Arquitetura Hexagonal

Olhe para o auth-service do Hands-on 3 de fora. Ele é chamado pelo gateway via HTTP, e logo poderia ser chamado por um consumidor Kafka ou por uma ferramenta de linha de comando para administradores; os seus testes também querem chamá-lo. Ele chama outras coisas: o account-service via Feign, uma biblioteca de JWT, talvez o Redis para os tokens revogados. Os diagramas em camadas desenham o HTTP "em cima" e o banco de dados "embaixo", mas, para a lógica de negócio, eles são o mesmo tipo de coisa — o mundo externo — e cada um deles deveria ser substituível sem mexer nas regras de login.

A Arquitetura Hexagonal — também chamada de Ports & Adapters (portas e adaptadores) — foi apresentada por Alistair Cockburn em 2005. A ideia é colocar o núcleo da aplicação no centro e expô-lo por meio de portas (interfaces), às quais se conectam adaptadores externos. O formato de hexágono é arbitrário; ele indica que a aplicação tem vários pontos de entrada/saída equivalentes, sem nenhum lado privilegiado — não existe "em cima" e "embaixo", apenas dentro e fora¹.

flowchart LR
  subgraph hexagon [Núcleo da aplicação]
    domain[Modelo de domínio]
    app[Serviços de aplicação]
    inport[«porta»\nInterfaces de entrada]:::port
    outport[«porta»\nInterfaces de saída]:::port
    domain <--> app
    app --> inport
    app --> outport
  end

  rest([REST Controller]):::adapter -->|adaptador de entrada| inport
  cli([CLI]):::adapter -->|adaptador de entrada| inport
  test([Suíte de testes]):::adapter -->|adaptador de entrada| inport

  outport -->|adaptador de saída| db[(Banco de dados)]:::adapter
  outport -->|adaptador de saída| mq([Message broker]):::adapter
  outport -->|adaptador de saída| ext([API externa]):::adapter

  classDef port fill:#adf,stroke:#36c
  classDef adapter fill:#fd9,stroke:#a60

Portas

Uma porta é uma interface pura — um contrato definido pelo núcleo da aplicação, e não pela tecnologia externa. Existem dois tipos:

Portas primárias (de entrada)

As portas primárias representam o que a aplicação sabe fazer — são a API dos casos de uso. Qualquer ator externo que queira interagir com a aplicação precisa passar por uma porta primária.

// Defined inside the application core
public interface AuthService {
    TokenOut login(String email, String password);
    void logout(String token);
}

A implementação dessa interface também vive dentro do núcleo — é o serviço de aplicação:

// Also inside the core — depends only on secondary ports
public class AuthServiceImpl implements AuthService {
    private final AccountRepository accounts; // ← secondary port
    private final JwtService jwt;

    @Override
    public TokenOut login(String email, String password) {
        Account account = accounts.findByEmail(email)
            .filter(a -> a.matchesPassword(password))
            .orElseThrow(InvalidCredentialsException::new);
        return new TokenOut(jwt.generate(account));
    }
}

Portas secundárias (de saída)

As portas secundárias representam o que a aplicação precisa do mundo externo — persistência, mensageria, APIs externas. O núcleo define a interface; a infraestrutura fornece a implementação.

// Defined inside the application core
public interface AccountRepository {
    Optional<Account> findByEmail(String email);
    Account save(Account account);
}

Adaptadores

Um adaptador é uma classe que traduz entre uma tecnologia externa e o contrato de uma porta. Ele vive fora do núcleo e depende dele — nunca o contrário.

// Adapter: translates HTTP → primary port
@RestController
public class AuthController {
    private final AuthService authService; // ← primary port

    public AuthController(AuthService authService) {
        this.authService = authService;
    }

    @PostMapping("/auth/login")
    public ResponseEntity<TokenOut> login(@RequestBody LoginIn in) {
        TokenOut token = authService.login(in.email(), in.password());
        return ResponseEntity.ok(token);
    }
}

// Any driver can plug into the same primary port
public class AuthCLI {
    private final AuthService authService;

    public void run(String[] args) {
        String email = args[0], password = args[1];
        TokenOut token = authService.login(email, password);
        System.out.println("Token: " + token.token());
    }
}

// Adapter: translates secondary port → JPA
@Repository
public class AccountJpaAdapter implements AccountRepository {

    private final AccountJpaRepository jpa;

    @Override
    public Optional<Account> findByEmail(String email) {
        return jpa.findByEmail(email).map(AccountMapper::toDomain);
    }

    @Override
    public Account save(Account account) {
        AccountTable table = AccountMapper.toTable(account);
        return AccountMapper.toDomain(jpa.save(table));
    }
}

// Swap the JPA adapter for a map in tests — no Spring context needed
public class InMemoryAccountRepository implements AccountRepository {
    private final Map<String, Account> store = new HashMap<>();

    @Override
    public Optional<Account> findByEmail(String email) {
        return Optional.ofNullable(store.get(email));
    }

    @Override
    public Account save(Account account) {
        store.put(account.email(), account);
        return account;
    }
}

Uma requisição atravessando o hexágono

Um login atravessa o hexágono duas vezes: entra por uma porta primária, sai por uma porta secundária e volta.

sequenceDiagram
    autonumber
    participant GW as gateway
    participant In as AuthController (adaptador de entrada)
    participant Core as AuthServiceImpl (núcleo)
    participant Out as AccountJpaAdapter (adaptador de saída)
    participant DB as Postgres
    GW->>In: POST /auth/login {email, password}
    In->>Core: login(email, password) pela porta AuthService
    Core->>Out: findByEmail(email) pela porta AccountRepository
    Out->>DB: SELECT ... WHERE email = ?
    DB-->>Out: linha
    Out-->>Core: Account (mapeada de AccountTable)
    Core->>Core: matchesPassword, gera o JWT
    Core-->>In: TokenOut
    In-->>GW: 200 OK + token

Troque o primeiro participante por um teste e o quarto por InMemoryAccountRepository, e o núcleo roda exatamente o mesmo código — essa é toda a ideia.

Os serviços da loja como hexágonos

Exemplo completo

Os arquivos abaixo mostram a fatia completa de autenticação do auth-service. Cada arquivo está anotado com a sua localização em relação à fronteira do hexágono.

1
2
3
4
5
6
7

// Primary port — defined BY the application core.
// Expresses what the authentication use case can do, in domain language.
public interface AuthService {
    TokenOut login(String email, String password);
    void register(RegisterIn in);
    void logout(String token);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// Primary port implementation — also lives inside the application core.
// Depends on secondary ports (AccountRepository, TokenRepository) and on JwtService.
// In a stricter design JwtService would also be a port (e.g. TokenIssuer) with a JJWT adapter.
public class AuthServiceImpl implements AuthService {

    private final AccountRepository accounts;  // secondary port
    private final TokenRepository tokens;      // secondary port
    private final JwtService jwt;

    public AuthServiceImpl(AccountRepository accounts,
                           TokenRepository tokens,
                           JwtService jwt) {
        this.accounts = accounts;
        this.tokens   = tokens;
        this.jwt      = jwt;
    }

    @Override
    public TokenOut login(String email, String password) {
        // Same error for "unknown email" and "wrong password": telling them apart
        // would let an attacker discover which emails are registered.
        Account account = accounts.findByEmail(email)
            .filter(a -> a.matchesPassword(password))
            .orElseThrow(() -> new InvalidCredentialsException("Invalid credentials"));
        String token = jwt.generate(account);
        tokens.store(token, account.id());
        return new TokenOut(token);
    }

    @Override
    public void register(RegisterIn in) {
        if (accounts.findByEmail(in.email()).isPresent())
            throw new DomainException("Email already registered");
        accounts.save(Account.of(in));
    }

    @Override
    public void logout(String token) {
        tokens.revoke(token);
    }
}

1
2
3
4
5
6
7

// Secondary port — defined BY the application core, implemented by the infrastructure.
// Expressed in domain terms: findByEmail, not findByEmailAddress or selectByEmail.
public interface AccountRepository {
    Optional<Account> findByEmail(String email);
    Optional<Account> findById(String id);
    Account save(Account account);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// Driving adapter — translates HTTP requests into primary port calls.
// Lives outside the hexagon. Depends on the AuthService interface (primary port).
@RestController
@RequestMapping("/auth")
public class AuthController {

    private final AuthService authService;  // primary port

    public AuthController(AuthService authService) {
        this.authService = authService;
    }

    @PostMapping("/login")
    public ResponseEntity<TokenOut> login(@RequestBody @Valid LoginIn in) {
        TokenOut token = authService.login(in.email(), in.password());
        return ResponseEntity.ok(token);
    }

    @PostMapping("/register")
    @ResponseStatus(HttpStatus.CREATED)
    public void register(@RequestBody @Valid RegisterIn in) {
        authService.register(in);
    }

    @PostMapping("/logout")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void logout(@RequestHeader("Authorization") String bearer) {
        authService.logout(bearer.replace("Bearer ", ""));
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// Driven adapter — implements the AccountRepository secondary port using JPA.
// Lives outside the hexagon. The core never imports this class.
@Repository
public class AccountJpaAdapter implements AccountRepository {

    private final AccountJpaRepository jpa;

    public AccountJpaAdapter(AccountJpaRepository jpa) {
        this.jpa = jpa;
    }

    @Override
    public Optional<Account> findByEmail(String email) {
        return jpa.findByEmail(email).map(AccountMapper::toDomain);
    }

    @Override
    public Optional<Account> findById(String id) {
        return jpa.findById(id).map(AccountMapper::toDomain);
    }

    @Override
    public Account save(Account account) {
        return AccountMapper.toDomain(jpa.save(AccountMapper.toTable(account)));
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// Test adapter — in-memory implementation of the AccountRepository secondary port.
// Used in unit tests to drive the core without any infrastructure.
public class InMemoryAccountRepository implements AccountRepository {

    private final Map<String, Account> byId    = new HashMap<>();
    private final Map<String, Account> byEmail = new HashMap<>();

    @Override
    public Optional<Account> findByEmail(String email) {
        return Optional.ofNullable(byEmail.get(email));
    }

    @Override
    public Optional<Account> findById(String id) {
        return Optional.ofNullable(byId.get(id));
    }

    @Override
    public Account save(Account account) {
        byId.put(account.id(), account);
        byEmail.put(account.email(), account);
        return account;
    }
}

Estratégia de testes

A principal lição da Arquitetura Hexagonal para os testes é que o núcleo da aplicação pode ser totalmente testado sem nenhuma infraestrutura. Substitua cada adaptador de saída por um stub em memória e acione a porta primária diretamente a partir de um teste.

flowchart LR
  test([Teste JUnit]):::adapter -->|aciona| AuthService
  AuthService --> AccountRepository
  AccountRepository -->|implementada por| InMemory([InMemoryAccountRepository]):::adapter

  classDef adapter fill:#fd9,stroke:#a60

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// Pure unit test — no Spring context, no database, no HTTP server.
// The in-memory adapter replaces JPA; the core is tested in isolation.
class AuthServiceTest {

    private final InMemoryAccountRepository accounts = new InMemoryAccountRepository();
    private final InMemoryTokenRepository   tokens   = new InMemoryTokenRepository();
    private final JwtService                jwt      = new JwtService("test-secret");
    private final AuthService               service  =
        new AuthServiceImpl(accounts, tokens, jwt);

    @Test
    void loginSucceeds_whenCredentialsMatch() {
        accounts.save(Account.of(new RegisterIn("Ada", "ada@example.com", "securepass")));

        TokenOut result = service.login("ada@example.com", "securepass");

        assertThat(result.token()).isNotBlank();
    }

    @Test
    void loginFails_whenPasswordIsWrong() {
        accounts.save(Account.of(new RegisterIn("Ada", "ada@example.com", "securepass")));

        assertThatThrownBy(() -> service.login("ada@example.com", "wrongpassword"))
            .isInstanceOf(InvalidCredentialsException.class);
    }

    @Test
    void register_failsWhenEmailAlreadyExists() {
        var in = new RegisterIn("Ada", "ada@example.com", "securepass");
        service.register(in);

        assertThatThrownBy(() -> service.register(in))
            .isInstanceOf(DomainException.class)
            .hasMessageContaining("already registered");
    }
}

Sem @SpringBootTest, sem H2, sem porta 8080 — o teste roda em milissegundos e cobre a regra de negócio diretamente.

Estrutura de pacotes sugerida

com.example.auth/
├── domain/                         ← Domain Model
│   └── Account.java                # Aggregate root — no framework annotations
├── application/                    ← Application Services + Ports
│   ├── AuthService.java            # Primary port (interface)
│   ├── AuthServiceImpl.java        # Primary port implementation
│   └── port/
│       └── AccountRepository.java  # Secondary port (interface)
├── adapter/
│   ├── in/
│   │   └── AuthController.java     # Driving adapter (REST)
│   └── out/
│       ├── AccountJpaAdapter.java  # Driven adapter (JPA)
│       ├── AccountTable.java       # @Entity — stays in the adapter
│       └── AccountMapper.java

Erros comuns

Pontos-chave

• A aplicação tem um dentro (domínio + serviços de aplicação) e um fora (todo o resto); não existe um "em cima" ou "embaixo" privilegiado.
• Portas são interfaces que pertencem ao núcleo: as portas de entrada/primárias dizem o que a aplicação oferece; as portas de saída/secundárias dizem do que ela precisa.
• Adaptadores traduzem entre uma tecnologia e uma porta: REST, CLI, listeners Kafka e testes acionam o núcleo; JPA, Feign, Redis e produtores Kafka são acionados por ele.
• As portas são nomeadas em termos do domínio, nunca moldadas pela tecnologia por trás delas.
• Trocar os adaptadores de saída por versões em memória permite testar o núcleo com JUnit puro em milissegundos — compare com as camadas da Clean Architecture, que descrevem o interior do hexágono.

Introduções em vídeo: CodeOpinion² (em inglês) e Fernanda Kipper³ (em português).