Arquitetura Hexagonal em 2026: Portas, Adaptadores, Clean

A arquitetura hexagonal (também chamada de portas e adaptadores) coloca a lógica de negócio no centro da aplicação e obriga toda preocupação externa — bancos de dados, HTTP, filas, APIs de terceiros — a falar com ela por meio de interfaces que o núcleo controla. Clean Architecture e Onion Architecture são formulações posteriores da mesma ideia, com camadas mais prescritivas. Se for para lembrar de uma única regra, é esta: as dependências do código-fonte apontam para dentro, e o núcleo nunca importa infraestrutura.

Este guia explica portas e adaptadores com precisão, compara os três estilos lado a lado, percorre um exemplo Orders em TypeScript com adaptadores em memória e Postgres, e lista os erros que transformam o padrão em cerimônia.

O que a arquitetura hexagonal diz de fato

Alistair Cockburn descreveu o padrão em 2005 com um objetivo simples: uma aplicação deveria ser igualmente acionável por usuários, programas, testes automatizados e scripts em lote, e deveria poder ser desenvolvida e testada isoladamente dos dispositivos e bancos de dados do seu ambiente de execução. O formato de hexágono não tem significado especial; ele só dá espaço para desenhar vários lados, um por tipo de ator externo.

O padrão tem três partes:

• O núcleo da aplicação. Modelo de domínio mais lógica de aplicação (casos de uso). Não sabe nada sobre frameworks, transporte ou armazenamento.
• Portas. Interfaces que definem como o núcleo é usado e do que ele precisa. As portas pertencem ao núcleo e são escritas na linguagem do núcleo (placeOrder, OrderRepository), nunca na linguagem da infraestrutura (insertRow, POST /orders).
• Adaptadores. Código na borda que traduz entre uma porta e uma tecnologia concreta. Adaptadores são substituíveis; o núcleo não deveria perceber quando um é trocado.

                         LADO DRIVING                       LADO DRIVEN
              (quem chama a aplicação)              (o que a aplicação chama)

   +-----------+                                                  +----------------+
   | REST ctrl |--+                                            +--| Postgres repo  |
   +-----------+  |                                            |  +----------------+
   +-----------+  |     +--------------------------------+     |  +----------------+
   | CLI       |--+---->| porta driving |  NÚCLEO DA     |     +--| In-memory repo |
   +-----------+  |     | PlaceOrder    |  APLICAÇÃO     |     |  +----------------+
   +-----------+  |     |               |  ------------  |     |  +----------------+
   | Teste     |--+     |               |  Order         |---->+--| SMTP mailer    |
   +-----------+        |               |  OrderLine     |     |  +----------------+
   +-----------+  |     |               |  Money         |     |  +----------------+
   | Fila      |--+     |               |  portas driven |     +--| Payment gateway|
   +-----------+        +--------------------------------+        +----------------+

   Adaptadores IMPLEMENTAM portas driven.   Adaptadores CHAMAM portas driving.
   Todas as setas no código-fonte apontam PARA DENTRO do núcleo.

Portas driving vs portas driven

A distinção que a maioria dos tutoriais embaralha é a direção da chamada.

Portas driving (primárias, de entrada). O mundo externo chama o núcleo por meio delas. Uma porta driving é a API do caso de uso: PlaceOrder.execute(command). O adaptador desse lado é um chamador — um controller HTTP, um resolver GraphQL, um consumidor de mensagens, um cron job, um teste. O núcleo expõe a porta; o adaptador depende dela.

Portas driven (secundárias, de saída). O núcleo chama o mundo externo por meio delas. Uma porta driven é uma necessidade do núcleo: OrderRepository, PaymentGateway, Clock, EventPublisher. O adaptador desse lado é um implementador — um repositório Postgres, um cliente Stripe, um fake para testes. O núcleo declara a interface; o adaptador a implementa e é injetado na inicialização.

Isso é inversão de dependência aplicada na fronteira da aplicação. O núcleo define os dois tipos de porta, então no código-fonte ele não depende de nada fora de si mesmo. A chamada em tempo de execução na direção driven vai para fora, mas a dependência em tempo de compilação continua apontando para dentro, porque a interface mora no núcleo.

Duas consequências:

1. Portas são definidas em termos de tipos de domínio (Order, OrderId, Money), nunca em termos de uma entidade de ORM, um DTO de framework HTTP ou uma linha de banco.
2. Qualquer coisa que o núcleo precise do ambiente — tempo, aleatoriedade, configuração — também é uma porta driven. É isso que o torna determinístico nos testes.

Hexagonal vs Clean vs Onion Architecture

As três são variações da mesma regra. As diferenças estão no vocabulário, em quantas camadas prescrevem e na origem.

Critério	Hexagonal (Portas e Adaptadores)	Onion Architecture	Clean Architecture
Origem	Alistair Cockburn, 2005	Jeffrey Palermo, 2008	Robert C. Martin, 2012
Ideia central	O núcleo fala com o exterior só por portas; adaptadores traduzem	Anéis concêntricos em volta de um modelo de domínio	Círculos concêntricos com uma regra de dependência explícita
Camadas nomeadas	Duas: dentro (núcleo) e fora (adaptadores). Nenhuma camada interna prescrita	Modelo de domínio, serviços de domínio, serviços de aplicação, infraestrutura/UI	Entidades, casos de uso, adaptadores de interface, frameworks e drivers
Regra de dependência	Implícita: adaptadores dependem de portas, o núcleo não depende de nada	Explícita: anéis externos dependem só dos internos	Explícita e nomeada: dependências apontam para dentro; círculos internos não sabem nada dos externos
Terminologia	Porta, adaptador, driving/driven, aplicação	Modelo de domínio, serviço de domínio, serviço de aplicação, infraestrutura	Entidade, caso de uso (interactor), gateway, presenter, controller
Onde vivem as interfaces	No núcleo, sob controle do núcleo	Nos anéis internos (domínio ou aplicação)	No círculo de casos de uso (input/output boundaries, gateways)
Prescreve casos de uso?	Não, mas a "aplicação" faz esse papel	Serviços de aplicação	Sim: um interactor por caso de uso, com portas de entrada/saída
Estrutura de pastas típica	domain/, application/, ports/, adapters/	Domain/, Application/, Infrastructure/, Web/	entities/, usecases/, adapters/, frameworks/
Ponto mais forte	Explicar a fronteira e a testabilidade	Enfatizar o modelo de domínio	Padronizar as camadas internas e a nomenclatura

Leia a tabela e o padrão aparece: a hexagonal responde onde fica a fronteira e quem a implementa; Onion e Clean respondem como organizo o que está dentro da fronteira. A maioria das bases de código em produção que se dizem "hexagonais" usa, na verdade, camadas internas no estilo Clean (domínio, aplicação/casos de uso) com vocabulário hexagonal na borda (portas, adaptadores). É uma combinação sensata, não uma contradição.

Exemplo prático: um módulo Orders em TypeScript

O exemplo abaixo é pequeno o suficiente para ler de uma vez e completo o suficiente para mostrar cada parte: domínio, uma porta driven, dois adaptadores para ela, um caso de uso (porta driving) e um adaptador HTTP.

Estrutura de pastas sugerida

src/
  orders/
    domain/
      Order.ts               # agregado com regras de negócio
      OrderLine.ts
      Money.ts
      errors.ts
    application/
      ports/
        driving/
          PlaceOrder.ts      # interface do caso de uso (porta driving)
        driven/
          OrderRepository.ts # interface de persistência (porta driven)
          Clock.ts
      use-cases/
        PlaceOrderService.ts # implementa PlaceOrder, depende das portas driven
    adapters/
      driving/
        http/
          OrdersController.ts
      driven/
        persistence/
          InMemoryOrderRepository.ts
          PostgresOrderRepository.ts
        SystemClock.ts
  composition/
    container.ts             # liga adaptadores às portas (composition root)
  main.ts

Regra prática: domain/ e application/ precisam compilar sem adapters/. Se você consegue apagar a pasta adapters/ e o núcleo continua passando no type-check, a fronteira está intacta.

Domínio

// src/orders/domain/Order.ts
import { Money } from './Money';
import { OrderLine } from './OrderLine';
import { EmptyOrderError } from './errors';

export type OrderId = string;

export class Order {
  private constructor(
    readonly id: OrderId,
    readonly customerId: string,
    private readonly lines: OrderLine[],
    readonly placedAt: Date,
  ) {}

  static place(id: OrderId, customerId: string, lines: OrderLine[], now: Date): Order {
    if (lines.length === 0) throw new EmptyOrderError(id);
    return new Order(id, customerId, [...lines], now);
  }

  total(): Money {
    return this.lines.reduce((sum, l) => sum.add(l.subtotal()), Money.zero('EUR'));
  }

  getLines(): readonly OrderLine[] {
    return this.lines;
  }
}

O domínio tem comportamento (place, total) e impõe uma invariante (nada de pedidos vazios). Repare que ele recebe now em vez de chamar new Date() — o tempo é uma dependência.

Portas driven

// src/orders/application/ports/driven/OrderRepository.ts
import { Order, OrderId } from '../../../domain/Order';

export interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: OrderId): Promise<Order | null>;
}

// src/orders/application/ports/driven/Clock.ts
export interface Clock {
  now(): Date;
}

O repositório fala em Order, não em linhas. Ele tem exatamente os métodos de que os casos de uso precisam, não uma superfície CRUD genérica.

Porta driving e caso de uso

// src/orders/application/ports/driving/PlaceOrder.ts
export interface PlaceOrderCommand {
  orderId: string;
  customerId: string;
  lines: { sku: string; quantity: number; unitPriceCents: number }[];
}

export interface PlaceOrder {
  execute(command: PlaceOrderCommand): Promise<{ orderId: string; totalCents: number }>;
}

// src/orders/application/use-cases/PlaceOrderService.ts
import { PlaceOrder, PlaceOrderCommand } from '../ports/driving/PlaceOrder';
import { OrderRepository } from '../ports/driven/OrderRepository';
import { Clock } from '../ports/driven/Clock';
import { Order } from '../../domain/Order';
import { OrderLine } from '../../domain/OrderLine';
import { Money } from '../../domain/Money';

export class PlaceOrderService implements PlaceOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly clock: Clock,
  ) {}

  async execute(cmd: PlaceOrderCommand) {
    const lines = cmd.lines.map(
      (l) => new OrderLine(l.sku, l.quantity, Money.of(l.unitPriceCents, 'EUR')),
    );
    const order = Order.place(cmd.orderId, cmd.customerId, lines, this.clock.now());
    await this.orders.save(order);
    return { orderId: order.id, totalCents: order.total().cents };
  }
}

O caso de uso orquestra: monta objetos de domínio, aplica regras, persiste por uma porta, devolve um resultado simples. Ele importa só de domain/ e ports/.

Dois adaptadores para a mesma porta

// src/orders/adapters/driven/persistence/InMemoryOrderRepository.ts
import { OrderRepository } from '../../../application/ports/driven/OrderRepository';
import { Order, OrderId } from '../../../domain/Order';

export class InMemoryOrderRepository implements OrderRepository {
  private readonly store = new Map<OrderId, Order>();
  async save(order: Order) { this.store.set(order.id, order); }
  async findById(id: OrderId) { return this.store.get(id) ?? null; }
}

// src/orders/adapters/driven/persistence/PostgresOrderRepository.ts
import { Pool } from 'pg';
import { OrderRepository } from '../../../application/ports/driven/OrderRepository';
import { Order, OrderId } from '../../../domain/Order';
import { toRows, fromRows } from './OrderMapper';

export class PostgresOrderRepository implements OrderRepository {
  constructor(private readonly pool: Pool) {}

  async save(order: Order) {
    const { header, lines } = toRows(order);
    const client = await this.pool.connect();
    try {
      await client.query('BEGIN');
      await client.query(
        'INSERT INTO orders (id, customer_id, placed_at) VALUES ($1, $2, $3)',
        [header.id, header.customer_id, header.placed_at],
      );
      for (const l of lines) {
        await client.query(
          'INSERT INTO order_lines (order_id, sku, quantity, unit_price_cents) VALUES ($1, $2, $3, $4)',
          [l.order_id, l.sku, l.quantity, l.unit_price_cents],
        );
      }
      await client.query('COMMIT');
    } catch (e) {
      await client.query('ROLLBACK');
      throw e;
    } finally {
      client.release();
    }
  }

  async findById(id: OrderId) {
    const header = await this.pool.query('SELECT * FROM orders WHERE id = $1', [id]);
    if (header.rowCount === 0) return null;
    const lines = await this.pool.query('SELECT * FROM order_lines WHERE order_id = $1', [id]);
    return fromRows(header.rows[0], lines.rows);
  }
}

O mapeamento entre Order e as linhas das tabelas vive no adaptador (OrderMapper). O domínio nunca vê o pg, e o SQL nunca vaza para cima. Trocar Postgres por DynamoDB ou por um ORM é um arquivo novo em adapters/, não uma mudança em application/.

Adaptador HTTP (driving)

// src/orders/adapters/driving/http/OrdersController.ts
import { FastifyInstance } from 'fastify';
import { PlaceOrder } from '../../../application/ports/driving/PlaceOrder';
import { EmptyOrderError } from '../../../domain/errors';

export function registerOrderRoutes(app: FastifyInstance, placeOrder: PlaceOrder) {
  app.post('/orders', async (req, reply) => {
    try {
      const result = await placeOrder.execute(req.body as any); // em código real, valide com um schema
      return reply.code(201).send(result);
    } catch (e) {
      if (e instanceof EmptyOrderError) return reply.code(422).send({ error: e.message });
      throw e;
    }
  });
}

O controller traduz HTTP em um comando e erros de domínio em códigos de status. Ele depende da interface PlaceOrder, não de PlaceOrderService, então as mesmas rotas funcionam com qualquer implementação.

Composition root

// src/composition/container.ts
import { Pool } from 'pg';
import { PlaceOrderService } from '../orders/application/use-cases/PlaceOrderService';
import { PostgresOrderRepository } from '../orders/adapters/driven/persistence/PostgresOrderRepository';
import { SystemClock } from '../orders/adapters/driven/SystemClock';

export function buildContainer(env: { DATABASE_URL: string }) {
  const pool = new Pool({ connectionString: env.DATABASE_URL });
  const placeOrder = new PlaceOrderService(new PostgresOrderRepository(pool), new SystemClock());
  return { placeOrder };
}

Este é o único lugar que conhece os dois lados. Frameworks com container de DI (NestJS, tsyringe, Spring, .NET) fazem o mesmo trabalho; uma função simples basta para a maioria dos módulos.

Testes: o motivo pelo qual a maioria dos times adota o padrão

Com a fronteira no lugar, os testes se dividem em três níveis, cada um com um papel claro.

Testes do núcleo, sem I/O. Ligue o caso de uso ao repositório em memória e a um relógio fixo. Eles rodam em milissegundos, não precisam de banco nem de container, e são os que você mais escreve.

// PlaceOrderService.test.ts
const orders = new InMemoryOrderRepository();
const clock = { now: () => new Date('2026-08-26T10:00:00Z') };
const service = new PlaceOrderService(orders, clock);

it('rejeita um pedido sem linhas', async () => {
  await expect(service.execute({ orderId: 'o1', customerId: 'c1', lines: [] }))
    .rejects.toBeInstanceOf(EmptyOrderError);
});

it('persiste o pedido e devolve o total', async () => {
  const result = await service.execute({
    orderId: 'o2', customerId: 'c1',
    lines: [{ sku: 'A', quantity: 2, unitPriceCents: 1500 }],
  });
  expect(result.totalCents).toBe(3000);
  expect(await orders.findById('o2')).not.toBeNull();
});

Testes de contrato dos adaptadores. Rode a mesma suíte contra todas as implementações de uma porta driven. Um describeOrderRepositoryContract(factory) compartilhado, executado uma vez para InMemoryOrderRepository e outra para PostgresOrderRepository (contra um Postgres real em container), garante que o fake se comporta como a produção. É esse passo que mantém os fakes em memória honestos.

Testes end-to-end enxutos. Um punhado deles pelo adaptador HTTP, para provar a ligação. Não um por regra de negócio; as regras já estão cobertas no primeiro nível.

O resultado prático é um ciclo de feedback rápido na CI e uma suíte de testes que sobrevive intacta a uma migração de infraestrutura. Para o argumento mais amplo, veja benefícios do TDD para o negócio.

Erros comuns

Domínio anêmico. Entidades que são sacos de getters e setters, com toda a lógica em "services". Aí você tem um hexágono protegendo nada. Se Order não consegue calcular o próprio total nem rejeitar uma lista de linhas vazia, a fronteira é decoração cara. Empurre as regras para os objetos de domínio; mantenha os casos de uso como orquestração.

Vazar entidades de ORM pelas portas. Uma porta cuja assinatura é save(entity: PrismaOrder) ou findById(): Promise<TypeOrmOrderEntity> fez o núcleo depender da biblioteca de banco. A correção é um mapper dentro do adaptador e tipos de domínio na porta, como no exemplo acima. O mesmo vale para DTOs HTTP no lado driving: o caso de uso recebe um comando, não um objeto de request.

Abstrair demais um app CRUD. Um formulário que grava uma linha e a lê de volta não precisa de um caso de uso, duas portas e três adaptadores. Você ganha quatro arquivos por campo e proteção nenhuma, porque não há regras para proteger. Reserve o padrão para módulos com lógica de verdade.

Interfaces de repositório genéricas. Repository<T> com findAll, findWhere, count convida a camada de aplicação a escrever queries. Portas devem listar as operações de que os casos de uso realmente precisam, nomeadas em termos de domínio.

Framework no núcleo. Decorators do framework web em casos de uso, @Injectable() em classes de domínio, exceções de framework cruzando a porta. Alguns times aceitam um decorator de DI em application/; nenhum deveria aceitar em domain/.

Um hexágono para o sistema inteiro. Uma única pasta application/ com 200 casos de uso é um monolito em camadas com nomes novos. Desenhe um hexágono por bounded context ou módulo, como discutido abaixo.

Quando não usar arquitetura hexagonal

Um checklist de decisão. Se a maioria das respostas for "não", uma estrutura em camadas mais simples vai servir melhor.

• O módulo contém regras de negócio além de validação de entrada e persistência?
• É plausível que uma dependência driven (banco, provedor de pagamento, mensageria) mude durante a vida do produto?
• Você precisa de testes rápidos que rodem sem infraestrutura?
• Mais de um driver vai chamar a mesma lógica (HTTP e uma fila, ou HTTP e uma CLI)?
• O código vai viver tempo suficiente para a manutenibilidade importar mais do que a velocidade inicial?
• O time entende inversão de dependência, ou há tempo para ensinar?

Pule o padrão em protótipos com vida curta conhecida, CRUD administrativo interno, proxies finos e serviços de cola, e scripts. Pule também se o time não for fazer valer a fronteira; um hexágono com import { Pool } from 'pg' dentro de domain/ é pior do que uma aplicação em camadas honesta, porque promete um isolamento que não existe. Regras de lint (por exemplo, no-restricted-imports do ESLint por pasta, ou o dependency-cruiser) são um seguro barato.

Como se encaixa com DDD, microsserviços e monolitos modulares

Com Domain-Driven Design. O DDD fornece o conteúdo do hexágono: agregados, value objects, eventos de domínio, uma linguagem ubíqua. A hexagonal fornece a casca que mantém esse modelo livre de infraestrutura. Bounded contexts mapeiam naturalmente para hexágonos; anti-corruption layers são só adaptadores entre dois contextos. Veja Domain-Driven Design na prática para o lado da modelagem.

Com monolitos modulares. Este é o ponto ideal em 2026 para a maioria dos produtos de médio porte. Cada módulo (orders/, billing/, catalog/) é um hexágono com as próprias portas e adaptadores, implantado como um único processo. Os módulos falam entre si só por portas driving (ou eventos publicados), nunca pelos repositórios uns dos outros. Como as fronteiras existem no código, extrair um módulo para um serviço depois é, na maior parte, uma mudança no composition root e nos adaptadores.

Com microsserviços. Cada serviço é um hexágono. O padrão mantém o núcleo do serviço independente do transporte (REST hoje, gRPC ou eventos amanhã) e deixa os testes in-process rápidos, o que importa mais em um sistema distribuído, onde testes end-to-end são lentos e instáveis. Ele não resolve as preocupações distribuídas — consistência, contratos entre serviços, observabilidade — que são cobertas em microsserviços vs arquitetura monolítica e estratégias de teste para microsserviços.

Com sistemas orientados a eventos. Um consumidor de mensagens é um adaptador driving; um publicador de eventos é uma porta driven. O núcleo emite eventos de domínio; um adaptador os mapeia para Kafka, SNS ou uma tabela de outbox. Esse mapeamento é o lugar para lidar com serialização e versionamento, não o domínio. Mais sobre o padrão em arquitetura orientada a eventos.

Recomendação

Use arquitetura hexagonal por módulo, não por sistema, e só em módulos com regras de negócio de verdade. Combine com a divisão interna da Clean Architecture (domínio e aplicação/casos de uso) e mantenha o vocabulário hexagonal na borda (portas driving e driven, adaptadores). Defina as portas em tipos de domínio, mapeie para tipos de ORM ou de transporte dentro dos adaptadores, e escreva um teste de contrato que rode contra todo adaptador de uma porta, para que seus fakes continuem fiéis. Faça valer a direção dos imports com ferramentas desde o primeiro dia.

Comece com um monolito modular em que cada módulo é um hexágono; você fica com a maior parte da testabilidade e da substituibilidade dos microsserviços sem o custo operacional, e a porta para a extração continua aberta. Na Arvucore, costumamos recomendar esse formato para produtos que devem viver mais do que um par de anos, e uma estrutura em camadas simples para todo o resto.