Arquitetura Hexagonal
Ports & Adapters — Alistair Cockburn (2005)
Definição
A Arquitetura Hexagonal — também chamada de Ports & Adapters — organiza o software em torno de um núcleo de domínio isolado. Seu princípio central é que a lógica de negócio nunca deve depender de detalhes de infraestrutura: banco de dados, frameworks web, serviços de e-mail, filas de mensagens, etc.
A ideia foi publicada por Alistair Cockburn em 2005 e tornou-se a base para Clean Architecture (Martin) e Onion Architecture (Palermo) — todas variações do mesmo princípio fundamental: inversão de dependência em favor do domínio.
Objetivos
Isolar o Domínio
A lógica de negócio fica em Java puro — sem @Entity, sem @Inject, sem imports de frameworks.
Substituição Livre
Trocar MySQL por MongoDB, REST por eventos? Basta trocar o adaptador. O domínio permanece intocado.
Testabilidade Máxima
O serviço pode ser testado com new BooksService(fakeRepo, fakeNotify) — zero CDI, zero banco.
Fronteiras Explícitas
Cada componente tem uma responsabilidade clara. Adaptadores traduzem; o domínio decide.
O Hexágono — Diagrama Interativo
Clique nos componentes para ver detalhes sobre cada camada da arquitetura.
Componentes em Detalhe
Contém: a entidade Book (com fábrica estática Book.of() que valida ISBN, campos obrigatórios e exemplares), as interfaces de porta (AddBookUseCase, BookRepository, EmailNotification…) e o serviço BooksService. Zero imports de Quarkus, JPA ou CDI.
Interfaces definidas no domínio que expõem as operações disponíveis: AddBookUseCase, ListBookUseCase, UpdateBookUseCase, DeleteBookUseCase. Todos os adaptadores de entrada dependem dessas interfaces — nunca de BooksService diretamente.
Interfaces que o domínio define e os adaptadores implementam: BookRepository (persistência) e EmailNotification (notificação). BooksService depende dessas interfaces — nunca de PanacheBookRepository diretamente.
BookResource (JAX-RS): recebe a requisição HTTP, deserializa o JSON para BookRequest, cria o objeto Book via Book.of() e chama a porta de entrada. Todas as anotações @Path, @POST, @Inject ficam aqui — o domínio não as conhece.
PanacheBookRepository: implementa BookRepository com Hibernate Reactive (Panache) e MySQL. Usa BookMapper (MapStruct) para converter Book ↔ BookEntity. LogEmailNotification: implementa EmailNotification simulando e-mail via log.
ApplicationBeans: instancia BooksService com new (Java puro), recebendo os adaptadores via @Inject CDI, e expõe cada instância como porta de entrada via @Produces. O domínio não tem nenhuma anotação CDI e não sabe que esse arquivo existe.
Regra de Dependência
Todas as setas de import apontam para dentro do hexágono.
BookResource importa
AddBookUseCase (domínio).
PanacheBookRepository importa
BookRepository (domínio).
O domínio não importa nada dos adaptadores. Esta é a Inversão de Dependência (DIP) — o princípio SOLID que fundamenta toda a arquitetura.
Fluxo — POST /books
Vantagens e Quando Usar
| Vantagem | Contexto ideal | Custo |
|---|---|---|
| Domínio 100% testável sem banco ou servidor | Lógica de negócio complexa | Mais arquivos e interfaces |
| Troca de tecnologia sem reescrita do domínio | Múltiplos canais (REST + CLI + eventos) | Curva de aprendizado inicial |
| Fronteiras explícitas entre módulos | Times grandes e projetos de longo prazo | Disciplina da equipe necessária |
| Facilita DDD, CQRS e Event Sourcing | Microsserviços com domínio rico | Excesso em CRUDs simples |
Simulador Interativo
Acompanhe passo a passo o fluxo de uma requisição POST /books através da arquitetura hexagonal.
Referências e Código
Repositório, execução e materiais de aprofundamento
Repositório do Projeto
pw2 — exemplos/hexagonal
Implementação completa em Java 25 + Quarkus 3.x com MySQL, JAX-RS, Hibernate Reactive (Panache), MapStruct e CDI.
github.com/rodrigoprestesmachado/pw2/tree/dev/exemplos/hexagonalStack de Tecnologias
Como Executar
Pré-requisitos
- Java 21+ (recomendado Java 25 para corresponder ao projeto)
- Maven 3.8+
- Docker e Docker Compose (para o MySQL)
Estrutura de Pastas
Materiais de Aprofundamento
Artigo Original — Alistair Cockburn (2005)
O texto fundacional que definiu a arquitetura Ports & Adapters, com a motivação original e exemplos.
alistair.cockburn.us/hexagonal-architecture/Clean Architecture — Robert C. Martin
Livro que expande os princípios hexagonais com "círculos concêntricos" (Entities → Use Cases → Interface Adapters → Frameworks).
Domain-Driven Design — Eric Evans
O livro fundacional do DDD. A arquitetura hexagonal é frequentemente combinada com DDD para modelar domínios ricos.
Quarkus — Guia CDI e Producers
Documentação oficial do Quarkus sobre CDI, @Produces, @ApplicationScoped e wiring de componentes.
quarkus.io/guides/cdi-referenceMapStruct — Mapeamento de Objetos
Biblioteca de geração de código em tempo de compilação usada no projeto para converter Book ↔ BookEntity.
mapstruct.orgMutiny — Programação Reativa no Quarkus
Guia sobre o modelo reativo (Uni, Multi) usado no BookResource para integrar CompletableFuture com JAX-RS.
quarkus.io/guides/mutiny-primer