hexagonal-architecture-layers-java

When to Use

Load this skill when:

• Designing a new Java service with clean, testable layers
• Refactoring Spring code to isolate the domain from frameworks
• Supporting multiple adapters (REST + messaging, JPA + Mongo)
• Enforcing dependency direction and clear module boundaries

Critical Patterns

Pattern 1: Domain is pure

Domain has no framework annotations, no persistence concerns, and no I/O.

Pattern 2: Application orchestrates

Application defines use cases and ports, calling domain logic and delegating I/O to ports.

Pattern 3: Infrastructure adapts

Infrastructure implements ports and wires adapters (controllers, repositories, clients).

Code Examples

Example 1: Domain model + output port

package com.acme.order.domain;

public record OrderId(String value) { }

public final class Order {
  private final OrderId id;
  private final Money total;

  public Order(OrderId id, Money total) {
    this.id = id;
    this.total = total;
  }

  public OrderId id() { return id; }
  public Money total() { return total; }
}

package com.acme.order.application.port;

import com.acme.order.domain.Order;
import com.acme.order.domain.OrderId;

public interface OrderRepositoryPort {
  OrderId nextId();
  void save(Order order);
}

Example 2: Application use case + input port

package com.acme.order.application.usecase;

import com.acme.order.application.port.OrderRepositoryPort;
import com.acme.order.domain.Order;
import com.acme.order.domain.OrderId;
import com.acme.order.domain.Money;

public interface PlaceOrderUseCase {
  OrderId place(Money total);
}

public final class PlaceOrderService implements PlaceOrderUseCase {
  private final OrderRepositoryPort repository;

  public PlaceOrderService(OrderRepositoryPort repository) {
    this.repository = repository;
  }

  @Override
  public OrderId place(Money total) {
    OrderId id = repository.nextId();
    Order order = new Order(id, total);
    repository.save(order);
    return id;
  }
}