Hexagonal Architecture, also known as Ports and Adapters, is a powerful pattern for building modular, testable, and adaptable microservices. In this blog, we’ll walk through:
- What Hexagonal Architecture is
- How to structure your Spring Boot microservice using this pattern
- Folder-by-folder explanation
- Real-world code snippets
- Why it matters
🧠 What Is Hexagonal Architecture?
Hexagonal Architecture is about keeping the core business logic independent from external systems like databases, HTTP servers, messaging systems, etc.
Your application should talk to the world through well-defined "ports", and the world connects to your application via "adapters".
🖼️ Diagram: High-Level View
+---------------------------+
| Inbound Adapters |
| (REST, Kafka, GraphQL) |
+-------------+-------------+
|
+--------▼--------+
| Inbound Port |
+--------+--------+
|
+---------▼----------+
| Application / |
| Use Cases |
+---------+----------+
|
+--------▼--------+
| Domain Layer |
+--------+--------+
|
+--------▼--------+
| Outbound Port |
+--------+--------+
|
+-------------▼-------------+
| Outbound Adapters |
| (DB, REST APIs, Files, etc)|
+---------------------------+
🧳 Real-World Folder Structure
src
└── main
└── java
└── com.example.orderms
├── domain
│ ├── model
│ ├── repository ← Outbound Ports
│ └── service
│
├── application
│ └── usecase ← Inbound Ports
│
├── adapter
│ ├── inbound ← REST, Kafka, etc.
│ └── outbound ← DB, REST Clients, etc.
│
├── config ← Spring Configuration
│
└── OrdermsApplication.java
🔍 Detailed Folder Breakdown
1. 📦 domain/ – Core Business Logic (Pure Java)
Contains your business entities, domain services, and interfaces that define what your application depends on. No Spring, no annotations — just clean domain logic.
✅ Structure:
domain
├── model
│ └── Order.java
├── repository
│ └── OrderRepository.java
└── service
└── OrderService.java
✅ Order.java
public class Order {
private String id;
private String productId;
private int quantity;
private OrderStatus status;
// constructors, getters, setters
}
✅ OrderRepository.java
public interface OrderRepository {
Order save(Order order);
Optional<Order> findById(String id);
}
This is a Port — we will create an adapter to implement it using JPA.
2. ⚙️ application/usecase/ – Application Logic (Use Cases)
This layer orchestrates domain logic. It's the command center of the app, delegating to domain services or calling outbound ports.
✅ Example:
application
└── usecase
├── PlaceOrderUseCase.java
└── CancelOrderUseCase.java
✅ PlaceOrderUseCase.java
public interface PlaceOrderUseCase {
Order execute(OrderRequestDTO request);
}
✅ PlaceOrderService.java
@Service
public class PlaceOrderService implements PlaceOrderUseCase {
private final OrderRepository repository;
public PlaceOrderService(OrderRepository repository) {
this.repository = repository;
}
public Order execute(OrderRequestDTO request) {
Order order = new Order(UUID.randomUUID().toString(), request.getProductId(), request.getQuantity(), OrderStatus.NEW);
return repository.save(order);
}
}
This implements the Inbound Port
PlaceOrderUseCase.
3. 🌐 adapter/inbound/ – Adapters That Call the App (REST, Kafka)
Contains external-facing logic that invokes use cases, such as HTTP controllers, Kafka consumers, CLI commands, etc.
✅ Structure:
adapter
└── inbound
└── rest
├── OrderController.java
└── dto
├── OrderRequestDTO.java
└── OrderResponseDTO.java
✅ OrderController.java
@RestController
@RequestMapping("/orders")
public class OrderController {
private final PlaceOrderUseCase placeOrder;
public OrderController(PlaceOrderUseCase placeOrder) {
this.placeOrder = placeOrder;
}
@PostMapping
public ResponseEntity<OrderResponseDTO> place(@RequestBody OrderRequestDTO request) {
return ResponseEntity.ok(OrderMapper.toResponseDTO(placeOrder.execute(request)));
}
}
4. 🗃️ adapter/outbound/ – Adapters the App Calls (Database, APIs)
Implements Outbound Ports using Spring Data JPA, Feign, WebClient, etc.
✅ Structure:
adapter
└── outbound
└── persistence
├── OrderEntity.java
├── JpaOrderRepository.java
├── OrderMapper.java
└── OrderPersistenceAdapter.java
✅ JpaOrderRepository.java
public interface JpaOrderRepository extends JpaRepository<OrderEntity, String> {
}
✅ OrderPersistenceAdapter.java
@Component
public class OrderPersistenceAdapter implements OrderRepository {
private final JpaOrderRepository jpaRepo;
public OrderPersistenceAdapter(JpaOrderRepository jpaRepo) {
this.jpaRepo = jpaRepo;
}
@Override
public Order save(Order order) {
return OrderMapper.toDomain(jpaRepo.save(OrderMapper.toEntity(order)));
}
@Override
public Optional<Order> findById(String id) {
return jpaRepo.findById(id).map(OrderMapper::toDomain);
}
}
This adapter implements the outbound port from the domain.
5. 🛠️ config/ – Spring Boot Configs
Wires beans and defines application-wide settings.
✅ Structure:
config
├── WebConfig.java
├── AdapterConfig.java
└── SwaggerConfig.java
✅ AdapterConfig.java
@Configuration
public class AdapterConfig {
@Bean
public PlaceOrderUseCase placeOrderUseCase(OrderRepository repository) {
return new PlaceOrderService(repository);
}
}
🔄 Data Flow in Action
User → REST API → UseCase → Domain Logic → Outbound Port → Persistence Adapter → DB
🧪 Testing Strategy
| Layer | Test Type | Tools |
|---|---|---|
| Domain | Unit Tests | JUnit, Mockito |
| UseCase | Unit/Mock Tests | JUnit |
| Adapters | Integration | TestContainers |
| Controller | Web Test | Spring MockMvc |
✅ Benefits of This Architecture
| Feature | Benefit |
|---|---|
| Separation of concerns | Clear boundaries between logic and tech |
| Framework independence | Domain is pure Java |
| Adapter pluggability | Swap DB, APIs, UIs easily |
| Easier testing | Domain logic tested without Spring |
| Scalability & maintainability | Perfect for microservices |
📦 Bootstrap Project Template
I can generate this folder structure into a ready-to-run Maven or Gradle Spring Boot project, complete with:
- Swagger
- JPA
- Flyway
- Testcontainers
- Profiles
Let me know if you want that.
🧠 Summary
Hexagonal architecture helps you design robust, clean, and future-proof microservices by enforcing clear boundaries. With Spring Boot, it's easy to adopt this pattern by structuring your app with:
- Domain (core business logic)
- Application (use cases)
- Ports (interfaces)
- Adapters (framework integrations)
If you’re building microservices in a modern, test-driven, and maintainable way—this structure will take you far.
Top comments (0)