Checklist de Regras para Projetos Node

Vinte e cinco regras que todo serviço ou worker Node.js HTTP deve satisfazer antes do tráfego de produção.

Como Usar Este Checklist

• Percorra de cima para baixo em novos serviços antes do primeiro deploy.
• Reaudite trimestralmente ou após grandes atualizações do Node/framework.
• Registre aprovação/reprovação em um apêndice de ADR ou wiki da equipe; corrija lacunas em ordem de prioridade.
• Aplique mecanicamente via CI sempre que possível (não apenas por honra no README).

Runtime e Processo

1. Node 24 Active LTS fixado: engines e Docker FROM node:24.18.0 alinhados.
2. Desligamento gracioso: SIGTERM drena HTTP e fecha pools de DB dentro do timeout.
3. Rotas de health e readiness: /health para liveness; /ready verifica o DB quando aplicável.
4. Sem I/O síncrono em caminhos críticos: fs.readFileSync banido em manipuladores de requisição.
5. Concorrência limitada: Workers de HTTP de saída e de fila usam limites (p-limit, tamanho do pool).

Segurança

6. Validação de entrada na fronteira: Validação Zod ou de schema em toda rota mutável.
7. Segredos do ambiente ou vault: Sem segredos no git; .env ignorado pelo git.
8. Guardas SSRF em fetch de saída: Bloqueia IPs link-local e de metadados em URLs fornecidas pelo usuário.
9. Cabeçalhos de segurança e CORS explícitos: Não apenas os padrões do framework em produção.
10. Portão de auditoria de dependências: npm audit --audit-level=high aprovado em CI.

API e Dados

11. Formato JSON de erro consistente: { error: { code, message } } em todas as rotas.
12. Paginação em endpoints de lista: cursor ou limit/offset com limites máximos documentados.
13. Mutações idempotentes: Idempotency-Key ou chaves naturais para POST que criam recursos.
14. Apenas logs estruturados: Logs JSON; sem console.log bruto em src/.
15. ID de correlação em toda requisição: Propaga X-Request-Id em logs e chamadas de saída.

Ferramentas e Qualidade

16. Lockfile commitado; CI usa npm ci. Apenas instalações reproduzíveis.
17. Portão de merge para typecheck: tsc --noEmit em todo PR.
18. Política de lint sem avisos: eslint --max-warnings 0.
19. Testes em CI: Unitários obrigatórios; integração para caminhos de DB com DB isolado.
20. Limites de importação aplicados: Aplicações não importam aplicações irmãs em monorepos.

Operações e Arquitetura

21. Build multi-stage do Docker: Dependências de desenvolvimento excluídas da imagem de runtime.
22. Configuração validada na inicialização: Processo sai com schema de ambiente inválido.
23. Timeouts em HTTP de saída: Sem fetch ilimitado para terceiros.
24. ADR para escolhas de framework e data store: Express/Fastify/Nest e ORM documentados.
25. Runbook linkado no README: Passos de plantão para OOM, deploy ruim, outage de DB.

Aplicando o Checklist em Ordem

• Nível 1 (1-5, 6-10): Segurança e proteção - bloqueia o lançamento se falhar.
• Nível 2 (11-20): Consistência de API e portões de qualidade - corrija antes do tráfego GA.
• Nível 3 (21-25): Maturidade operacional - complete dentro do primeiro mês em produção.

FAQs

Relacionados

• Regras de Async e Event Loop - detalhes das regras 4-5
• Regras de Segurança - detalhes das regras 6-10
• Regras de API - detalhes das regras 11-13

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.