Melhores Práticas do Node.js

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

Quando Usar

Use esta habilidade ao tomar decisões de arquitetura Node.js, escolher frameworks, projetar padrões assíncronos ou aplicar melhores práticas de segurança e implantação.

⚠️ 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 estiver claro
• Escolha o framework/padrão com base no CONTEXTO
• Não use a mesma solução por padrão sempre

1. Seleção de Framework (2025)

Árvore de Decisão

What are you building?
│
├── Edge/Serverless (Cloudflare, Vercel)
│   └── Hono (zero-dependency, ultra-fast cold starts)
│
├── High Performance API
│   └── Fastify (2-3x faster than Express)
│
├── Enterprise/Team familiarity
│   └── NestJS (structured, DI, decorators)
│
├── Legacy/Stable/Maximum ecosystem
│   └── Express (mature, most middleware)
│
└── Full-stack with frontend
    └── Next.js API Routes or tRPC

Princípios de Comparação

Perguntas de Seleção a Fazer:

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

2. Considerações de Runtime (2025)

TypeScript Nativo

Node.js 22+: --experimental-strip-types
├── Run .ts files directly
├── No build step needed for simple projects
└── Consider for: scripts, simple APIs

Decisão do Sistema de Módulos

ESM (import/export)
├── Modern standard
├── Better tree-shaking
├── Async module loading
└── Use for: new projects

CommonJS (require)
├── Legacy compatibility
├── More npm packages support
└── Use for: existing codebases, some edge cases

Seleção de Runtime

3. Princípios de Arquitetura

Conceito de Estrutura em Camadas

Request Flow:
│
├── Controller/Route Layer
│   ├── Handles HTTP specifics
│   ├── Input validation at boundary
│   └── Calls service layer
│
├── Service Layer
│   ├── Business logic
│   ├── Framework-agnostic
│   └── Calls repository layer
│
└── Repository Layer
    ├── Data access only
    ├── Database queries
    └── ORM interactions

Por Que Isso Importa:

• Testabilidade: Simule camadas independentemente
• Flexibilidade: Troque o banco de dados sem alterar a lógica de negócios
• Clareza: Cada camada tem uma única responsabilidade

Quando Simplificar:

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

4. Princípios de Tratamento de Erros

Tratamento Centralizado de Erros

Pattern:
├── Create custom error classes
├── Throw from any layer
├── Catch at top level (middleware)
└── Format consistent response

Filosofia de Resposta de Erro

Client gets:
├── Appropriate HTTP status
├── Error code for programmatic handling
├── User-friendly message
└── NO internal details (security!)

Logs get:
├── Full stack trace
├── Request context
├── User ID (if applicable)
└── Timestamp

Seleção de Código de Status

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

Quando Usar Cada Um

Consciência do Event Loop

Vinculado a I/O (async ajuda):
├── Consultas ao banco de dados
├── Requisições HTTP
├── Sistema de arquivos
└── Operações de rede

Vinculado a CPU (async não ajuda):
├── Operações criptográficas
├── Processamento de imagem
├── Cálculos complexos

…