Este projeto está arquitetado no framework Nestjs, leia a documentação para mais detalhes ou veja o resumo existente na sessão Configurações > Nestjs.
IMPORTANTE existe uma demo publicada no heroku clicar aqui, o primeiro acesso pode levar até 30s para ser estabelecido devido a conta ser gratuita.
- Conteúdo
- Configurações
- Dotenv
- Scripts
- Docker
- Tests automatizados
- Typescript
- VSCode
- Nestjs
- Sobre o projeto
- Configurações
Dotenv (click to show)
O projeto depende do arquivo .env que deve existir na pasta raiz. Este arquivo não é versionado apesar do arquivo .env.example ser.
Certifique-se de possuir um .env na raiz do projeto antes de executá-lo para que as constantes em src/app.vars.ts sejam carregadas.
DETALHAMENTO
| Variável | Descrição |
|---|---|
| NODE_ENV | Define o ambiente de execução. Recebe "Production" ou "Development". Controla funcionalidades da aplicação. |
| APP_PORT | Define a porta de acesso ao serviço. |
| APP_VERSION | Define a versão atual do projeto. |
| APP_VERSION_PREFIX | Define o prefixo da versão, default v. |
| APP_CONTAINER_NAME | Define o nome do container que será gerado pelo docker. |
| MYSQL_DATABASE | Define o nome do banco de dados. |
| MYSQL_ROOT_PASSWORD | Define a senha do usuário root no mysql. |
| MYSQL_PORT | Define a porta usada pelo banco de dados. |
| JWT_SECRET | Define a palavra-secreta usada para gerar o token de acesso. |
| JWT_SECRET_EXPIRES_IN | Define o tempo de vida do token. |
| JWT_SECRET_REFRESHTOKEN_EXPIRES_IN | Define o tempo de vida do refresh-token. |
| DATABASE_URL | Define a url de acesso ao banco de dados. |
Scripts (click to show)
O projeto conta com diversos scripts de linha de comando para uso via terminal, i.e., yarn <SCRIPT> ou npm run <SCRIPT>
DETALHAMENTO
| Script | Descrição |
|---|---|
| build | Compila o projeto gerando na pasta dist os scripts para produção |
| build:tsc | Roda o compilador do typescript a partir do tsconfig.build para verificar possíveis erros |
| format | Formata automaticamente o código com o padrão definido pelo prettier |
| format:check | |
| lint | Roda o ESLINT para conferir o styleguide do código, corrigindo automaticamente erros simples |
| start | Inicia o servidor sem hot auto-reload |
| start:dev | Inicia o servidor de desenvolvimento com hot auto-reload |
| start:debug | Inicia o servidor de desenvolvimento com hot auto-reload em modo debug |
| start:debug:docker | Usado pelo docker para iniciar o servidor de desenvolvimento em modo debug |
| start:prod | Inicia o entrypoint gerado no build em modo produção |
| test | Executa todos os testes unitários encontrados na aplicação |
| test:watch | Inicia o servidor de teste e ativa o hot auto-reload apenas para o testes modificados |
| test:ci | Gera o relatório de cobertura dos testes no código-fonte |
| test:staged | Usado com o husky para interromper o pre-commit no primeiro test que falhar |
| test:debug | Precisa que o start:dev esteja executando, levanta o modo debug nesse ambiente para uma única execução |
| test:e2e | Executa todos os testes de integração |
| test:clear | Limpa o cache de arquivos do jest |
| update:packages | Inicia uma varredura para verificar bibliotecas do sistema que estejam desatualizadas |
| prisma | Executa o prisma local instalado no projeto |
| prisma:studio | Sobe o serviço de client do banco de dados |
| prisma:db:migrate | Cria novas migrações com base no schema.prisma |
| prisma:db:push | Migra as tabelas para o banco de dados |
| prisma:db:seed | Popula as tabelas com dados de test |
Docker 🐳 (click to show)
Um Dockerfile está presente na raiz do projeto, assim como um docker-compose.yml com uma configuração mínima viável para a execução do mesmo.
No docker-compose.yml há referência para uma rede interna que permitará conectar diversos container de serviços que venham a existir no projeto.
Em uma máquina com Docker e Docker Compose instalados, basta configurar seu arquivo .env e executar
docker-compose up # Comando travará o terminal
# ou
docker-compose up -d # Comando executará em segundo planopara iniciar a aplicação.
A execução de testes e demais comandos listados na sessão Scripts pode ser feita a partir de uma nova sessão dentro do container
docker-compose exec api /bin/bash # Inicia uma sessão dentro de um container já em execução
# ou
docker-compose run --rm api /bin/bash # Cria um container novo e inicia uma sessãoIMPORTANTE
O comando padrão do container de desenvolvimento definido no docker-compose.yml é o start:debug:docker que já irá levantar o serviço em modo de debug caso haja necessidade desse suporte.
Um Makefile está presente na raiz do projeto, o intuito é facilitar a execução dos comandos Docker executados a partir de um terminal de comandos
make start # Inicia o servidor do nestjs em modo debugmake bash # Abre o terminal interativo do container em execuçãoTests Automatizados (click to show)
Com exceção dos tests de integração, os demais tests são executados em uma instancia do jest configurada via package.json. O jest está preparado para entender todos os alias-path existentes no projeto
"jest": {
...
"moduleNameMapper": {
"~/(.*)": "<rootDir>/$1"
}
}Quando o test de cobertura for executado, arquivos da pasta config, ou tipo index.ts, .d.ts e outros necessários para levantar o serviço não farão parte da cobertura, conforme definição
"jest": {
...
"collectCoverageFrom": [
"**/*.(t|j)s",
"!**/*.d.ts",
"!<rootDir>/*.ts",
"!<rootDir>/**/index.ts",
"!<rootDir>/**/*.module.ts",
"!<rootDir>/config/**/*"
]
}Quando for necessário usar o modo de debug, o programador deve optar por uma das seguintues opções para poder fazer os breakpoints no sistema
Serviço em ambiente local usar a opção:
Debug ServerServiço rodando no container docker usar a opção:
Docker: Debug ServerTypescript (click to show)
Esta arquitetura utiliza Typescript como linguagem de codificação. Todas as features disponíveis pelo framework estão em Typescript e são altamente extensiveis, o que torna todo o código produzido super flexível para o desenvolvimento de softwares.
Apesar de adicionar uma estrutura diferente há sintaxe do javascript e que muitos programadores poderão não estar habitualidos a usar, TS trás vários benefícios a codificação:
- Suporte intellisense para prover auto-completo, informações de parametros, informações rápidas, lista de membros, etc., tudo a nível de IDEs de código-fonte.
- Melhor tooling para debug do desenvolvedor, fazendo verificações de erros e garantias de tipagens ao codificar.
- Adição de suporte para design patterns como Abstract, Factories, Decorators, Singles, etc., para facilitar a gerência das dependências de forma padronizada e reutilizável.
- Fornece um código mais confiável e explícito, menos sucetível a erros durante a programação.
- Entre outros.
O projeto já possui um linter e o prettier configurados para garantir boa parte da formatação desejada no padrão de código definido. Arquivos de configuração .prettierrc e .eslintrc.js explicitam as configurações que dentre as poucas decisões definem: utilização obrigatória de aspas SIMPLES e a não-utilização de ponto e vírgula.
Um arquivo .editorconfig também dita as configurações acerca da formatação de arquivos: identação com 2 espaços, com codificação em UTF-8 e com linha em branco ao final dos arquivos.
VSCode (click to show)
O projeto trabalha com aspas simples nas strings e ponto-e-virgula para definir o final de cada linha conforme o padrão airbnb, entretanto, toda essa formatação é feita pelo prettier sempre que um arquivo é salvo.
// .vscode/settings.json
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[yaml]": {
"editor.defaultFormatter": "redhat.vscode-yaml"
},
"editor.codeActionsOnSave": {
"source.fixAll": true,
"source.organizeImports": true
},
}IMPORTANTE
O projeto conta com suportar alias-path, a raiz ./ está configurada para ~/ conforme definição
// tsconfig.json
{
"compilerOptions": {
...
"paths": {
"~/*": ["*"]
},
...
}
}O prettier está preparado para fornecer os imports de cada recurso obedecendo alias-path, i.e., import { RootService } from '~/root/root.service'; conforme definição
// .vscode/settings.json
{
"typescript.preferences.importModuleSpecifier": "non-relative",
}IMPORTANTE
Específico para ambiente Windows
{
"files.eol": "\n",
"editor.tabSize": 2
}Nestjs (click to show)
Nestjs adota extensivamente conceitos como a Injeção de Dependência e a Inversão de Controle. Providers é um dos principais conceitos dentro do framework, que são basicamente classes anotadas que podem se comportar de diferentes formas (services, repositories, factories, helpers, ...).
A ideia principal é que um provider pode injetar uma ou mais dependências. O framework possui uma gerência em run-time de um design pattern bem comum, que é a de injeção de dependência. O Nest baseou-se profundamente no padrão adotado pelo Angular e pode ser melhor explorado na sua documentação.
Isso permite adotar estratégias SOLID-like entre outras que, não necessariamente precisam ser programadas.
Nest faz uso da estrutura de módulos para organizar seus projetos, um módulo base é encontrado dentro da pasta src com o nome de arquivo app.module.ts, todo novo módulo deve ser adicionado a sua lista de arquivos para importação.
Este projeto está configurado para trabalhar com a estrutura de módulos e um módulo root pode ser encontrado dentro da pasta src como exemplo.
No terminal faça:
yarnNote: Após a instalação deve-se migrar o esquema de tabelas e os dados de teste para o banco de dados, faça:
#> migra as tabelas
yarn prisma:db:push
#> popula com dados de teste
yarn prisma:db:seedIMPORTANTE: É possível conectar-se ao banco de produção usado no ambiente do Heroku apartir de qualquer client de conexão de MySql.
Dados de acesso:
| Param | Value |
|---|---|
| HOST | us-cdbr-east-05.cleardb.net |
| USER | bc566598fb7dd8 |
| PASSWORD | ed4199d1 |
| DBNAME | heroku_437694f837420de |
OBS Para mais informações veja o valor presente na variável DATABASE_URL
No terminal faça:
yarn test:ciNote: O resultado deve ser igual a imagem:
Para subir o docker do projeto rode:
docker-compose upNa linha de comando faça:
yarn start:devNOTA: caso tenha dúvidas veja a sessão Configurações > Dotenv & Configurações > Scripts
#GET /- Url sem serventia =P.
#POST /v1/auth- Rota não autenticada, devolve as credenciais de acesso de um usuário.#POST /v1/auth/signup- Rota não autenticada, para registro de novos usuários.
#GET /v1/users- Rota autenticada, devolve uma lista de usuários paginados.#POST /v1/users- Rota autenticada, registra novos usuários.#GET /v1/users/{id}- Rota autenticada, devolve um usuário pelo id.#PATCH /v1/users/{id}- Rota autenticada, atualiza um usuário pelo id.#DELETE /v1/users/{id}- Rota autenticada, remove um usuário pelo id.
#GET /v1/products- Rota autenticada, devolve uma lista de produtos paginados.#POST /v1/products- Rota autenticada, registra novos produtos.#GET /v1/products/{id}- Rota autenticada, devolve um produto pelo id.#PATCH /v1/products/{id}- Rota autenticada, atualiza um produto pelo id.#DELETE /v1/products/{id}- Rota autenticada, remove um produto pelo id.
Note: Toda a documentação está disponível via Swagger, você pode clicar aqui para acessar.
Copyright (c) 2022-present