Un service Spring Boot typique, après quelques mois d'ajouts successifs, ressemble souvent à ceci : des @Service qui injectent directement des @Repository Spring Data JPA, qui manipulent les entités JPA jusque dans le contrôleur REST, avec de la logique métier éparpillée entre les trois couches selon qui a écrit le code en dernier. Tester une règle métier isolément devient impossible sans démarrer un contexte Spring complet ou une base H2 en mémoire. L'architecture hexagonale répond précisément à ce problème : elle isole le métier de tout ce qui est framework, pour que le métier se teste et évolue indépendamment de Spring, de JPA, ou du protocole d'exposition.
Le principe : ports et adaptateurs
L'idée centrale, posée par Alistair Cockburn, est de placer le domaine métier au centre, sans dépendance vers l'extérieur. Le domaine définit des interfaces, les "ports" : des ports d'entrée (les cas d'usage que l'application expose) et des ports de sortie (ce dont le domaine a besoin pour fonctionner, comme la persistance ou un appel à un service externe). Les adaptateurs implémentent ces ports : un adaptateur d'entrée traduit une requête HTTP ou un message de queue en appel de cas d'usage, un adaptateur de sortie traduit un besoin du domaine (sauvegarder une commande) en appel technique concret (JPA, appel REST, etc.).
La règle de dépendance est stricte : le domaine ne dépend de rien, l'application dépend du domaine, l'infrastructure dépend de l'application et du domaine, jamais l'inverse. Spring rend cette inversion triviale grâce à l'injection de dépendances : on injecte l'interface du port, Spring résout l'implémentation concrète au démarrage.
Structure de package concrète
com.example.orders
├── domain
│ ├── Order.java
│ ├── OrderStatus.java
│ └── OrderPolicy.java
├── application
│ ├── port.in
│ │ └── CancelOrderUseCase.java
│ ├── port.out
│ │ └── OrderRepository.java
│ └── CancelOrderService.java
└── infrastructure
├── adapter.in.web
│ └── OrderController.java
└── adapter.out.persistence
├── OrderJpaEntity.java
├── OrderJpaRepository.java
└── OrderRepositoryAdapter.java
Le package domain ne contient aucune annotation Spring ni JPA. C'est du Java pur, avec les règles métier.
public class Order {
private final OrderId id;
private OrderStatus status;
private final List<OrderLine> lines;
public void cancel() {
if (status == OrderStatus.SHIPPED) {
throw new OrderAlreadyShippedException(id);
}
this.status = OrderStatus.CANCELLED;
}
}
Le port de sortie est une interface définie côté application, exprimée dans le vocabulaire du métier, pas dans celui de la persistance :
public interface OrderRepository {
Optional<Order> findById(OrderId id);
void save(Order order);
}
Le cas d'usage orchestre le domaine via ce port, sans savoir si la persistance est du JPA, du MongoDB ou un simple fichier :
@Service
public class CancelOrderService implements CancelOrderUseCase {
private final OrderRepository orderRepository;
public CancelOrderService(OrderRepository orderRepository) {
this.orderRepository = orderRepository;
}
@Override
@Transactional
public void cancel(OrderId orderId) {
Order order = orderRepository.findById(orderId)
.orElseThrow(() -> new OrderNotFoundException(orderId));
order.cancel();
orderRepository.save(order);
}
}
L'adaptateur de sortie, lui, vit dans infrastructure et porte toute la dépendance vers Spring Data JPA, y compris la traduction entre entité JPA et objet du domaine :
@Component
public class OrderRepositoryAdapter implements OrderRepository {
private final OrderJpaRepository jpaRepository;
private final OrderMapper mapper;
public OrderRepositoryAdapter(OrderJpaRepository jpaRepository, OrderMapper mapper) {
this.jpaRepository = jpaRepository;
this.mapper = mapper;
}
@Override
public Optional<Order> findById(OrderId id) {
return jpaRepository.findById(id.value()).map(mapper::toDomain);
}
@Override
public void save(Order order) {
jpaRepository.save(mapper.toEntity(order));
}
}
L'adaptateur d'entrée côté web traduit la requête HTTP en appel de cas d'usage, sans jamais manipuler l'entité JPA :
@RestController
@RequestMapping("/orders")
public class OrderController {
private final CancelOrderUseCase cancelOrderUseCase;
public OrderController(CancelOrderUseCase cancelOrderUseCase) {
this.cancelOrderUseCase = cancelOrderUseCase;
}
@PostMapping("/{id}/cancel")
public ResponseEntity<Void> cancel(@PathVariable String id) {
cancelOrderUseCase.cancel(new OrderId(id));
return ResponseEntity.noContent().build();
}
}
Pourquoi cette séparation paie, concrètement
Le bénéfice le plus tangible est la vitesse et la fiabilité des tests. Order.cancel() se teste avec un test JUnit pur, sans Spring, sans base de données, en quelques millisecondes :
@Test
void cancel_shouldThrow_whenOrderAlreadyShipped() {
Order order = Order.shipped(OrderId.of("ORD-1"));
assertThrows(OrderAlreadyShippedException.class, order::cancel);
}
Les adaptateurs, eux, se testent avec les outils adaptés à leur couche : @DataJpaTest pour l'adaptateur de persistance avec une base embarquée, @WebMvcTest pour le contrôleur avec le cas d'usage mocké. On évite ainsi les tests d'intégration lourds (@SpringBootTest complet) pour vérifier une règle métier qui n'a rien à voir avec Spring.
Le second bénéfice est la capacité à changer d'infrastructure sans toucher au métier. Remplacer Spring Data JPA par un appel à un service externe, ou ajouter un second adaptateur d'entrée (un consommateur Kafka en plus du contrôleur REST) pour le même cas d'usage, ne demande aucune modification du domaine ni du cas d'usage : seulement un nouvel adaptateur qui implémente le port existant.
Ajouter un second adaptateur d'entrée sans toucher au métier
Le vrai test d'une architecture hexagonale correctement posée est d'ajouter un nouveau mécanisme de livraison sans modifier ni le domaine ni le cas d'usage. Imaginons qu'une annulation de commande doive désormais pouvoir être déclenchée par un message Kafka émis par un système d'entrepôt, en plus du contrôleur REST existant. Avec le port d'entrée CancelOrderUseCase déjà défini, il suffit d'écrire un nouvel adaptateur :
@Component
public class OrderCancellationKafkaListener {
private final CancelOrderUseCase cancelOrderUseCase;
public OrderCancellationKafkaListener(CancelOrderUseCase cancelOrderUseCase) {
this.cancelOrderUseCase = cancelOrderUseCase;
}
@KafkaListener(topics = "warehouse.order-cancellations", groupId = "orders-service")
public void onMessage(OrderCancellationEvent event) {
try {
cancelOrderUseCase.cancel(new OrderId(event.orderId()));
} catch (OrderNotFoundException | OrderAlreadyShippedException ex) {
log.warn("Could not apply cancellation from warehouse event {}: {}", event.orderId(), ex.getMessage());
}
}
}
Ni CancelOrderService, ni Order, ni l'interface OrderRepository n'ont changé. C'est précisément ce que l'inversion de dépendance achète : la règle métier ("on ne peut pas annuler une commande déjà expédiée") n'existe qu'à un seul endroit, et elle s'applique de façon identique, qu'elle soit déclenchée par une requête HTTP ou par un message asynchrone. Sans cette séparation, la tentation aurait été de dupliquer la vérification status == SHIPPED dans le listener Kafka, avec le risque réel qu'elle diverge de la version du contrôleur REST au fil des évolutions.
Réduire le coût du mapping entre domaine et persistance
Le reproche le plus fréquent fait à cette architecture, le volume de code de mapping entre entité JPA et objet du domaine, peut être atténué sans renoncer à la séparation. Un outil comme MapStruct génère le mapper à la compilation à partir d'une simple interface annotée, ce qui évite d'écrire à la main chaque assignation de champ :
@Mapper(componentModel = "spring")
public interface OrderMapper {
Order toDomain(OrderJpaEntity entity);
OrderJpaEntity toEntity(Order order);
}
Cela ne supprime pas la couche de mapping, mais réduit son coût de maintenance à la définition de l'interface : les cas particuliers (une relation imbriquée qui ne se mappe pas de façon triviale, un champ calculé) se règlent avec des méthodes @Mapping explicites, tout en gardant le gros du mapping généré automatiquement et vérifié à la compilation plutôt qu'à l'exécution.
Le compromis qu'il faut assumer
Cette structure a un coût réel : plus de classes, plus de mapping entre objets du domaine et entités JPA, plus d'interfaces à maintenir. Sur un CRUD simple sans règle métier notable, cette discipline est une perte de temps pure : un @Service qui appelle directement un @Repository Spring Data fait exactement le même travail avec un dixième du code. L'architecture hexagonale se justifie quand la logique métier est suffisamment riche et sujette à changement pour que son isolement rapporte plus qu'il ne coûte, ou quand plusieurs mécanismes de livraison (REST, messaging, CLI) doivent partager les mêmes cas d'usage.
Quand la structure seule ne suffit pas
Découper en ports et adaptateurs résout un problème de dépendances, pas un problème de modèle anémique. Si Order reste un simple sac de getters/setters et que toute la logique de cancel() migre dans CancelOrderService, on a déplacé le problème sans le résoudre : le domaine redevient une couche de données déguisée, et les règles métier se retrouvent diluées dans les services applicatifs comme avant, juste dans un package qui porte un nom différent. L'architecture hexagonale donne la bonne structure de dépendances ; c'est la discipline de mettre le comportement dans les objets du domaine (dans l'esprit du DDD) qui donne le bénéfice réel.
À retenir
L'architecture hexagonale en Spring Boot consiste à faire dépendre l'infrastructure du domaine via des interfaces, jamais l'inverse, ce que l'injection de dépendances de Spring rend naturel à mettre en œuvre. Le gain concret est mesurable en vitesse de test et en facilité de changement d'infrastructure ; le coût est un supplément de classes et de mapping qui ne se justifie que si la complexité métier le mérite.
