Aula 5.8 - Aula 5.8 — Compilação e projeto final

Identificação

Módulo: 5 — Node.js, NestJS e APIs
Duração: 2 horas
Tipo: oficina integradora
Entrega: API REST documentada, testada e reproduzível
Laboratório: ../exemplos/aula-5.8/index.html

Introdução

Chegamos ao fechamento do primeiro back-end do curso. As aulas anteriores criaram processo, módulos, rotas, DTOs, validação, erros, configuração, documentação, registros e testes. Agora precisamos verificar se essas partes formam uma entrega reproduzível.

Compilar significa transformar o TypeScript em JavaScript que o Node.js consegue executar. Publicar significa colocar o resultado em um ambiente onde a aplicação ficará disponível. Compilar não publica automaticamente.

O aluno não precisa de uma VPS para concluir este módulo. Todo o projeto pode ser executado localmente no Windows. XAMPP pode continuar servindo as páginas estáticas e o Angular, enquanto a API NestJS executa em outro processo e outra porta.

Nesta aula responderemos:

npm run build inicia a API?
precisamos copiar src para produção?
XAMPP executa NestJS?
o Git atrapalha a publicação?
é obrigatório usar VPS para concluir o curso?
o que deve entrar no arquivo README?
quais evidências demonstram que o módulo foi concluído?

Objetivos

Ao concluir a aula, você será capaz de:

diferenciar desenvolvimento, compilação, execução e publicação;
gerar JavaScript a partir do projeto NestJS;
inspecionar o diretório de saída;
executar o resultado compilado;
preparar configuração sem incluir segredos;
organizar scripts reproduzíveis;
criar um README para Windows;
auditar contrato, testes, registros e segurança;
explicar a convivência entre XAMPP, Angular, NestJS e MySQL;
apresentar e defender o projeto final do módulo.

Pré-requisitos

aulas 5.1 a 5.7 concluídas;
Node.js e npm instalados;
terminal PowerShell ou Prompt de Comando;
Knowledge API executando localmente;
documentação OpenAPI e testes essenciais.

1. Quatro etapas diferentes

Etapa	O que acontece
desenvolvimento	acompanha alterações e reinicia a API
compilação	transforma TypeScript em JavaScript
execução	inicia o processo Node.js
publicação	envia artefatos e configuração a outro ambiente

Confundir essas etapas dificulta o diagnóstico.

2. Scripts principais

{
  "scripts": {
    "start:dev": "nest start --watch",
    "build": "nest build",
    "start:prod": "node dist/main.js",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:e2e": "jest --config ./test/jest-e2e.json"
  }
}

Os nomes à esquerda são atalhos do projeto. Os comandos à direita executam ferramentas.

3. Comandos no Windows

Abra o terminal na pasta que contém package.json:

npm install
npm test
npm run build
npm run start:prod

Os mesmos comandos funcionam no PowerShell e no Prompt de Comando. A forma de definir variáveis de ambiente muda entre terminais, por isso prefira configuração documentada e arquivos locais ignorados pelo Git.

4. O que `nest build` produz?

Em uma aplicação padrão, a saída fica em dist:

dist/
├── main.js
├── app.module.js
└── tasks/
    ├── tasks.controller.js
    ├── tasks.service.js
    └── tasks.module.js

O formato exato depende da configuração. Não escreva caminhos rígidos sem confirmar a saída real.

5. O que não entra em `dist` automaticamente?

Podem exigir tratamento explícito:

arquivos estáticos;
modelos de e-mail;
certificados;
arquivos de tradução;
documento OpenAPI exportado;
qualquer recurso não importado pela compilação.

Configure cópia de recursos somente quando o projeto realmente precisar.

6. Compilação não valida tudo

Uma compilação aprovada confirma principalmente tipos e transformação. Ela não garante:

conexão com serviços externos;
presença de variáveis de ambiente;
regras corretas;
segurança;
documentação coerente;
funcionamento de todos os endpoints.

Por isso, a porta de qualidade inclui mais etapas.

7. Porta de qualidade local

instalação
   ↓
formatação e análise estática
   ↓
testes
   ↓
compilação
   ↓
auditoria de segurança e documentação
   ↓
execução do artefato

Interrompa a entrega quando uma etapa obrigatória falhar.

8. Limpeza da saída

Evite misturar arquivos antigos com a compilação atual. O Nest CLI normalmente gerencia a saída, mas o projeto deve confirmar sua configuração. Nunca apague pastas amplas ou fora do projeto por meio de um script de limpeza mal definido.

9. Configuração de produção

Produção precisa fornecer valores como:

NODE_ENV=production
PORT=3000
DATABASE_URL=...

O arquivo .env.example documenta nomes sem valores secretos:

NODE_ENV=development
PORT=3000
DATABASE_URL=mysql://USUARIO:SENHA@HOST:3306/BANCO

Nunca envie .env real ao repositório ou ao navegador.

10. O Git atrapalha a publicação?

Não. Git registra versões do código e pode ajudar a transportar mudanças. O ambiente de destino pode:

clonar um repositório autorizado;
receber um pacote já compilado;
receber uma imagem de contêiner;
usar um serviço de implantação integrado ao repositório.

Git não executa a API sozinho e não substitui configuração, Node.js ou processo de publicação.

11. É obrigatório ter VPS?

Não para desenvolver e concluir o curso. Localmente, o Windows pode executar:

navegador
├── site estático pelo Apache/XAMPP
├── Angular em servidor de desenvolvimento ou compilado
├── API NestJS em localhost:3000
└── MySQL local pelo XAMPP ou instalação própria

Uma VPS ou hospedagem compatível é necessária apenas quando você quiser manter o sistema disponível publicamente e controlar o processo Node.js no servidor.

12. XAMPP executa a API NestJS?

O Apache do XAMPP não executa o processo NestJS. São programas diferentes:

Apache/XAMPP  → arquivos web e, se necessário, proxy
Node.js       → processo da API NestJS
MySQL         → banco de dados

Eles podem coexistir no mesmo computador, desde que utilizem portas compatíveis.

13. Hospedagem compartilhada

Uma hospedagem comum pode oferecer Git e ainda não permitir um processo Node.js permanente. Antes de contratar ou publicar, verifique:

suporte à versão necessária do Node.js;
possibilidade de manter processo ativo;
configuração de porta ou proxy;
variáveis de ambiente;
acesso a registros;
reinício automático;
banco MySQL;
limites de memória e CPU.

Não confunda “possui Git” com “hospeda NestJS”.

14. Gerenciador de processo

Em servidor próprio, a API precisa reiniciar após falha ou reinicialização da máquina. Um gerenciador de processo ou a plataforma de hospedagem cumpre esse papel. A escolha será detalhada no Módulo 15.

15. Verificação de saúde

O endpoint de saúde deve confirmar que o processo responde:

GET /api/health

{
  "status": "ok",
  "service": "knowledge-api"
}

Quando MySQL for conectado, a estratégia deverá diferenciar saúde do processo e disponibilidade de dependências.

16. README reproduzível

O README precisa responder:

o que é o projeto;
quais tecnologias utiliza;
quais versões são esperadas;
como instalar dependências;
como criar a configuração local;
como executar em desenvolvimento;
como testar;
como compilar;
como executar a compilação;
onde abrir a documentação;
quais dados são mantidos apenas em memória.

17. Exemplo de início rápido

## Execução local no Windows

1. Copie `.env.example` para `.env`.
2. Execute `npm install`.
3. Execute `npm run start:dev`.
4. Abra `http://localhost:3000/docs`.

## Verificações

- `npm test`
- `npm run test:e2e`
- `npm run build`

Não escreva “execute normalmente”. Forneça comandos e resultados esperados.

18. Projeto final do módulo

A Knowledge API deve incluir:

GET /api/health;
GET /api/tasks;
GET /api/tasks/:id;
POST /api/tasks;
PATCH /api/tasks/:id;
DELETE /api/tasks/:id;
módulo de tarefas;
controlador fino e serviço de aplicação;
repositório em memória;
DTOs por operação;
validação global;
erros HTTP padronizados;
correlação e registros seguros;
documentação OpenAPI;
testes essenciais;
compilação executável;
README reproduzível.

19. Estrutura sugerida

knowledge-api/
├── src/
│   ├── common/
│   │   ├── filters/
│   │   ├── interceptors/
│   │   └── middleware/
│   ├── config/
│   ├── health/
│   ├── tasks/
│   │   ├── dto/
│   │   ├── domain/
│   │   └── repositories/
│   ├── app.module.ts
│   └── main.ts
├── test/
├── .env.example
├── .gitignore
├── nest-cli.json
├── package.json
├── tsconfig.json
└── README.md

Estrutura serve à compreensão. Não crie pastas vazias apenas para parecer arquitetural.

20. Auditoria do contrato HTTP

Para cada operação, confirme:

verbo e caminho;
status de sucesso;
DTO de entrada;
formato de saída;
erros esperados;
idempotência quando relevante;
documentação OpenAPI;
teste correspondente.

21. Auditoria de segurança

.env real está ignorado;
nenhum segredo aparece no Angular;
erros não devolvem stack trace;
registros não contêm senha ou token;
documentação não possui credencial real;
entrada externa passa por validação;
CORS não foi confundido com autorização;
dependências não foram instaladas de fonte desconhecida.

22. Auditoria de qualidade

módulos possuem responsabilidade clara;
controladores delegam regras;
serviços recebem dependências;
testes são independentes;
compilação não possui erro;
aplicação fecha corretamente em testes;
comandos do README foram reproduzidos em pasta limpa;
saída compilada inicia com configuração válida.

23. Evidências da entrega

Guarde:

resultado da suíte de testes;
resultado da compilação;
captura ou exportação do contrato OpenAPI;
lista de endpoints;
exemplo de registro sem dado sensível;
README;
roteiro de apresentação;
limitações conhecidas.

Evidência não significa publicar segredos ou todo o conteúdo do terminal.

24. Roteiro de apresentação

Minuto 1 — problema

Explique por que a Knowledge AI precisa de uma API.

Minutos 2 e 3 — arquitetura

Mostre módulo, controlador, serviço e repositório.

Minutos 4 e 5 — contrato

Apresente documentação, DTOs, validação e erros.

Minuto 6 — qualidade

Mostre correlação, testes e compilação.

Minuto 7 — limites e evolução

Explique que o armazenamento ainda é em memória e será substituído por MySQL no Módulo 6.

25. Perguntas para defesa técnica

por que o Angular não acessa MySQL diretamente?
qual diferença entre DTO e entidade?
por que documentação não substitui validação?
onde uma regra de negócio deve ficar?
como localizar eventos da mesma requisição?
por que o projeto usa repositório em memória agora?
como o sistema será publicado no futuro?

26. Laboratório guiado

Abra o painel de entrega da Knowledge API.

Etapa 1 — Escolha um estado

Compare projeto incompleto, regressão e versão pronta.

Etapa 2 — Execute as verificações

Rode testes, compilação, auditoria de contrato e segurança.

Etapa 3 — Examine bloqueadores

O painel explica por que uma entrega não deve avançar.

Etapa 4 — Gere o parecer

Produza um resumo com pontuação, evidências e próximos passos.

27. Erros comuns

Executar `start:prod` antes de compilar

O arquivo esperado pode não existir ou estar desatualizado.

Copiar `.env` para `dist`

Segredo não pertence ao artefato público.

Publicar somente `src`

O servidor precisa de estratégia de instalação e compilação ou de artefato pronto.

Achar que Git mantém o processo vivo

Git transporta versões. Um serviço ou gerenciador executa a aplicação.

Testar apenas no Swagger UI

Isso é útil, mas não substitui suíte automatizada.

Ignorar limitações conhecidas

O armazenamento em memória perde dados ao reiniciar. Documente essa decisão.

28. Exercícios

explique a diferença entre npm run build e npm run start:prod;
liste os processos locais usados com XAMPP;
escreva o início rápido do README;
produza uma lista de seis endpoints;
identifique cinco dados que não podem aparecer nos registros;
execute testes e compilação em uma pasta nova;
explique por que uma VPS não é necessária durante o curso.

29. Desafio individual

Prepare uma entrega reproduzível da Knowledge API:

repositório Git local limpo;
.env.example sem segredo;
instruções para Windows;
suíte aprovada;
compilação aprovada;
documentação OpenAPI;
exemplo de erro seguro;
exemplo de correlação;
roteiro de apresentação de sete minutos;
registro explícito da limitação de armazenamento em memória.

30. Lista de verificação de conclusão

Diferencio compilação, execução e publicação.
Executo comandos na pasta que contém package.json.
A suíte de testes está aprovada.
A compilação está aprovada.
O resultado compilado inicia corretamente.
Nenhum segredo está versionado ou documentado.
O README permite reproduzir a execução no Windows.
A documentação corresponde aos endpoints.
Sei explicar como XAMPP e NestJS coexistem.
Sei que não preciso de VPS para concluir o curso.
Consigo apresentar decisões e limitações.

31. Rubrica do projeto final

Critério	Pontos
Arquitetura modular	15
Contratos REST e validação	15
Erros e configuração	15
OpenAPI	10
Registros e segurança	15
Testes	15
Compilação e reprodução	10
Apresentação técnica	5
Total	100

Para concluir o módulo, obtenha pelo menos 70 pontos e não possua falha crítica de segurança, compilação ou reprodução.

32. Resumo

TypeScript precisa ser compilado para JavaScript executável;
compilar não publica nem inicia automaticamente;
Git ajuda a versionar e transportar, mas não executa a API;
XAMPP e NestJS são processos diferentes e podem coexistir;
todo o módulo pode ser concluído localmente no Windows;
uma entrega profissional inclui testes, contrato, segurança e documentação;
MySQL substituirá o armazenamento em memória sem mudar a responsabilidade do Angular.

Próximo módulo

No Módulo 6, conectaremos a API ao MySQL com Prisma, criaremos modelos, migrações, consultas, transações e paginação sem permitir que o Angular acesse o banco diretamente.