Arquitetura Hexagonal: Princípios e aplicação prática

Publicado em 29 Jan 2026 • 6 min de leitura

A Arquitetura Hexagonal, também conhecida como Ports & Adapters, é um padrão que isola o núcleo de negócio (domínio) de detalhes externos — UI, persistência, filas, APIs externas — através de portas (interfaces) e adaptadores que fazem a tradução entre o mundo externo e o domínio.

Por que usar?

  • Separação clara de responsabilidades: regras de negócio ficam sem dependência direta de frameworks e infra.
  • Testabilidade: o domínio pode ser testado com mocks/stubs de portas sem precisar de banco ou rede.
  • Facilidade para trocar infra: trocar um banco, gateway ou UI torna-se uma mudança de adaptador, não do domínio.

Estrutura básica

Imagine três camadas: domínio no centro, portas (interfaces) ao redor, e adaptadores na borda. Comunicam-se apenas via interfaces:

 // Domain
interface OrderService { placeOrder(dto): Result }

// Adapter (driven) - persistence
class SqlOrderRepository implements OrderRepository { ... }

// Adapter (driving) - http
class HttpOrderController { constructor(orderService){ this.orderService = orderService } }

Boas práticas

  1. Defina interfaces nos limites do domínio e não ao contrário.
  2. Mantenha o domínio livre de anotações e dependências de frameworks.
  3. Implemente adaptadores finos que convertem DTOs para objetos de domínio e vice-versa.
  4. Use testes de unidade no domínio e testes de integração para validar adaptadores end-to-end.

Exemplo prático

Em um serviço de pedidos, o fluxo típico seria: Controller → Application Service (porta) → Domínio → Repositório (porta) → Adapter (SQL/NoSQL).

Quando evitar

Projetos muito pequenos ou scripts simples podem não se beneficiar do overhead inicial. Também não precisa ser obedecida religiosamente: aplique pragmatismo.

Conclusão

A Arquitetura Hexagonal é uma abordagem poderosa para manter domínio limpo e independente, facilitando evolução e testes. Comece extraindo interfaces nos pontos de acoplamento e evolua gradualmente.

Se quiser, posso gerar um template de projeto (métodos, estrutura de pastas e exemplos em Java/TypeScript) para começar.