Pular para o conteúdo
LabS Atlas
AI For Devs
Entrar

Arquitetura Hexagonal

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

Arquitetura Hexagonal é um estilo de arquitetura de software que isola o núcleo de regras de negócio das tecnologias externas por meio de portas e adaptadores, de modo que trocar um framework ou um provedor não obrigue a reescrever o domínio.

A motivação é longevidade. Código escrito só para resolver o problema de agora pode ser simples e direto; código que vai ser mantido por anos precisa de um desacoplamento lógico entre o que a aplicação faz e as tecnologias com que ela faz. Num sistema de agentes de IA essa separação pesa ainda mais, porque as peças externas mudam rápido: o provedor de modelo, o framework de orquestração, a biblioteca de integração. Quando a regra de negócio vive isolada, essas trocas acontecem na borda.

Portas, adaptadores e domínio na estrutura de pastas

Porta e adaptador são conceitos irmãos: aparecem sempre juntos, na mesma altura da estrutura. Uma organização possível concentra numa pasta application o domínio (as regras de negócio), as portas e os serviços que implementam os adaptadores, deixando numa pasta separada o núcleo que as demais camadas podem consumir.

O ponto que costuma confundir é onde mora a regra de negócio. Na leitura de arquitetura limpa, tudo é domínio: até o código de configuração é tratado como um domínio de infraestrutura. O domínio de negócio propriamente dito é o modelo de negócio, e é ele que o serviço implementa. Uma pasta chamada domain não esgota o assunto, portanto; ela nomeia um dos domínios, não todos.

Quando o custo da arquitetura se justifica

A decisão é de escala de vida do código, não de gosto. Para algo descartável, que resolve um problema de cinco minutos, montar portas e adaptadores é trabalho desperdiçado. Para um projeto que vai receber manutenção por muito tempo, o desacoplamento paga o custo inicial, aplicando responsabilidade única por domínio em vez de concentrar tudo em uma camada de serviço.

Adotar às pressas devolve o problema

Aplicar o desenho sob pressão de entrega, replicando o formato sem entender a razão de cada pasta, tende a produzir uma estrutura só aparentemente hexagonal, com serviços que continuam misturando regra de negócio e integração. O resultado é uma migração pendente, que precisa ser refeita com calma depois.

Relação com o ecossistema de agentes em Java

Em Java, a combinação com Spring AI torna essa organização natural: o framework favorece orientação a objetos bem estruturada, o que facilita separar os agentes, suas ferramentas e seus contratos do código que fala com o modelo de linguagem. Cada agente vira uma peça com responsabilidade declarada, e os pontos de contato com o mundo externo — modelo, repositório, fila de eventos — ficam nos adaptadores. É o mesmo raciocínio que sustenta o desenho de um Agente de IA como conjunto de partes com papéis definidos, aplicado uma camada acima, na aplicação que hospeda esses agentes.