Pacote de programação para disciplinas de desenvolvimento web back-end, utilizando Javascript com Nodejs + Express. O Objetivo é servir de exemplo para a elaboração de uma API para comunicar dados em JSON a respeito de uma modelagem. É uma API RESTful com validações de schemas JSON (Ajv) e para autenticação utiliza JWT Token (jsownwebtoken). Na persistência de dados, se utiliza o ORM Sequelize com banco de dados em MySQL.

Este projeto faz parte de uma série de aprendizado em APIs. Nesta mesma série, você pode acessar o mesmo projeto implementado com PHP e Lumen.

• Nodejs 18.16.x;
• npm 9.5.x;
• Express 4.18.2
• MySQL 8.0;
• Ajv 8.12.0;
• cors 2.8.5;
• jsonwebtoken 9.0.1;
• mysql2 3.6.0;
• sequelize 3.6.0.

Se você é docente da área, pode entrar em contato para obter slides e dicas sobre o desenvolvimento de aulas com este projeto.

• Utilização do framework Express como base;
• Validação de documentos JSON com Ajv;
• ORM Sequelize para criação/alteração de banco de dados relacionais, incluindo relacionamento entre tabelas.
• Aplicações de configurações sobre CORS e Bearer Tokens;

Este projeto faz referência a uma modelagem hipotética de um game, da relação entre um jogador e seus equipamentos.

1. Ambiente local de desenvolvimento:

• Se Windows: instalações node e npm e MySQL;
• Se Linux: instalações node e npm e MySQL;

2. Para acessar o banco de dados, caso não queira manipular o BD via linha de comando, pode utilizar um ou mais softwares clientes, como MySQL Workbench ou DBeaver.

3. Para usuários Windows recomenda-se sempre utilizar o Git Bash for Windows a fim de executar comandos similares ao estilo linux das aulas. Pode usar o terminal do Visual Studio Code.

O projeto segue uma estrutura em MVC com arquivos individuais de rotas e validadores JSON:

• /app
  • /commons: helpers reutilizáveis pela aplicação;
  • /controllers: os Controllers da aplicação;
  • /middlewares: reúne todos os middlewares da aplicação;
  • /models: reúne as Models e o inicializador index para o ORM;
  • /routes: arquivos de rotas da aplicação;
  • /schemas: os esquemas JSON utilizados para validações na aplicação;
• modelagem: documentações sobre o banco de dados.
• app.js: componente de inicialização do projeto.
• config.js: reúne propriedades configuráveis globais da aplicação.

1. Fazer o download/fork/cópia deste repositório.
2. Instalar via npm o projeto:

dev@pc:~$ cp .env.example .env
dev@pc:~$ npm install

3. Verifique se o primeiro comando resultou na cópia correta do .env.example para .env. Em seguida preencha corretamente todas as variáveis de ambiente do arquivo .env.

4. Para executar o projeto, acesse o diretório da aplicação e execute um dos comandos abaixo:

dev@pc:~$ npm run dev
#ou
dev@pc:~$ npx nodemon

Ao receber documentos JSON do cliente, este projeto utiliza a biblioteca Ajv para avaliar se na estrutura do documentos os dados encontram-se adequados conforme a necessidade do back-end. Para criar um schema de validação verifique exemplo em app/schemas. Poderá especificar regras de campos obrigatórios, tipos de dados que cada campo deve ser, dentre outros.

Para utilizar o validador automatizado, no controller é necessário realizar a chamada do objeto do Ajv, informar o objeto de schema de validação (item anterior). Depois é necessário apenas informar o conjunto de dados recebido (pode ser o corpo da requisição) ao validador para que o mesmo avalie toda a estrutura. Um exemplo pode ser consultado no método create em app/controllers/JogadorController.

Este projeto utiliza o ORM Sequelize, onde por meio do arquivo app/models/conexao.js é realizada a conexão com o banco de dados. A parametrização do Sequelize consta em config.js.

Cada model do projeto (app/models) é uma classe com dados privados (comum em JS). Entretanto, na mesma classe, a Model do Seuqelize para cada entidade é inicializada. A ideia é que métodos comuns do ORM como create, update, dentre outros, sejam acopladas a classe comum da model. Isto facilita caso futuramente seja necessário trocar o Sequelize por outro framework. Cada model téncicamente exporta a sua classe e a model sequelize conectada, respectivamente.

Em app/models/index.js é realizada a importação das models e a sincronização com banco de dados. A sincronização verifica se existe a tabela da model criada no BD e caso não existir, cria as tabelas necessárias. Em app/models/relations.js são implementados e configurados os relacionamentos entre as models (o que pode ser também feito dentro de cada classe), a partir destas configurações, quando o Sequelize for criar as tabelas, os relacionamentos também serão gerados.

Para a utilização da API é necessário ter um token de acesso que deverá ser enviado pelo lado do cliente, via cabeçalho da requisição, para esta API autorizar o consumo de dados. No cabeçalho deve ser especificado Bearer token, onde token é gerado para um cliente conhecido. Um middleware em app/middlewares tem por responsabilidade ser o intermediário, avaliando se existe o token na requisição e se o mesmo é válido.

O projeto segue o padrão de implementação de tokens via JWT Token. É necessário que um cliente que deseja utilizar a API faça o cadastro para se tornar um cliente conhecido e autorizado. Ao fazer o cadastro o token é gerado e retornado ao cliente. Por padrão cada token tem um tempo de validade definido em config.js (jwt.expiration).

Também existe a implementação de login para os clientes, ao enviar e-mail e senha corretos para esta API, a mesma verificará as credenciais e irá gerar um token. No final desta mesma requisição o cliente deverá receber um token de acesso para utilizar normalmente a API.

Express

Sequelize ORM

npm

Serão aceitas atualizações de pacotes, correções de bug e melhorias didáticas. Novas funcionalidades podem serem debatidas e adicionadas ao projeto se verificado necessidade do desenvolvimento de back-end de um jogo completo.