Clean Architecture na prática
A regra de dependência, os círculos e o que ninguém conta: onde a Clean Architecture se paga com folga e onde ela vira fábrica de boilerplate. Um guia honesto e prático.
Código organizado que escala de verdade não é o que tem mais pastas. É o que protege o que importa.
Todo sistema tem um núcleo que vale dinheiro: as regras do negócio. Como se calcula um frete, quando um pedido pode ser cancelado, o que torna um usuário elegível a desconto. E todo sistema tem cascas que mudam com o tempo: o framework web da vez, o banco de dados, a fila, a API de terceiro.
O drama da maioria dos códigos legados é que essas duas coisas estão misturadas. A regra de frete vive dentro do controller, que conhece o ORM, que depende do framework. Resultado: trocar qualquer casca exige cirurgia no núcleo, e testar o núcleo exige subir o mundo inteiro.
A Clean Architecture, formalizada por Robert C. Martin em 2012, ataca exatamente essa mistura (o artigo original).
A única regra que realmente importa
Esqueça por um momento os nomes das camadas. A Clean Architecture se resume a uma regra:
As dependências apontam sempre para dentro. O núcleo de negócio não conhece nada de fora. Nunca.
Na prática, os círculos se organizam assim, de dentro para fora:
- Entidades: as regras de negócio que existiriam mesmo sem software. Um Pedido, suas invariantes, seus estados válidos.
- Casos de uso: as ações do sistema. "Confirmar pedido", "aplicar desconto". Orquestram entidades e definem o que o sistema faz.
- Adaptadores: tradutores entre o mundo de dentro e o de fora. Controllers, presenters, repositórios concretos.
- Frameworks e drivers: a borda descartável. Web framework, banco, filas, APIs externas.
O truque que faz tudo funcionar é a inversão de dependência (o D do SOLID): o caso de uso declara a interface RepositorioDePedidos; quem implementa com Postgres, Mongo ou memória é a borda. O núcleo manda, a infraestrutura obedece.
O que você ganha com isso
- Testabilidade real: as regras de negócio são testadas em milissegundos, sem banco, sem HTTP, sem mock acrobático. O teste instancia o caso de uso com implementações de memória e pronto.
- Decisões adiadas: Martin chama frameworks e banco de "detalhes". Com o núcleo isolado, você pode escolher (ou trocar) o detalhe depois, com o produto já validado. Combina com a filosofia de adiar decisões caras que defendemos aqui.
- Código que conta a história do negócio: abrir a pasta de casos de uso e ler "ConfirmarPedido", "CancelarAssinatura", "AplicarReajuste" comunica mais que qualquer documentação.
- Fronteiras prontas para crescer: se um dia o sistema precisar extrair um serviço, as costuras já existem. Casos de uso coesos viram serviços com muito menos dor.
A mesma ideia aparece com outros nomes na literatura: Hexagonal (Ports & Adapters) de Alistair Cockburn e Onion Architecture de Jeffrey Palermo. Os desenhos variam; a regra de dependência é a mesma.
Onde os times exageram
Sejamos honestos: Clean Architecture mal aplicada vira fábrica de boilerplate. Os erros clássicos:
- Camada por camada em CRUD trivial: cadastro simples não precisa de quatro interfaces e três DTOs por campo. Comece simples; adicione fronteiras quando a regra de negócio aparecer de verdade.
- Abstrair o que nunca vai mudar: interface para tudo "por precaução" é custo sem retorno. Abstraia o que é volátil ou o que precisa de teste isolado.
- Culto à pasta: copiar a estrutura de diretórios de um tutorial não é arquitetura. A pergunta de auditoria é uma só: o núcleo importa algo da borda? Se sim, não há Clean Architecture, há pastas bonitas.
Nossa régua em consultoria: a arquitetura deve custar menos do que os problemas que evita. Em produtos com regra de negócio rica e vida longa, a Clean Architecture se paga com folga. Em protótipos e CRUDs finos, uma organização em módulos simples basta.
Quer o núcleo do seu sistema protegido?
Aplicar essas fronteiras num código que já existe, sem parar a esteira de entregas, é um trabalho de refatoração incremental que fazemos com frequência no serviço de Arquitetura de Software: mapeamos o domínio, isolamos os casos de uso mais valiosos primeiro e o time continua entregando durante a transição.
Quer saber se o seu código passa no teste da regra de dependência? Pergunte à IA da Rabelo Digital, aqui no canto da tela. Descreva a estrutura atual e ela aponta os primeiros movimentos. Sem formulário, sem espera.
Deixe um Comentário