Arquitetura Hexagonal (Ports & Adapters)

A arquitetura hexagonal, também chamada de Ports & Adapters, coloca a regra de negócio no centro e empurra tudo que é técnico (banco, web, fila) para fora. O objetivo é que o coração do sistema não dependa de detalhes de infraestrutura.

A ideia central

        Web        CLI
         \         /
        [ Adapter ]
            |
         (Porta)
            |
      +-----------+
      |  DOMÍNIO  |   <- regras de negócio
      +-----------+
            |
         (Porta)
            |
        [ Adapter ]
         /        \
      Banco      Fila

O domínio fica no meio. Ele define portas (interfaces). Os adapters implementam essas portas e conectam o mundo externo.

Portas e adapters

• Porta: um contrato, uma interface. Ex.: “salvar pedido”.
• Adapter: a implementação concreta. Ex.: salvar no PostgreSQL, ou num arquivo, ou em memória para testes.

O domínio fala com a porta. Quem implementa fica de fora.

// Porta (definida pelo domínio)
interface RepositorioPedido {
  salvar(pedido)
  buscar(id)
}

// Adapter (na infraestrutura)
class RepositorioPedidoSQL implements RepositorioPedido {
  salvar(pedido) { /* grava no banco */ }
  buscar(id)     { /* lê do banco */ }
}

Isolar a entrada e saída (I/O)

A regra é simples: o domínio nunca importa banco, framework web ou biblioteca de fila. Esses detalhes vivem só nos adapters. Assim você troca o banco sem tocar na lógica.

Vantagens

• Domínio testável sem banco nem rede.
• Fácil trocar tecnologias (banco, API, fila).
• Regras de negócio claras e isoladas.

Desvantagens

• Mais arquivos e abstrações no começo.
• Pode ser exagero para projetos muito simples.

Quando usar

Vale a pena em sistemas com regras de negócio ricas e que devem durar anos, onde a infraestrutura pode mudar. Para um script pequeno, é overkill.