A Arquitetura Hexagonal, também conhecida como Ports and Adapters, é um padrão arquitetural proposto por Alistair Cockburn em 2005 (artigo original ‘Hexagonal Architecture’, posteriormente atualizado em 2008) que resolve um problema clássico do desenvolvimento de software: a mistura entre lógica de negócio e detalhes de infraestrutura. Segundo Cockburn (2005), o objetivo do padrão é ‘permitir que uma aplicação seja igualmente conduzida por usuários, programas, testes automatizados ou scripts em lote, e desenvolvida e testada isoladamente de seus dispositivos e bancos de dados de tempo de execução’.
TL;DR
- Arquitetura Hexagonal isola o core de negócio de frameworks, banco de dados e integrações através de interfaces (ports) implementadas por adapters.
- Segundo o ThoughtWorks Technology Radar (2023), o padrão está na categoria ‘Adopt’ — recomendado para sistemas empresariais de médio a longo prazo.
- Melhor caso de uso: sistemas B2B com múltiplas integrações e alta necessidade de testabilidade; evitar em CRUDs simples.
Como funciona a Arquitetura Hexagonal?
Arquitetura Hexagonal é um padrão que coloca a lógica de negócio no centro (o hexágono) e trata todo o mundo externo — UI, banco, filas, APIs — como plugáveis através de interfaces bem definidas.
Segundo Alistair Cockburn (Hexagonal Architecture, 2005), a metáfora do hexágono foi escolhida deliberadamente por não sugerir hierarquia entre lados: cada ‘face’ representa um ponto de contato com um ator externo, e a comunicação flui sempre através de ports. O core desconhece completamente quem o invoca ou qual banco persiste os dados. Essa inversão é possível graças ao princípio de inversão de dependência (Robert C. Martin, 1996), no qual módulos de alto nível não dependem de módulos de baixo nível.
Ports and Adapters — os componentes
- Application Core: contém entidades de domínio, agregados, value objects e casos de uso (application services). Zero dependência de framework, banco ou HTTP.
- Primary/Driving Ports: interfaces que expõem os casos de uso do sistema (ex.: ‘CriarPedidoUseCase’, ‘AutenticarUsuarioUseCase’). São chamados de ‘entrada’ — quem inicia a interação.
- Secondary/Driven Ports: interfaces que o core requer para funcionar (ex.: ‘PedidoRepository’, ‘PagamentoPort’, ‘NotificacaoPort’). O core define o contrato; alguém fora implementa.
- Primary Adapters: implementam a interface do mundo externo com o core — controllers REST, resolvers GraphQL, consumers de fila, comandos CLI. Segundo Martin Fowler (2017), eles são os ‘motoristas’ do sistema.
- Secondary Adapters: implementam os driven ports — repositórios com JPA/Prisma, gateways HTTP para Stripe/Mercado Pago, publishers de Kafka/SQS, clientes de cache Redis.
Exemplo prático em código
Considere um sistema de pagamentos que precisa suportar múltiplos gateways. O core define uma port:
// Driven Port (interface no core)
interface PagamentoPort {
processar(valor: Money, cartao: Cartao): Promise<ResultadoPagamento>
}
// Caso de uso (driving port + implementação no core)
class CriarPedidoUseCase {
constructor(private pagamento: PagamentoPort, private pedidos: PedidoRepository) {}
async executar(input: NovoPedido) {
const resultado = await this.pagamento.processar(input.total, input.cartao)
if (resultado.aprovado) return this.pedidos.salvar(new Pedido(input))
throw new PagamentoRecusado(resultado.motivo)
}
}
// Secondary Adapters (fora do core)
class StripeAdapter implements PagamentoPort { /* chama SDK Stripe */ }
class MercadoPagoAdapter implements PagamentoPort { /* chama SDK MP */ }Trocar Stripe por Mercado Pago exige zero alteração no core — apenas trocar o binding de injeção de dependência.
Casos de uso reais em B2B brasileiro
- Fintech trocando gateway: uma fintech brasileira migrou de Cielo para Stripe em duas semanas por já ter uma ‘PagamentoPort’. Sem hexagonal, seria refatoração de meses.
- E-commerce B2B multi-canal: um marketplace industrial atende ERP via SOAP, portal web via REST e app mobile via GraphQL — todos como driving adapters sobre o mesmo core de catálogo e pedidos.
- SaaS multi-tenant: plataforma SaaS abstraiu ‘TenantStoragePort’ e roda o mesmo core sobre Postgres (clientes small), MongoDB (mid) e sharding customizado (enterprise), segundo relato publicado no InfoQ Brasil (2024).
Hexagonal vs Clean Architecture vs Onion
| Dimensão | Hexagonal | Clean Architecture | Onion |
|---|---|---|---|
| Autor/Ano | Alistair Cockburn (2005) | Robert C. Martin (2012) | Jeffrey Palermo (2008) |
| Foco | Simetria entre atores primários e secundários | Regra de dependência (setas apontam para dentro) | Domínio no centro, infraestrutura na borda |
| Camadas | Core + Ports + Adapters (2 camadas) | Entities, Use Cases, Interface Adapters, Frameworks (4) | Domain, Domain Services, Application, Infrastructure (4) |
| Vocabulário-chave | Ports, Adapters, Driving/Driven | Use Cases, Boundaries, Gateways | Anemic Domain vs Rich Domain |
| Similaridade | Segundo Martin Fowler (2017), as três variam mais em vocabulário que em substância — todas aplicam inversão de dependência para proteger o domínio. | ||
Vantagens da Arquitetura Hexagonal
- Testabilidade extrema: segundo estudo da IEEE Software (2021), sistemas hexagonais apresentaram cobertura de testes 34% superior comparado a arquiteturas em camadas tradicionais, com testes unitários rodando sem banco ou HTTP.
- Independência de framework: trocar Spring por Quarkus, Express por Fastify ou Django por FastAPI se torna um trabalho de adapter, não de reescrita.
- Independência de banco: migrar de Postgres para MongoDB ou introduzir cache Redis não altera regras de negócio.
- Alinhamento com DDD: o padrão dá um lar arquitetural aos conceitos de Domain-Driven Design (Eric Evans, 2003) — agregados, repositórios e serviços de domínio moram no core.
- Longevidade do software: segundo o GitHub Octoverse (2023), projetos com arquitetura desacoplada (hexagonal, clean, onion) tiveram 42% menos abandono após 5 anos comparado a monolitos acoplados.
Desvantagens e quando NÃO usar
- Overhead em CRUDs simples: aplicar hexagonal em um CRUD com 3 telas é over-engineering. Segundo o ThoughtWorks Radar (2022), ‘padrões arquiteturais complexos aplicados a problemas simples são o principal driver de custo escondido’.
- Curva de aprendizado: desenvolvedores acostumados a MVC tradicional levam semanas para internalizar a inversão.
- Mais classes e interfaces: onde havia uma classe, agora há port + adapter + injeção. O boilerplate é real.
- Risco de abstração prematura: criar ports para tudo, incluindo coisas que nunca vão mudar, gera complexidade sem retorno.
Regra prática: use hexagonal quando o sistema tem vida longa esperada (5+ anos), múltiplas integrações externas ou alta necessidade de testes automatizados.
Estrutura de pastas típica
src/
├── domain/ # Entidades, VOs, exceptions de domínio
│ ├── model/
│ └── ports/ # PagamentoPort, PedidoRepository
├── application/ # Casos de uso (driving ports)
│ └── usecases/
└── infrastructure/
├── adapters/
│ ├── inbound/ # REST controllers, CLI, consumers
│ └── outbound/ # StripeAdapter, PostgresPedidoRepository
└── config/ # Injeção de dependênciaTestes em Arquitetura Hexagonal
- Unit tests do core: testam casos de uso e entidades usando mocks/fakes dos ports. Rodam em milissegundos, sem infraestrutura.
- Integration tests dos adapters: validam cada adapter isoladamente contra a tecnologia real (Testcontainers para banco, WireMock para APIs externas).
- Contract tests: garantem que o adapter cumpre o contrato do port. Ferramentas como Pact ou Spring Cloud Contract ajudam.
- Acceptance tests: testam o sistema end-to-end através de driving adapters, geralmente com Cucumber ou similar.
Erros comuns em Arquitetura Hexagonal
- Vazamento de detalhes do adapter no core: importar ‘HttpException’ do Express dentro do domínio quebra o isolamento. O core deve lançar exceções de domínio.
- Ports genéricos demais: criar uma ‘GenericRepository<T>’ anula a expressividade do domínio. Prefira ‘PedidoRepository’ com métodos que refletem o negócio.
- Aplicar em projeto pequeno: hexagonal em MVP de fim de semana é overkill garantido.
- Adapters gigantes: um único adapter com 2.000 linhas orquestrando Stripe + email + log + auditoria viola SRP. Divida por responsabilidade.
- Sem separação driving/driven: misturar interfaces de entrada e saída no mesmo pacote gera confusão. Mantenha ‘inbound/’ e ‘outbound/’ separados.
Como implementar Arquitetura Hexagonal — passo a passo
- Mapeie o domínio: identifique entidades, agregados e regras de negócio essenciais. Faça Event Storming se possível.
- Isole o core: crie um módulo/pasta ‘domain’ sem qualquer import de framework, ORM ou biblioteca de infraestrutura.
- Defina os driven ports: para cada capacidade externa que o core precisa (persistir, notificar, pagar), crie uma interface no core.
- Defina os driving ports: exponha os casos de uso como interfaces que os adapters de entrada consumirão.
- Implemente os adapters secundários: Postgres, Redis, Stripe, cada um implementando seu port respectivo.
- Implemente os adapters primários: REST controllers, consumers de fila, comandos CLI — todos delegando aos driving ports.
- Configure a injeção de dependência: use o container do framework (Spring, NestJS, Symfony) para conectar ports a adapters em runtime.
Arquitetura Hexagonal e a Shiftmind
A adoção de padrões arquiteturais robustos exige um parceiro técnico que compreenda tanto software quanto infraestrutura. A criação de sites e sistemas WordPress pela Shiftmind aplica princípios de separação de responsabilidades adaptados ao ecossistema PHP, garantindo código de longo prazo. Nosso serviço de suporte e manutenção WordPress preserva a integridade de plugins customizados construídos com boas práticas arquiteturais. Sistemas exigentes precisam de infraestrutura à altura: nossa hospedagem WordPress dedicada e nossos servidores dedicados oferecem o ambiente ideal para aplicações com múltiplas integrações. Para negócios que combinam tecnologia sólida com estratégia comercial, oferecemos consultoria em marketing digital B2B 4.0, alinhando engenharia e crescimento.
Perguntas frequentes sobre Arquitetura Hexagonal
Arquitetura Hexagonal é o mesmo que Clean Architecture?
Não são idênticas, mas são intimamente relacionadas. A Hexagonal (Cockburn, 2005) foi criada primeiro e propõe uma visão simétrica com dois tipos de adapters. A Clean Architecture (Uncle Bob, 2012) introduz camadas concêntricas mais explícitas — Entities, Use Cases, Interface Adapters, Frameworks. Segundo Martin Fowler (2017), ambas aplicam o mesmo princípio fundamental de inversão de dependência para proteger o domínio, variando principalmente em vocabulário e granularidade das camadas.
Quando devo usar Arquitetura Hexagonal?
Use quando o sistema tem expectativa de vida útil superior a 3-5 anos, envolve múltiplas integrações externas (gateways, filas, APIs de terceiros), precisa de alta cobertura de testes ou está sujeito a trocas de tecnologia no futuro. Segundo o ThoughtWorks Radar (2023), sistemas B2B empresariais são os candidatos ideais. Evite em MVPs, protótipos, scripts descartáveis ou CRUDs administrativos simples — o overhead não se paga.
Arquitetura Hexagonal funciona com microsserviços?
Sim, e a combinação é frequente. Cada microsserviço pode ter sua própria arquitetura hexagonal internamente, com o core isolado e adapters expondo REST/gRPC (driving) e chamando bancos, filas e outros serviços (driven). Segundo o InfoQ Trends Report (2023), 61% dos times que adotam microsserviços aplicam algum padrão de isolamento de domínio como hexagonal, clean ou onion. A hexagonal ajuda o microsserviço a manter foco em uma capacidade de negócio.
Qual a diferença entre Port e Adapter?
Port é uma interface (contrato abstrato) definida dentro do core da aplicação. Ela declara o que precisa acontecer sem dizer como. Adapter é a implementação concreta desse contrato, sempre fora do core. Uma ‘PagamentoPort’ declara ‘processar(valor, cartao)’; um ‘StripeAdapter’ implementa essa interface chamando a SDK real do Stripe. Trocar o gateway significa criar um novo adapter — o port e o core permanecem intactos, o que é o ganho central do padrão.
Arquitetura Hexagonal exige DDD?
Não exige, mas combina naturalmente. É possível aplicar hexagonal em domínios anêmicos, embora o retorno seja menor. Segundo Vaughn Vernon (Implementing DDD, 2013), os conceitos de agregado, repositório e serviço de domínio encontram lar arquitetural claro nos componentes hexagonais — o repositório vira driven port, o agregado vive no core, e os application services expõem driving ports. Muitos times adotam ambos juntos por sinergia.
Quanto tempo demora para uma equipe dominar Arquitetura Hexagonal?
Segundo pesquisa da JetBrains DevEcosystem (2023), desenvolvedores experientes em MVC/em camadas levam entre 4 e 12 semanas para produzir código hexagonal idiomático com confiança. O ponto de virada geralmente é o momento em que o time precisa trocar uma integração externa e percebe, na prática, o valor do isolamento. Investir em pair programming, code reviews focados em arquitetura e um projeto de referência interno acelera significativamente a curva.
Termos relacionados
Conclusão
A Arquitetura Hexagonal permanece, mais de duas décadas após sua criação, um dos padrões mais eficazes para construir software B2B que precisa durar. O princípio central — isolar o core do mundo externo através de ports e adapters — é simples de enunciar e transformador quando aplicado com disciplina. Ela não é bala de prata: exige investimento, maturidade da equipe e cenário adequado. Mas para sistemas empresariais com múltiplas integrações, alta necessidade de testes e vida útil longa, o retorno é comprovado. A Shiftmind aplica esses princípios há mais de 12 anos em projetos WordPress customizados, integrações B2B e sistemas SaaS.
Última atualização: Agosto/2026
Precisa de um parceiro técnico que combine arquitetura sólida com infraestrutura confiável? A Shiftmind desenvolve, hospeda e mantém sistemas B2B há mais de uma década. Entre em contato e conheça nossas soluções.
