Hexagonal Architecture in Spring Boot

Hexagonal Architecture, also known as Ports and Adapters, is a design pattern aimed at isolating the central logic of an application from external technical concerns like databases, user interfaces, or third-party services.

In the Spring Boot ecosystem, it’s common to find projects where business logic is tightly coupled with JPA annotations or web controller dependencies. This article explores how to break that coupling.

Why Hexagonal?

Imagine your application as a “hexagon.” At its center lies the Domain, containing pure business rules. Nothing from the outside should contaminate this core. Communication with the external world happens through:

1. Ports: Interfaces that define what the domain wants to do, but not how.
2. Adapters: Concrete implementations that translate external calls into the domain (Primary Adapters) or from the domain to the outside world (Secondary Adapters).

Project Structure

A typical structure following this pattern would look like this:

1
com.example.project
2
├── domain
3
│   ├── model       (Pure POJO classes)
4
│   ├── service     (Business logic)
5
│   └── ports       (Input and output interfaces)
6
├── infrastructure
7
│   ├── adapters
8
│   │   ├── input   (REST Controllers, CLI)
9
│   │   └── output  (JPA Repositories, HTTP Clients)
10
│   └── config      (Spring Configuration)

1. The Domain Core

This is where your application’s “truth” resides. We avoid using annotations like @Entity or @Table here to keep it independent from JPA.

1
public class Order {
2
    private UUID id;
3
    private List<Product> products;
4
    private OrderStatus status;
5

6
    public void confirm() {
7
        if (products.isEmpty()) {
8
            throw new BusinessException("Cannot confirm an empty order");
9
        }
10
        this.status = OrderStatus.CONFIRMED;
11
    }
12
}

2. The Ports

We define interfaces for our requirements. For instance, an output port to save orders:

1
public interface OrderRepositoryPort {
2
    Order save(Order order);
3
    Optional<Order> findById(UUID id);
4
}

3. The Adapters

A secondary adapter would implement the output port using JPA:

1
@Component
2
public class JpaOrderAdapter implements OrderRepositoryPort {
3
    private final SpringDataOrderRepository repository;
4

5
    @Override
6
    public Order save(Order order) {
7
        OrderEntity entity = OrderMapper.toEntity(order);
8
        return OrderMapper.toDomain(repository.save(entity));
9
    }
10
}

Benefits of this Approach

1. Testability: You can test business logic without spinning up a Spring context or a real database.
2. Technological Independence: If you decide to switch from MySQL to MongoDB, you only change the infrastructure adapter; the domain remains untouched.
3. Long-term Maintainability: The code is easier to read, and responsibilities are clearly delimited.

Conclusion

Implementing Hexagonal Architecture in Spring Boot requires more initial effort due to the creation of mappers and multiple layers. However, for applications meant to grow and evolve over years, it’s one of the best investments a developer can make.