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 ; } } Example 3: Infrastructure adapter + wiring package com . acme . order . infrastructure . persistence ; import com . acme . order . application . port . OrderRepositoryPort ; import com . acme . order . domain . Order ; import com . acme . order . domain . OrderId ; import org . springframework . stereotype . Repository ; @Repository public final class OrderJpaAdapter implements OrderRepositoryPort { private final SpringOrderRepository repository ; private final OrderMapper mapper ; public OrderJpaAdapter ( SpringOrderRepository repository , OrderMapper mapper ) { this . repository = repository ; this . mapper = mapper ; } @Override public OrderId nextId ( ) { return new OrderId ( java . util . UUID . randomUUID ( ) . toString ( ) ) ; } @Override public void save ( Order order ) { repository . save ( mapper . toEntity ( order ) ) ; } } Anti-Patterns Don't: Put framework annotations in domain // BAD: domain tied to JPA @jakarta.persistence.Entity public class Order { @jakarta.persistence.Id private String id ; } Don't: Call infrastructure directly from domain // BAD: domain depends on Spring repository public class Order { private final SpringOrderRepository repository ; } Quick Reference Task Pattern Persist domain data Define output port in application, implement in infrastructure Expose use case Define input port and service in application Keep domain pure No annotations, no I/O, no framework imports Resources Hexagonal Architecture: https://alistair.cockburn.us/hexagonal-architecture/ Clean Architecture: https://www.oreilly.com/library/view/clean-architecture/9780134494272/