Como desenvolvedores Fullstack, somos constantemente pressionados a entregar funcionalidades rapidamente. Nessa pressa, é comum cairmos na armadilha de acoplar regras de negócio diretamente ao framework (Express, NestJS, Spring Boot) ou ao banco de dados. O resultado? Um código difícil de testar e um pesadelo para refatorar.
A Arquitetura Hexagonal (ou Ports and Adapters), criada por Alistair Cockburn, propõe uma solução para esse acoplamento. Mas a grande questão que quero discutir hoje não é apenas "como implementar", mas quando o investimento se paga.
O Coração do Conceito: Independência
A premissa é simples: Sua lógica de negócio não deve depender de nada externo. O "Hexágono" representa o seu domínio. O que está fora dele (banco de dados, APIs de terceiros, interfaces de usuário) são apenas detalhes de implementação.
- Ports (Portas)
São as definições (geralmente interfaces) de como o mundo externo deve interagir com sua aplicação ou como sua aplicação precisa consumir recursos externos.
Driving Ports (Entrada): Como o usuário chega até a lógica (ex: uma interface de serviço).
Driven Ports (Saída): O que a lógica precisa para funcionar (ex: uma interface de repositório).
- Adapters (Adaptadores)
São as implementações técnicas. Um SqlOrderRepository é um adaptador de saída que implementa a porta OrderRepository. Se amanhã você mudar para MongoDB, criará um novo adaptador sem tocar na lógica central.
Quando vale a pena aplicar?
Implementar essa arquitetura exige mais arquivos, mais interfaces e, consequentemente, mais tempo inicial. Por isso, ela não deve ser sua escolha padrão para tudo.
✅ Vale a pena quando:
A complexidade de negócio é alta: Se o seu software possui regras complexas que precisam ser protegidas de mudanças tecnológicas.
Sistemas de Vida Longa: Projetos que ficarão em manutenção por anos e passarão por trocas de bibliotecas e versões de frameworks.
Necessidade de Testes Unitários Reais: Se você precisa testar regras de negócio sem subir containers ou mocks complexos de banco de dados. No hexágono, você testa o domínio isoladamente.
Incerteza Técnica: Quando você ainda não decidiu qual banco de dados usar ou se a integração com aquele parceiro de logística é definitiva.
❌ Não vale a pena quando:
CRUDs Simples: Se sua aplicação apenas move dados de um formulário para o banco, a abstração será apenas um estorvo.
MVPs de curtíssimo prazo: Se o objetivo é validar uma ideia em duas semanas para possivelmente descartá-la.
Projetos com baixa complexidade de lógica: Onde o framework já resolve tudo de forma idiomática e rápida.
O Trade-off: O preço da liberdade
O maior custo da Arquitetura Hexagonal é o Boilerplate. Você terá que mapear objetos de banco (Entidades de Infra) para objetos de domínio e vice-versa. Isso evita que o seu domínio seja "contaminado" por anotações de ORM (como TypeORM ou Hibernate), mas exige código extra (Mappers).
Conclusão
A Arquitetura Hexagonal é sobre opções. Ela permite que você adie decisões técnicas e proteja o ativo mais valioso da sua empresa: a regra de negócio. Se você é um dev Fullstack buscando senioridade, dominar esse padrão permitirá que você projete sistemas sustentáveis, e não apenas softwares que "funcionam por enquanto".
E você, já sentiu a dor de ter que trocar uma biblioteca e ver o sistema inteiro quebrar? O isolamento do domínio teria ajudado? Vamos conversar nos comentários!
Top comments (0)