Visão Geral
Em termos gerais, Sails.js é um gerador de códigos JavaScript que entrega, em poucos
minutos,
um protótipo
executável de uma Aplicação WEB do tipo backend robusta, segura e escalável.
O resultado é a capacidade de entregar páginas HTML5 + CSS + JavaScript dinâmicas ao Cliente Web.
Um protótipo Sails contém:
- Páginas de Cadastro de Novos Usuários, Login e Logout
- Funcionalidades para Recuperar e Modificar a Senha
- Página de FAQ
- Página de Termos de Serviço
- Página de Políticas de Uso de Dados
- Formulário de Solicitação de Suporte
- Capacidade nativa de internacionalização (i18n)
- Conexão com um Banco de Dados Local
Uma vez que o Protótipo tenha sido gerado, Sails permite ao desenvolvedor:
- gerar um Projeto (100%) código aberto, sem encapsulamentos ou acoplamento de bibliotecas proprietárias.
- utilizar comandos, diretamente no console de terminal, para:
- acessar a base de dados associada e manipulá-la;
- testar a eficácia de funções e métodos;
- criar páginas, controladores, funções JavaScript, helpers, hooks, scripts, actions,
modelos de dados, dentre
outros.
Sails.js segue o princípio de padrão sobre
configuração,
onde estão pré-definidos os parâmetros que definirão o seu comportamento, no entanto, se pode alterar
praticamente tudo que se desejar por arquivos de configuração.
Por exemplo:
- Sails espera encontrar as
classe de modelos de dados no diretório src/model e, uma vez criada uma Classe de Modelo, esta
pode
ser usada para inserir, atualizar, excluir ou ler dados do banco de dados, imediatamente, sem a necessidade de
declaração explicita.
Esta Classe de Modelo segue o padrão Mapeamento Relacional de Objetos, simplificando a maneira como os
desenvolvedores podem criar recursos.
- Sails espera encontrar os Controllers que responderão às requisições HTTP no
diretório
api/controllers e,
uma vez criado um Controllers este é carregado durante a inicialização do
sistema e estará
disponível como rota.
O Sails tem recursos de segurança integrados que ajudam a proteger as aplicações contra diversos tipos de
ataques.
O Sails tem uma comunidade ativa e em crescimento
que
fornece suporte e recursos para os desenvolvedores.
Como Funciona a Aplicação WEB Gerada ?
- Toda a magia começa quando o Navegador (Internet Browser) na estação de trabalho do cliente faz
uma
requisição (HTTP Request) ao servidor (ex. http://localhost/overview/index.html).
- O Core do Sails intercepta a requisição e confronta com as "Políticas de Segurança" definidas
no
arquivo
policies.js , retornando 401 - Forbidden, caso não autorizado.
- Uma vez autorizado o acesso, então o Sails compara o "Caminho da Requisição" com as "Rotas" definidas no
arquivo
routes.js, retornando 404 - Page Not Found, caso não encontre
correspondência.
- Encontrada a correspondência de "Rota", então o Sails identifica qual é o "Controlador"
( Controllers)
associado a esta e o executa para, em princípio, obter os dados que serão expostos na "Visão" que será
renderizada em seguida.
- Se o "Controlador" contém chamada ao Modelo de Dados, então este aguarda que o Banco de Dados retorne as
informações solicitadas para continuar.
- Uma vez que os dados tenham sido obtidos, pode então o "Controlador" enviar uma "Resposta" (HTTP
Response) ao Navegador.
Esta resposta pode ser do tipo JavaScript Object (JSON) ou uma resposta HTML completa.
- Se a opção do desenvoledor foi de uma "Resposta HTML", então ele informou qual a "Visão" deve ser
"Renderizada" (Ex. action.ejs). Esta visão, por padrão, será do tipo EJS (“Embedded JavaScript
Templating”). Você pode, se desejar, modificar o renderizador para qualquer outro compatível com Node.js
(em especial com o Express.js). Clique aqui
para saber como converter para o renderizador Pug
- O Core do Sails orquestrará a passagem dos "Dados Obtidos" pelo "Controlador" para o "Renderizador" EJS,
a construção da respectiva página HTML (resultado da renderização), a vinculação com os estilos (CSS
Style)
e o acoplamento deste HTML gerado com um
componente Vue 2 que incorpora o dinamismo JavaScript às páginas HTML.
- Visualize este processo no diagrama abaixo
Clique
aqui para seguir um
passo de construção de um protótipo
Clique
aqui para internacionalizar
um
protótipo
Helpers, Hooks, Policies & Scripts
Scripts são funções JavaScript que atuam como ferramentas versáteis para execução eventual ou
dependente de contexto. Um Script Sails segue o padrão Machinepack
(detalhado mais abaixo) e pode ser executado manualmente, na console, ou acionado dentro de um outro artefato
Sails.
Utilize:
sails generate script meu-script - para criar um novo Script como /scripts/meu-script.jssails run meu-script - para executar o Script no terminal (shell), a partir da raiz do protótipoawait require('<path relativo>/scripts/meu-script').fn() - para executar o Script dentro de outro artefato. Ex. dentro do
/config/bootstrap.js
Policies são funções JavaScript que atuam como ferramentas versáteis para autorização e
controle
de acesso.
Permitem executar alguma lógica antes que uma ação (mapeada no arquivo routes.js) seja
executada
para determinar
se a solicitação deve ou não continuar a processar.
O caso de uso mais comum para políticas é restringir determinadas ações apenas a usuários conectados.
Hooks são funções JavaScript que estendem o core Sails adicionando rotas ocultas,
ações
implícitas e/ou lógica de inicialização.
O método "chave" para a inicialização de um Hook deve ser nomeado como initialize()
Helpers são objetos JavaScript estruturados como machinepack controlados pelo
core Sails destinados ao uso Global ou repetitivo, ou
seja, todos os Helpers são acessíveis por todos os artefatos do Protótipo/Projeto. Uma vez criados,
pode-se invocá-los por meio do comando
await sails.helpers.nomeHelper.metodo(parametro1, parametro2) ou await
sails.helpers.nomeHelper.metodo.with({objeto})
Bootstrap é um inicializador de preparação. O arquivo config/bootstrap.js
é executado sempre que a aplicação é inicializada e nele já existem ações pré-definidas relevantes, tais
como a
identificação do ambiente de execução e criação automática de usuário.
Machinepacks são máquinas para interpretação de funções JavaScript autodocumentáveis e
previsíveis que seguem uma especificação,
escrita por Mike McNeil.
Uma máquina é caracterizada pelo seguinte:
- Ele deve ter um propósito claro, seja enviar um e-mail, emitir um Web Token JSON, fazer uma solicitação
de
busca, etc.
- Deve seguir a especificação, que torna as máquinas previsíveis para consumo via instalações npm.
- As máquinas são autodocumentáveis. Isso significa que pode simplesmente olhar para uma máquina e
saber
o que ela faz e o que ela executará (os parâmetros).
- As máquinas são rápidas de implementar.
- Como são autodocumentáveis, são também previsíveis.
Como já citado anteriormente, Helpers e Scripts são contruídos conforme a especificação
machinepack
E NÃO FUNCIONARÃO se forem escritos de outra forma, pois são interpretados pelo
core
do Sails. Observe que os Hooks e as Policies são funcões JavaScript padrão e não
seguem o
modelo
machinepack.
Helpers devem estar localizados no diretório \api\helpers para que sejam
acessíveis
em qualquer parte do seu aplicativo.
Hooks devem estar localizados no diretório \api\hooks para que funcionem e
serão
executados durante a inicialização.
Policies devem estar localizadas no diretório \api\policies para que sejam
localizadas
pelo core Sails enquanto executa o arquivo de configuracao config/policies.js,
durante a inicialização da aplicação.
Scripts devem estar localizadas no diretório \scripts para que sejam
localizados
pelo core Sails quando acionados pelo comando sails run meu-script,
seja manualmente ou por dentro de outro artefato..
Clique
aqui
para acessar exemplos funcionais que pode utilizar livremente
Inicialização de uma Aplicação Sails
Os seguintes passos são executados pelo core Sails durante a inicialização de uma
Aplicação:
- São carrregadas as configurações iniciais da Aplicação localizadas nos arquivos:
config/datastore.js, config/models.js, config/custom.js, e
config/local.j.
Este último "local" existe somente na estação de trabalho do desenvolvedor, pois é excluído do controle
de
versionamento (.git) por padrão e sobrescreve todos os demais, ou seja, havendo
repetição
de definição, vale a do local.js!
- São carregados todos os arquivos do tipo Helper, localizados no diretório
api/helpers/*
- São carregados e executados todos os arquivos do tipo Hook, localizados no diretório
api/hooks/*
- É carregado e executado o arquivo
config/bootstrap.js
- É carregado o arquivo
config/sessions.js para identificação dos parâmetros de Sessão do
Servidor HTTP
- É carregado o arquivo
config/http.js para identificação dos parâmetros de Funcionamento do
Servidor HTTP
- É inicializado o Servidor HTTP
- São mapeados os endpoints ou rotas acessíveis por requisições http (localizadas no diretório
api/controllers )
- É carregado o arquivo
config/socket.js para identificação dos parâmetros de Funcionamento
do
Servidor Web Socket
- É inicializado o Servidor Web Socket
- Ficam ativos os Listenings de Servidor para a "Escuta" de novas requisições HTTP, até que
ocorra um
erro ou uma parada intencional.
Cabe destacar que, se for identificado na inicialização que o "Ambiente de
Execução" (Environment) contém a variável NODE_ENV=production, então o conteúdo do arquivo
config/env/production.js
sobregravará as demais definições anteriores, ou seja, havendo repetição de definição, vale a do
production.js!
Actions & Controllers
As ações são responsáveis por responder a solicitações de um navegador ‘web’, aplicativo móvel
ou qualquer
outro sistema capaz de se comunicar com um servidor. Eles geralmente atuam como um intermediário entre os seus
modelos e visões e orquestram a maioria da lógica de negócios do seu projeto. Pode-se usar ações
para servir páginas da Web, lidar com envios de formulários, gerir solicitações de API de terceiros e
tudo mais. As ações são mantidas nos Controladores.
Controladores são arquivo posicionados no diretório api/controllers/*
(e gerenciados pelo core do Sails ) que contém ações no seu corpo.
As ações são vinculadas a rotas em seu aplicativo. Quando um agente do usuário solicita uma URL específica,
a ação vinculada a essa rota executa a lógica de negócios e envia uma resposta. Por exemplo, a rota GET
/hello em seu aplicativo pode estar vinculada a uma ação como:
async function (req, res) {
return res.send('Olá mundo!');
}
O conhecimento abaixo é extremamente relevante, mas este trabalho pode ser reduzido significativamente
pelo uso do recurso
Blueprints, nativo no
Sails.js!
Clique aqui para saber mais sobre Blueprints
Arquivos de Actions podem ser definidos de duas formas: Action
2 ou Clássico:
Action 2 é o modo mais moderno de se construir Actions no ambiente Sails, no
entanto, o modelo Clássico ainda é funcional e, em alguns casos, mais adequado.
Vantagens do modo Action 2
- Action 2 implica em uma ação por arquivo, enquanto Clássico permite mais de uma action e
torna a manutenção futura mais difícl;
- Você pode definir claramente os nomes e tipos dos parâmetros de solicitação esperados pela ação, e esses
parâmetros serão validados automaticamente antes que a ação seja executada;
- Todos os resultados possíveis da execução da ação (saídas) são claramente visíveis, sem a necessidade de
dissecar o código
- O código que escreve não depende diretamente de req e res, facilitando a reutilização ou abstração
de códigos auxiliares
- Actions2, já incorpora no seu corpo todo o dicionário de dados existente na requisição do navegador
(this.req).
Veja abaixo um exemplo de Action 2
module.exports = {
friendlyName: 'Church Search',
description: 'Pesquisa por igrejas estabelecidas em uma determinada cidade.',
inputs: {
nomeCidade: {
description: 'o nome da cidade pesquisada.',
// Se o valor recebido não for texto, Sails envia um `res.badRequest`, automaticamente
type: 'string',
// Se o valor esperado não for enviado, Sails envia um `res.badRequest`, automaticamente
required: true
},
// Se multiplas instancias atendem ao requisito, entao paginar sempre sera uma necessidade
page: { type: 'number', required: false },
size: { type: 'number', required: false }
},
exits: {
success: {
responseType: 'view',
viewTemplatePath: 'pages/church/church-search'
}
},
fn: async function ({nomeCidade, page, size}) {
// Procure igrejas cujo nome da cidade foi especificado na solicitação.
// Observe que não precisamos validar que 'nomeCidade' é um texto;
// o algorítimo da máquina faz isso por nós e retorna 'badRequest'
// se a validação falhar.
// No entanto, sendo page e size opicionais (required: false), melhor garantir que...
const page = page | 0;
const size = size | 10;
var churchs = await Church.find({ cidade: nomeCidade }).skip(page*size).limit(size);
// Torna o objeto churchs (neste caso um array) disponivel para uso pela View.EJS
return {churchs}
}
};
// Atenção: para implementação de todo o CRUD (Create, Read, Update e Delete),
// usando Action2, será preciso criar um arquivo 'controller/*.js'
// para cada uma das ações. Ex: church-create.js, church-read.js, church-update.js, church-delete.js
Veja abaixo um exemplo de Classic Action
/**
* ChurchController
*
* @description :: Server-side actions for handling incoming requests.
* @help :: See https://sailsjs.com/docs/concepts/actions
*/
module.exports = {
read: async function (req, res) {
// params são obtidos do PATH.
// Ex.: /api/v1/church/:id
// /api/v1/church/32
const id = req.params['id'];
await Church.find({id: id})
.then(
Church => {
res.render('pages/church/church-edit', {instance: Church});
}
).catch(err => {
res.notFound()
console.log(err.message)
});
},
// query são obtidos dos parametros.
// Ex.: /api/v1/church?page=0&size=10
readAll: async function (req, res) {
const page = req.query.page | 0;
const size = req.query.size | 0;
await Church
.find()
.skip(page*size)
.limit(size)
.then(list => res.view('pages/church/church-search', {list: list}))
.catch(err => console.log(err.message));
},
// body é obtido do corpo das requisições do tipo POST e PUT
// normalmente JSON ou x-form
update: async function (req, res) {
let Church = await Church.find({_id: req.params['id']});
return res.json(Church.updateOne(
{
version: req.body.version,
description: req.body.description
}
));
},
create: async function (req, res) {
await Church.create(req.body).then(
Church => res.json(Church)
).catch(err => console.log(err));
},
};
Diferença no roteamento de Actions 2 e Clássicos
// Action 2 - Uma acao por arquivo!
'GET /caminho': {action: 'acao'},
// neste caso a função fn ({}) do arquivo api/controllers/acao.js
// Clássico - uma ou mais acoes por arquivo!
'GET /caminho': 'NomeController.get',
// neste caso a função get(req, res) do arquivo api/controllers/NomeController.js
'PUT /caminho': 'NomeController.put',
// neste caso a função put(req, res) do arquivo api/controllers/NomeController.js
Captura de Parâmetros Actions 2 e Clássicos
Para uma rota do tipo:
POST /altera-texto/num/:num/assunto/:ass/date/:dat?limite={lim}
Uma requisição:
POST /altera-texto/num/1/assunto/teste/date/2023-12-30?limite=10
{
objeto: { sumario: `Sumario do texto`, detalhe: `Detalhes do texto enviado` }
}
teriamos:
// Action 2:
inputs: {
num: {type: 'number', required: true },
ass: {type: 'string', required: true },
dat: {type: 'string', required: true },
limite: {type: 'number', required: false },
objeto: {type: 'ref', required: false },
}
...
fn: async function ({num, ass, dat, limite, objeto}){
const numero = num
const assunto = ass
const data = new Date(dat)
const lim = limite | 0
const objetoJSON = objeto | { sumario: `-`, detalhe: ''}
console.log('Sumario: '+objetoJSON.sumario)
}
// Classic Action
fn: async function (req, res){
const numero = req.param['num']
const assunto = req.param['ass']
const dataTexto = new Date(req.param['dat'])
const limite = req.query.limite | 0
const objetoJSON = req.body.objeto | { sumario: `-`, detalhe: ''}
console.log('Sumario: '+objetoJSON.sumario)
}
// Observe que para o Action 2, tanto faz se foi um parâmetro de Path (param) ou um Parâmetro do
// Query do Request (query) ou corpo da requisição (body), tudo será tratado pelo `inputs`.
// Observe que os valores não obrigatórios (required: false OU ?parametro=valor) devem ser testados,
// pois podem estar nulos em tempo de execução.
Criando Actions
- Para criar uma única Action 2:
sails generate action nome-da-action;
- Para criar uma Action 2 associada com uma View (EJS):
sails generate page nome-da-page.
Neste caso será criado um arquivo controllers/view-nome-da-page.js,
um outro views/pages/nome-da-page.ejs e
outro assets/js/pages/nome-da-page.page.js (Vue 2);
- Para criar uma ou mais Action Classic:
sails generate controller nome-do-arquivo
e adicionar as actions dentro dele manualmente;
- Para criar uma Action Classic e um Model de mesmo nome:
sails generate api nomemodel.
Neste caso, serão criados: controllers/NomemodelController.js e models/Nomemodel.js.
Recomenda-se implementar 5 funções para os 5 métodos padrão RESTful: get, post, put, path e delete.
(ou deixe como está e ative a ferramenta Rotas Blueprints RESTful )
Atenção! Nenhum dos comandos de geração de Actions acima irá
adicionar as respectivas
rotas dentro dos arquivos config/routes.js.
Se você está utilizando blueprints, o
Sails resolve a rota pra você, senão:
Você terá que inserir manualmente!
O
Core do
Sails.js vai tentar `adivinhar` qual
HTTP Method
você está tentando criar na sua action2, então, para ajudá-lo, você pode comandar...
- sails generate action create-acao - para obter uma rota 'POST /api/v1/create-acao': { action:'create-acao'},
- sails generate action get-acao - para obter uma rota 'GET /api/v1/get-acao': { action:'get-acao'},
- sails generate action update-acao - para obter uma rota 'PATH /api/v1/update-acao': { action:'update-acao'},
- sails generate action destroy-acao - para obter uma rota 'DELETE /api/v1/destroy-acao': { action:'destroy-acao'},
Bem-vindo ao Sails.js Tech Brasil!
