Pular para o conteúdo
thiagoetipadrões

Contatos

apps/architecture/hexagonal

040 · Arquiteturas de Alto Nível (Macro-Architecture) · ≈ 5 min de estudo

Arquitetura Hexagonal (Ports & Adapters)

O domínio fica no centro e define as portas — contratos na língua do negócio. Tudo que é tecnologia (HTTP, linha de comando, PostgreSQL, SMS) vira adaptador plugado nessas portas, trocável sem tocar na regra. Use quando o mesmo núcleo precisa atender várias entradas ou quando a infraestrutura deve poder mudar.

passos
6
arquivos
7
testes
0
tecnologias
5
Infraestrutura realTypeScriptBunElysiaPostgreSQLDocker
CenárioRelaçõesComparar
Baixar cartão

Cenário

Banco digital com transferência entre contas acionada pelo app (HTTP) e pelo backoffice (linha de comando). As duas entradas usam o mesmo núcleo: limite de R$ 50.000,00 por transferência, saldo suficiente, contas existentes e distintas. Concluída a transferência, os dois clientes recebem SMS.

Planta

Fluxo
7/7
Adaptadores condutoresNucleoAdaptadores conduzidoshttp_transferElysia POST /transferscli_transferargv e exit codePorta de entradaInterfaceTransferUseCaseuse_case_transferlimite, saldo, contasPorta de saidaInterfaceAccountRepositoryPorta de saidaInterfaceCustomerNotifierrepository_account_postgresFOR UPDATE em ordemnotifier_postgresfila de SMSimplementaimplementa
7

7 passos — reproduza para seguir o fluxo

Como funciona

6 passos

Domínio no centro, portas e adaptadores.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

FOR UPDATE+9
main.ts+1
  1. 01

    ports/port_transfer.ts declara a porta de entrada (InterfaceTransferUseCase) e as de saída (InterfaceAccountRepository, InterfaceCustomerNotifier), só com tipos do domínio

  2. 02

    core/use_case_transfer.ts aplica a regra recebendo as portas por injeção; recusa é resultado (status: "refused" com motivo), não exceção

  3. 03

    O adaptador HTTP traduz o motivo em 404 ou 422; o adaptador CLI converte "250.50" em centavos e devolve exit code 0 ou 2

  4. 04

    O repositório PostgreSQL trava as duas contas com FOR UPDATE em ordem de id, grava saldos e transferência numa transação

  5. 05

    A notificação sai só depois do commit, pelo adaptador que enfileira o SMS em customer_notifications

  6. 06

    main.ts é o único composition root: instancia os adaptadores concretos e os injeta no núcleo

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

  • Núcleo testado com adaptadores falsos, sem banco

  • Nova entrada (gRPC, fila) reaproveita o núcleo inteiro

  • Trocar PostgreSQL ou o canal de SMS não toca a regra

  • Fronteira explícita entre regra e tecnologia

Custos

  • Mais arquivos e indireções

  • Porta mal desenhada vira CRUD genérico

  • Composition root cresce com o sistema

  • Excesso para um serviço pequeno

apps/architecture/hexagonal

7 arquivos

src/ports/

  • port_transfer.tsPortas de entrada e saída

src/core/

  • use_case_transfer.tsRegra da transferência, sem import de infraestrutura

src/adapters/driving/

  • http_transfer.tsAdaptador condutor HTTP (Elysia)
  • cli_transfer.tsAdaptador condutor de linha de comando

src/adapters/driven/

  • repository_account_postgres.tsAdaptador conduzido de contas (PostgreSQL)
  • notifier_postgres.tsAdaptador conduzido de notificação (fila de SMS)

src/

  • main.tsComposition root

Executar · com Docker

  1. ./docker.sh up# sobe PostgreSQL
  2. cp .env.example .env# variáveis de ambiente
  3. bun install# dependências
  4. bun run demo# roda o cenário
  5. bun run test# integração contra o serviço real
  6. bun run api
  7. bun run cli CC-A CC-B 250.50

API e linha de comando sobre o mesmo núcleo:

Requisitos
BunDocker
Sobe junto
PostgreSQL

Relações

Onde ele se encaixa

Mapa
  1. Hexagonal Architecture
  • Combina com3
  • Alternativa a2

Por que se relacionam

Combina com

Alternativa a

Teste rápido

Qual destes combina com Hexagonal Architecture?

Próximo projeto · Arquiteturas de Alto Nível (Macro-Architecture)Clean Architecture
Esc

↑ ↓ navegarEnter abrir191 resultados