Boas Práticas de Modularidade

Direção de importação: rotas → casos de uso → domínio. Estas práticas mantêm bases de código Node.js testáveis e prontas para mudanças de framework ou persistência.

Como Usar Esta Lista

• Automatize regras de importação antes de debates em code review
• Aplique a workers e pontos de entrada CLI, não apenas HTTP
• Emparelhe com Boas Práticas de Arquitetura para limites macro
• Novas rotas devem chamar casos de uso existentes - sem orquestração duplicada

A - Disciplina de Camadas

• Handlers de rota ficam com menos de 15 linhas. Parse, autorize, chame caso de uso, mapeie resposta.
• Casos de uso orquestram e definem regras de aplicação. Não repositórios, não rotas.
• Camada de domínio não tem importações de express, fastify, @nestjs/*, prisma, ioredis.
• Infraestrutura implementa portas definidas em domínio/aplicação. Mapeie linhas de ORM para entidades de domínio no adaptador.
• Raiz de composição é o único lugar que instancia adaptadores concretos.

B - Direção de Importação

• Fluxo permitido: infraestrutura → aplicação → domínio. Nunca domínio → infraestrutura.
• Chamadas entre funcionalidades passam pela API pública do módulo ou serviço de aplicação. Não acesse a infraestrutura de um módulo par.
• CI executa dependency-cruiser ou ESLint para falhar importações proibidas.
• Kernel compartilhado contém apenas utilitários. Sem regras de precificação, impostos ou descontos em shared/.
• Arquivos Barrel exportam a superfície pública intencional. Não export * from './infrastructure'.

C - Testes

• Testes unitários de casos de uso com repositórios em memória. Testes sub-10ms por comando.
• Testes de integração acessam Postgres real via Testcontainers para adaptadores de repositório.
• Testes HTTP (supertest) cobrem códigos de status e autenticação. Não todos os ramos de regras de negócio.
• Workers chamam os mesmos casos de uso que as rotas HTTP. Sem lógica de negócio duplicada.
• Reinicie o container DI ou o cache de configuração entre os testes.

D - Design de Casos de Uso

• Um caso de uso por comando ou consulta. Sem OrderGodService.
• Tipos explícitos de entrada/saída. Adaptadores mapeiam para DTOs JSON.
• Verificações de autorização vivem no caso de uso ou política de domínio. Não apenas middleware de rota.
• Idempotência e transações documentadas por caso de uso.
• Retorne erros de domínio tipados (AppError). Mapeador HTTP central traduz códigos.

E - Persistência

• Interfaces de repositório expressam a linguagem de domínio. findById, não findUnique.
• Sem cliente Prisma em casos de uso. Injete OrderRepository.
• Relatórios pesados usam modelos de leitura ou serviços de consulta. Não repositórios inchados.
• Repositório em memória enviado junto com o adaptador Postgres para testes rápidos.
• Cursores de paginação retornados da porta do repositório quando listas são grandes.

F - Notas de Framework (Express 5 / Fastify 5 / Nest 11)

• Express/Fastify: fábricas de roteadores ordersRouter(deps) para injeção.
• Fastify: use plugins com escopo encapsulado quando módulos precisam de isolamento.
• Nest: controllers finos; providers mapeiam para casos de uso. Evite a classe "deus" OrdersService inchada.
• Valide req.body com Zod na borda HTTP antes de execute().
• Um framework HTTP por deployable. Não misture Express e Fastify em um único processo.

FAQs

Relacionados

• Fundamentos de Modularidade - exemplos introdutórios
• Casos de Uso e Serviços - camada de aplicação
• Padrão Repository - portas de persistência
• Padrões de Injeção de Dependência - conexão
• Checklist de Refatoração - auditoria estrutural

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.