Sails.js Tech Brasil • Documentação & Guias

Passo a passo com Blueprints Sails.js

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.

Se esta é sua primeira vez aqui, recomendamos a leitura dos conteúdos abaixo antes de continuar:

Pré-requisitos

Node.js instalado na estação de trabalho (https://nodejs.org)
Pré conhecimento do básico da linguagem de programação JavaScript
Uma IDE de desenvolvimento qualquer instalada (IntelliJ, Visual Code, Eclipse, Netbeans, Kdeveloper, etc.)

Primeira Etapa: Protótipo Raiz (5 min)

Instalação do Sails.js
npm i sails -g

Criando o protótipo
sails new primeiro-prototipo-blueprint
Quando perguntado, responda: 2. Empty

 Choose a template for your new Sails app:
 1. Web App  ·  Extensible project with auth, login, & password recovery
 2. Empty    ·  An empty Sails app, yours to configure
 (type "?" for help, or <CTRL+C> to cancel)
? 2

Navegando para o diretório raiz do Protótipo
cd primeiro-prototipo-blueprint
Instalação da biblioteca Axios
npm install para uso do protótipo

Executando o Primeiro Protótipo pela primeira vez
sails lift você verá:

 info: Starting app...

 info: Initializing project hook... (`api/hooks/custom/`)
 info: Initializing `apianalytics` hook...  (requests to monitored routes will be logged!)
 info: ·• Auto-migrating...  (alter)
 info:    Hold tight, this could take a moment.
 info:  ✓ Auto-migration complete.

debug: Running v0 bootstrap script...  (looks like this is the first time the bootstrap has run on this computer)
 info:
 info:                .-..-.
 info:
 info:    Sails              <|    .-..-.
 info:    v1.5.18             |\
 info:                       /|.\
 info:                      / || \
 info:                    ,'  |'  \
 info:                 .-'.-==|/_--'
 info:                 `--'-------'
 info:    __---___--___---___--___---___--___
 info:  ____---___--___---___--___---___--___-__
 info:
 info: Server lifted in `C:\Users\rogeriorfs\git\passo-a-passo`
 info: To shut down Sails, press <CTRL> + C at any time.
 info: Read more at https://sailsjs.com/support.

debug: -------------------------------------------------------
debug: :: Mon Jul 17 2023 08:15:43 GMT-0300 (Horário Padrão de Brasília)

debug: Environment : development
debug: Port        : 1337
debug: Local       : http://localhost:1337
debug: -------------------------------------------------------

Utilize o navegador (browser) de sua preferência e navegue para http://localhost:1337. O navegador deve apresentar algo do tipo:
Se uma nova página se abriu, então continue na próxima etapa

Segunda Etapa: Configuração

Localize e abra o arquivo /config/blueprints.js. Você deve ver algo como:

 /**
 * Blueprint API Configuration
 * (sails.config.blueprints)
 *
 * For background on the blueprint API in Sails, check out:
 * https://sailsjs.com/docs/reference/blueprint-api
 *
 * For details and more available options, see:
 * https://sailsjs.com/config/blueprints
 */

module.exports.blueprints = {

  /***************************************************************************
  *                                                                          *
  * Automatically expose implicit routes for every action in your app?       *
  *                                                                          *
  ***************************************************************************/

  // actions: false,


  /***************************************************************************
  *                                                                          *
  * Automatically expose RESTful routes for your models?                     *
  *                                                                          *
  ***************************************************************************/

  // rest: true,


  /***************************************************************************
  *                                                                          *
  * Automatically expose CRUD "shortcut" routes to GET requests?             *
  * (These are enabled by default in development only.)                      *
  *                                                                          *
  ***************************************************************************/

  // shortcuts: true,

};

Habilite todas as opções (action, rest e shortcuts devem estar 'true'), por enquanto.
Agora crie uma API de dados Usuario como o comando sails generate api Usuario e certifique-se de que foram criados um aquivo /models/Usuario.js e outro /controllers/UsuarioController.js.
Antes que o Sails pergunte, altere também o valor do atributo "migrate" do aquivo /config/models.js para o 'alter', permitindo que o sails crie e modifique seu banco de dados.
Reinicie o protótipo com sails lift.

Terceira Etapa: Teste dos atalhos

Vamos começar pela Rota de Atalho, pois ela permite testar a integração entre o protótipo e o banco de dados diretamente do navegador:

Para adicionar dados aos /models/Usuario.js: digite no navegador http://localhost:1337/usuario/create?nome=Luiz Claudio&idade=24&time=Flamengo. Pressione Enter

O resultado deve ser algo do tipo

{
  "nome": "Luiz Claudio",
  "idade": "24",
  "time": "Flamengo",
  "createdAt": 1790433705642,
  "updatedAt": 1790433705642,
  "id": 1
}

Para adicionar um segundo registro de dados aos /models/Usuario.js: digite no navegador http://localhost:1337/usuario/create?nome=Paulo Silva&idade=42&time=Vasco. Pressione Enter

Para listar os dados do /models/Usuario.js: digite no navegador http://localhost:1337/usuario. Pressione Enter. Você deve ver:

 [
  {
    "nome": "Luiz Claudio",
    "idade": "24",
    "time": "Flamengo",
    "createdAt": 1790433705642,
    "updatedAt": 1790433705642,
    "id": 1
  },
  {
    "nome": "Paulo Silva",
    "idade": "42",
    "time": "Vasco",
    "createdAt": 1790433911411,
    "updatedAt": 1790433911411,
    "id": 2
  }
]

Agora vamos obter os dados de um registro específico, o primeiro registro criado (1). Digite http://localhost:1337/usuario/find/1. Apareceu o Flamenguista!
Para obter os dados do segundo registro criado (2), digite http://localhost:1337/usuario/find/2. Apareceu o Vascaíno!
Vamos modificar o time do segundo registro com http://localhost:1337/usuario/update/2?time=Flamengo

E agora vamos consultar todos os usuários flamenguistas: http://localhost:1337/usuario/find?time=Flamengo

 [
  {
    "nome": "Luiz Claudio",
    "idade": "24",
    "time": "Flamengo",
    "createdAt": 1790433705642,
    "updatedAt": 1790433705642,
    "id": 1
  },
  {
    "nome": "Paulo Silva",
    "idade": "42",
    "time": "Flamengo",
    "createdAt": 1790433911411,
    "updatedAt": 1790459260651,
    "id": 2
  }
]

Para uma lista mais completa dos Atalhos visite Blueprints (Alicerces de Desenvolvimento)

Quarta Etapa: Rotas de Ação Implícitas

Rotas de Ação Implicitas é o termo para a capacidade do Sails de inferir as rotas de ação (request) a partir da estrutura de diretorios. Vejamos:

Vamos criar uma rota teste chamada 'lista-flamenguistas'. Para quer o Sails localize a ação é necessário que exista um Controller (tipo 1) no diretório /api/controllers
Digite sails generate controller listaFlamenguistas (a estrutura de comando sails não permite o uso de '-' para nomes de objetos). Você verá como resultado algo como:
```
            info: Created a new controller ("listaFlamenguistas") at api/controllers/ListaFlamenguistasController.js!
        
```

Localize e edite o arquivo criado para que se pareça com:

 /**
 * ListaFlamenguistasController
 *
 * @description :: Server-side actions for handling incoming requests.
 * @help        :: See https://sailsjs.com/docs/concepts/actions
 */

module.exports = {
  count: async function (req, res) {
    // Dizendo ao Sails que queremos usar o modelo Usuario.js (sim! tudo minúsculo!)
    const Usuario = sails.models.usuario;
    // Dizendo ao Sails (Waterline) que somente os flamenguistas devem ser contados.
    const count = await Usuario.count({time: 'Flamengo'});
    return res.json({
      counter: count
    });
  }

};

Navegue para http://localhost:1337/listaFlamenguistas/count e confira o resultado. O Sails reconheceu o método dentro do controller sem a necessidade de declaração explicita de rota.
```
{
  "counter": 2
}
        
```

Se o desenvolvedor decidir se utilizar de Rotas Implicitas de forma extensiva, recomendamos o uso da função/método index():

 module.exports = {
  count: async function (req, res) {
    // Dizendo ao Sails que queremos usar o modelo Usuario.js (sim! tudo minúsculo!)
    const Usuario = sails.models.usuario;
    // Dizendo ao Sails (Waterline) que somente os flamenguistas devem ser contados.
    const count = await Usuario.count({time: 'Flamengo'});
    return res.json({
      counter: count
    });
  }, // use vírgula para separar os métodos no controller!

  index: async function (req, res) {
    return res.json({
      message: 'Hello World!'
    });
  }

};

Reinicie a aplicação e navegue para http://localhost:1337/listaFlamenguistas (sem o /count). Observe que a mensagem Hello World! é exibida.
Ficou claro? A função/método index() será assumida como o método padrão sempre que a rota raiz for informada.

Para fixar o entendimento das Rotas Implícitas:

Navegue para http://localhost:1337/listaFlamenguistas. A mensagem Hello World! será retornada
Navegue para http://localhost:1337/listaFlamenguistas/index. A mensagem Hello World! será retornada
Navegue para http://localhost:1337/listaFlamenguistas/count. A contagem de flamenguistas será apresentada
Navegue para http://localhost:1337/listaFlamenguistas/list. Uma mensagem de erro será apresentada, pois esta rota (função/método) não existe.

Quinta Etapa: Ação RESTFul padrão

O Sails permite a criação de rotas RESTFul padrão (verbos GET, POST, PUT, PATCH, DELETE), que são rotas que seguem um padrão específico para facilitar a criação de APIs RESTful. Essas rotas são criadas automaticamente pelo Sails, sem a necessidade de escrever código adicional.

Habilite o atributo "rest" do arquivo /config/blueprints.js. (Se você está seguindo o passo-a-passo desde o início, provavelmente já fez isso!)
No navegador, digite http://localhost:1337/usuario. A Lista de Usuários será retornada! Funcionou, pois o navegador sempre envia o Verbo HTTP GET, mas não funcionará para os demais Verbos HTTP
Para testar os outros Verbos será necessário usar um cliente HTTP, como o Postman ou o Insomnia.
Uma vez que tenha instalado o Postman ou o Insomnia, crie uma nova requisição HTTP e configure-a para enviar:
- GET localhost:1337/usuario/1 - Para acessar os dados do primeiro usuário
- POST localhost:1337/usuario?nome=Maria Tereza&idade=24&time=Palmeiras - Para criar um palmeirence
- PATCH localhost:1337/usuario/1?idade=34 - Para alterar a idade de um usuário
- DELETE localhost:1337/usuario/2 - Para remover da base de dados um registro de usuário
Para saber mais sobre como estruturar rotas RESTful, consulte nossa página Blueprints

Atenção: Certifique-se de que o servidor Sails esteja em execução antes de enviar as requisições.
Durante o uso de Blueprints não há validação de tipos, ou seja, o comando PATCH localhost:1337/usuario/1?idade=ND irá introduzir uma String em um campo que, por definição, seria um número!

Para resolver isso, defina explicitamente os campos no Objeto Model, nesse caso o Objeto models/Usuario.js

/**
 * Usuario.js
 *
 * @description :: A model definition represents a database table/collection.
 * @docs        :: https://sailsjs.com/docs/concepts/models-and-orm/models
 */

module.exports = {

  attributes: {

    //  ╔═╗╦═╗╦╔╦╗╦╔╦╗╦╦  ╦╔═╗╔═╗
    //  ╠═╝╠╦╝║║║║║ ║ ║╚╗╔╝║╣ ╚═╗
    //  ╩  ╩╚═╩╩ ╩╩ ╩ ╩ ╚╝ ╚═╝╚═╝

    idade: {
      type: 'number',
      defaultsTo: 0
    }

    //  ╔═╗╔╦╗╔╗ ╔═╗╔╦╗╔═╗
    //  ║╣ ║║║╠╩╗║╣  ║║╚═╗
    //  ╚═╝╩ ╩╚═╝╚═╝═╩╝╚═╝


    //  ╔═╗╔═╗╔═╗╔═╗╔═╗╦╔═╗╔╦╗╦╔═╗╔╗╔╔═╗
    //  ╠═╣╚═╗╚═╗║ ║║  ║╠═╣ ║ ║║ ║║║║╚═╗
    //  ╩ ╩╚═╝╚═╝╚═╝╚═╝╩╩ ╩ ╩ ╩╚═╝╝╚╝╚═╝

  },

};

Se o campo foi definido explicitamente como indicado acima, a tentativa de inserir texto na idade retornara o seguinte erro:

 {
  "code": "E_INVALID_VALUES_TO_SET",
  "details": "Could not use specified `idade`.  Specified value is not a valid `idade`.  1 error validating value: \n • Specified value (a string: 'ND') doesn't match the expected type: 'number'",
  "message": "The server could not fulfill this request (`PATCH /usuario/1`) due to a problem with the parameters that were sent.  See the `details` for more info.  **The following additional tip will not be shown in production**:  Tip: Check your client-side code to make sure that the request data it sends matches the expectations of the corresponding attributes in your model.  Also check that your client-side code sends data for every required attribute."
}

Este é um resumo de como utilizar Blueprints para acelerar o desenvolvimento de seu protótipo. Para mais informações, visite o site oficial do Sails.js

📚 Para Saber Mais & Continuar Aprendendo:

🌐 Comunidades Sails.js

🎓 Cursos em Português

💬 Fale com Especialistas