Boas Práticas de Regras do Node.js

Como transformar as regras de serviços Node.js de documentação em prática de engenharia aplicada e auditável.

Como Usar Esta Lista

• Emparelhe com o Checklist de Regras do Projeto Node.js a cada trimestre.
• Cada regra deve ser mapeada para CI, lint ou revisão de código - não para sistema de honra.
• A equipe de plataforma mantém modelos que incorporam padrões aplicáveis por padrão.

A - Mecanismos de Aplicação

• CI falha em lint, typecheck, teste, auditoria - não avisos no README. Regras sem portões decaem em semanas.
• Modelos incluem .npmrc engine-strict, ESLint, teste de exemplo, Dockerfile. Novos repositórios começam em conformidade.
• Checklist de PR vincula o checklist de regras para funcionalidades principais. Portão humano para regras que a automação não pode cobrir.
• Substitua ADRs ao reverter decisões. O histórico do Git explica por que as regras mudaram.
• Ticket de auditoria de regras trimestral. O proprietário verifica o status de aprovação/falha do checklist por catálogo de serviços.

B - Tempo de Execução e Confiabilidade

• Integração de desligamento gracioso testada. Teste SIGTERM em CI ou script de implantação em staging.
• Readiness difere de liveness. Verificação de DB apenas em /ready para evitar kill em cascata durante picos.
• Regras de loop de eventos e IO síncrono em revisão de lint/arquitetura. Bloqueie readFileSync em src/ via regra personalizada ou grep CI.
• Timeouts de saída obrigatórios no wrapper do cliente HTTP. fetchWithTimeout único usado em toda a organização.
• Jobs de worker carregam IDs de correlação da requisição que os acionou. Rastreie junções entre limites assíncronos.

C - Segurança e Dependências

• Zod (ou equivalente) em cada rota mutável. Sem req.body bruto nas profundezas dos serviços.
• Verificação de segredos no push. Verificação de segredo do GitHub mais gitleaks em CI.
• Wrapper SSRF exigido para URLs de usuário. Sem fetch(userInput) bruto em qualquer lugar.
• Agendamento semanal de auditoria de dependências. Não apenas quando o Renovate abre PRs.
• RFC antes de nova dependência de produção. knip impede o acúmulo de dependências não utilizadas.

D - API e Observabilidade

• Manipulador de erros global com formato JSON único. Clientes e BFFs dependem da consistência.
• Chaves de idempotência em mutações financeiras. Índice único de DB impõe; não apenas cache de aplicação.
• Logs JSON estruturados apenas; Pino ou equivalente. no-console em src/.
• Métricas para sinais de ouro: latência, tráfego, erros, saturação. Mínimo de métricas RED por serviço.
• Esquemas OpenAPI ou Zod publicados para APIs públicas. Contrato fonte de verdade documentado.

E - Cultura e Propriedade

• Runbook de plantão vinculado e testado após alterações importantes. Regras 21-25 fatia operacional.
• Incidentes atualizam regras ou ADRs quando lacunas são encontradas. Ações de postmortem se tornam itens de checklist.
• Onboarding de juniores percorre o checklist nível 1. Segurança e tempo de execução antes da velocidade de funcionalidades.
• Exceções de plataforma com tempo limitado. Isenções de engine-strict expiram com ID de ticket.
• Regras ensinadas via exemplos de revisão de código, não apenas slides. Vincule a documentação da regra nos comentários da revisão.

FAQs

Relacionados

• Checklist de Regras do Projeto Node.js - auditoria de 25 regras
• Modelo ADR para Node - documentar decisões
• Regras de Segurança - detalhes das regras de segurança

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.