Introdução
Você já abriu um projeto seu depois de alguns meses e pensou: “Quem foi o maluco que escreveu isso?” (e depois percebeu que foi você mesmo 😅).
Isso acontece porque, no calor do desenvolvimento, priorizamos entregar rápido e acabamos deixando a organização de lado. Foi assim que descobri o poder da Clean Architecture — uma abordagem que mudou a forma como estruturo meus projetos no dia a dia.
Desenvolvimento
1. O problema: código que cresce sem controle
Em projetos pequenos, tudo parece caber em um único arquivo ou em poucas pastas. Mas conforme o sistema cresce, a bagunça aparece:
- Regras de negócio misturadas com detalhes de banco de dados.
- Controllers cheios de lógica que deveriam estar em outro lugar.
- Dificuldade de testar partes isoladas do sistema.
Esse foi exatamente o cenário que vivi em um projeto usando NestJS + Prisma + PostgreSQL.
2. A solução: separar responsabilidades
A Clean Architecture propõe um princípio simples: separe as camadas e proteja as regras de negócio da bagunça externa.
Na prática, organizei assim:
- Use Cases → onde fica a lógica de negócio pura.
- Repositories → abstrações para o acesso a dados (ex.: Prisma).
- Controllers / Resolvers → apenas responsáveis por receber requisições e devolver respostas.
- DTOs → contratos de entrada e saída, deixando claro o que cada caso de uso espera.
3. Exemplo prático do dia a dia
Um caso real foi quando precisei criar um use case para gerar boletos Pix (Bolepix).
Antes, o controller fazia tudo: validava dados, chamava o banco e ainda se conectava à API da Celcoin. Resultado: um caos difícil de manter.
Depois da refatoração:
- O Controller só recebia a requisição e chamava o CreateBolepixUseCase.
- O Use Case cuidava da lógica de criação, validando as regras de negócio.
- O Repository abstraía as interações com o Prisma.
- A integração com a Celcoin ficou isolada em um service externo.
Isso tornou o código muito mais testável e fácil de evoluir.
4. Boas práticas que aprendi
- Não deixe que a camada de banco de dados “contamine” a lógica de negócio.
- Escreva testes primeiro para os use cases — eles são o coração da aplicação.
- Mantenha os nomes claros: CreateOrderUseCase, ChargeWebhookUseCase, etc.
- Lembre-se: simples é melhor do que complexo.
Conclusão
Adotar a Clean Architecture não é sobre seguir uma “receita de bolo”, mas sim sobre aprender a separar responsabilidades para manter o código limpo e saudável a longo prazo.
Hoje, quando volto a projetos antigos, consigo entender facilmente a estrutura e evoluir sem medo de quebrar tudo.
E você, já tentou aplicar Clean Architecture em seus projetos? Quais foram seus maiores desafios? 🚀
Conta aqui nos comentários — vou adorar trocar experiências.
Top comments (0)