Engenharia de Software
Clean Architecture com Node.js
Como estruturar aplicações Node.js com separação de responsabilidades, testes e regras de negócio mais protegidas.
Clean Architecture em Node.js ajuda a organizar casos de uso, entidades, adaptadores e infraestrutura com limites claros.
Separe casos de uso
Casos de uso coordenam regras, validações e dependências. Eles não deveriam saber se a chamada veio de REST, fila ou job agendado. Essa independência permite reaproveitar a regra em diferentes entradas.
Em TypeScript, um caso de uso pode receber interfaces para repositórios, serviços externos e publicadores de eventos. Isso mantém o código testável e reduz o acoplamento com frameworks.
- Dê nomes de negócio aos casos de uso.
- Receba dependências por contrato.
- Retorne erros de domínio previsíveis.
Infraestrutura nas bordas
Express, Fastify, Prisma, filas e SDKs externos são detalhes importantes, mas detalhes. Eles devem ficar nas bordas, traduzindo entrada e saída para o formato que o núcleo entende.
Essa fronteira também ajuda a controlar efeitos colaterais. Em vez de uma rota salvar dados, enviar e-mail e publicar evento diretamente, o caso de uso orquestra o fluxo e cada adaptador executa sua parte.
- Controllers devem ser finos.
- Repositórios implementam persistência, não regra de negócio.
- Integrações externas precisam de timeouts e tratamento de erro.
Teste o que sustenta a operação
A maior vantagem aparece nos testes. Casos de uso podem ser validados sem subir banco ou servidor, cobrindo cenários de sucesso, falhas de regra e respostas de dependências externas.
Isso não elimina testes de integração. Pelo contrário: permite que eles sejam mais focados em contratos importantes, como schema de banco, endpoints públicos e mensageria.
- Cubra regras com testes unitários de caso de uso.
- Cubra adaptadores com testes de integração.
- Evite mocks excessivos em fluxos que dependem de contratos externos.