Nodejs Best Practices

Node.js Best Practices

Princípios e tomada de decisão para desenvolvimento Node.js em 2025. Aprenda a PENSAR, não memorize padrões de código.

⚠️ Como Usar Esta Habilidade

Esta habilidade ensina princípios de tomada de decisão, não código fixo para copiar.

• PERGUNTE ao usuário sobre preferências quando não estiverem claras
• Escolha framework/padrão baseado no CONTEXTO
• Não use a mesma solução padrão toda vez

1. Seleção de Framework (2025)

Árvore de Decisão

O que você está construindo?
│
├── Edge/Serverless (Cloudflare, Vercel)
│   └── Hono (zero-dependency, cold starts ultra-rápidos)
│
├── API de Alta Performance
│   └── Fastify (2-3x mais rápido que Express)
│
├── Enterprise/Familiaridade da equipe
│   └── NestJS (estruturado, DI, decoradores)
│
├── Legado/Estável/Ecossistema máximo
│   └── Express (maduro, mais middleware)
│
└── Full-stack com frontend
    └── Next.js API Routes ou tRPC

Princípios de Comparação

Perguntas para Seleção:

1. Qual é o alvo de deployment?
2. O tempo de cold start é crítico?
3. A equipe tem experiência prévia?
4. Há código legado para manter?

2. Considerações de Runtime (2025)

TypeScript Nativo

Node.js 22+: --experimental-strip-types
├── Executa arquivos .ts diretamente
├── Sem etapa de build para projetos simples
└── Considere para: scripts, APIs simples

Decisão do Sistema de Módulos

ESM (import/export)
├── Padrão moderno
├── Melhor tree-shaking
├── Carregamento assíncrono de módulos
└── Use para: projetos novos

CommonJS (require)
├── Compatibilidade legada
├── Mais pacotes npm suportam
└── Use para: codebases existentes, alguns casos especiais

Seleção de Runtime

3. Princípios de Arquitetura

Conceito de Estrutura em Camadas

Fluxo de Requisição:
│
├── Camada Controller/Route
│   ├── Manipula especificidades HTTP
│   ├── Validação de entrada na fronteira
│   └── Chama camada de serviço
│
├── Camada Service
│   ├── Lógica de negócio
│   ├── Agnóstica de framework
│   └── Chama camada de repositório
│
└── Camada Repository
    ├── Apenas acesso a dados
    ├── Queries de banco de dados
    └── Interações com ORM

Por Que Isso Importa:

• Testabilidade: Mock de camadas independentemente
• Flexibilidade: Trocar banco de dados sem tocar lógica de negócio
• Clareza: Cada camada tem responsabilidade única

Quando Simplificar:

• Scripts pequenos → Um arquivo OK
• Protótipos → Menos estrutura aceitável
• Sempre pergunte: "Isso vai crescer?"

4. Princípios de Tratamento de Erros

Tratamento de Erros Centralizado

Padrão:
├── Crie classes de erro customizadas
├── Lance de qualquer camada
├── Capture no nível superior (middleware)
└── Formate resposta consistente

Filosofia de Resposta de Erro

Cliente recebe:
├── Status HTTP apropriado
├── Código de erro para manipulação programática
├── Mensagem amigável ao usuário
└── SEM detalhes internos (segurança!)

Logs recebem:
├── Stack trace completo
├── Contexto da requisição
├── ID do usuário (se aplicável)
└── Timestamp

Seleção de Código de Status

5. Princípios de Padrões Assíncronos

Quando Usar Cada Um

Conscientização do Event Loop

I/O-bound (async ajuda):
├── Queries de banco de dados
├── Requisições HTTP
├── Sistema de arquivos
└── Operações de rede

CPU-bound (async não ajuda):
├── Operações criptográficas
├── Processamento de imagem
├── Cálculos complexos
└── → Use worker threads ou offload

Evitar Bloqueio do Event Loop

• Nunca use métodos síncronos em produção (fs.readFileSync, etc.)
• Offload de trabalho CPU-intensivo
• Use streaming para dados grandes

6. Princípios de Validação

Valide nas Fronteiras

Onde validar:
├── Ponto de entrada da API (corpo/params da requisição)
├── Antes de operações de banco de dados
├── Dados externos (respostas de API, uploads de arquivo)
└── Variáveis de ambiente (startup)

Seleção de Biblioteca de Validação

Filosofia de Validação

• Falhe rápido: Valide cedo
• Seja específico: Mensagens de erro claras
• Não confie: Mesmo em dados "internos"

7. Princípios de Segurança

Checklist de Segurança (Não Código)

• Validação de entrada: Todas as entradas validadas
• Queries parametrizadas: Sem concatenação de string para SQL
• Hash de senha: bcrypt ou argon2
• Verificação JWT: Sempre verifique assinatura e expiração
• Rate limiting: Proteção contra abuso
• Security headers: Helmet.js ou equivalente
• HTTPS: Em produção
• CORS: Propriamente configurado
• Secrets: Apenas variáveis de ambiente
• Dependências: Auditadas regularmente

Mentalidade de Segurança

Não confie em nada:
├── Query params → valide
├── Corpo da requisição → valide
├── Headers → verifique
├── Cookies → valide
├── Uploads de arquivo → escaneie
└── APIs externas → valide resposta

8. Princípios de Testes

Seleção de Estratégia de Teste

O Que Testar (Prioridades)

1. Caminhos críticos: Autenticação, pagamentos, negócio principal
2. Casos extremos: Entradas vazias, limites
3. Tratamento de erros: O que acontece quando falha?
4. Não vale a pena testar: Código do framework, getters triviais

Test Runner Integrado (Node.js 22+)

node --test src/**/*.test.ts
├── Sem dependência externa
├── Boa cobertura de reportagem
└── Modo watch disponível

10. Anti-padrões para Evitar

❌ NÃO FAÇA:

• Use Express para novos projetos edge (use Hono)
• Use métodos síncronos em código de produção
• Coloque lógica de negócio em controllers
• Pule validação de entrada
• Hardcode secrets
• Confie em dados externos sem validação
• Bloqueie event loop com trabalho CPU

✅ FAÇA:

• Escolha framework baseado no contexto
• Pergunte ao usuário sobre preferências quando não estiverem claras
• Use arquitetura em camadas para projetos em crescimento
• Valide todas as entradas
• Use variáveis de ambiente para secrets
• Faça profile antes de otimizar

11. Checklist de Decisão

Antes de implementar:

• Perguntou ao usuário sobre preferência de stack?
• Escolheu framework para ESTE contexto? (não só padrão)
• Considerou alvo de deployment?
• Planejou estratégia de tratamento de erros?
• Identificou pontos de validação?
• Considerou requisitos de segurança?

Lembre-se: Node.js best practices são sobre tomada de decisão, não memorizar padrões. Todo projeto merece consideração fresca baseada em seus requisitos.