Un service Spring annoté @Transactional qui lève une exception métier et qui, contre toute attente, commite malgré tout les écritures déjà effectuées, est l'un des bugs les plus déroutants à diagnostiquer, précisément parce que le code semble correct à la lecture. L'annotation est présente, l'exception est bien levée, et pourtant la base de données garde une trace de ce qui aurait dû être annulé. Comprendre pourquoi demande de comprendre comment @Transactional est réellement implémenté, pas seulement ce qu'il est censé faire.
Le mécanisme : un proxy, pas une instruction
@Transactional n'est pas un mot-clé du langage ni une instruction exécutée au moment de l'appel. C'est une annotation lue par Spring AOP, qui enveloppe le bean Spring dans un proxy (JDK dynamic proxy pour une interface, CGLIB pour une classe concrète). Quand un autre bean appelle une méthode annotée, l'appel passe par ce proxy, qui ouvre une transaction, délègue à la méthode réelle, puis commite ou effectue un rollback selon le résultat.
Le piège apparaît quand l'appel se fait depuis la même classe, en interne, sans passer par le proxy :
@Service
public class OrderService {
private final OrderRepository orderRepository;
private final AuditLogService auditLogService;
public OrderService(OrderRepository orderRepository, AuditLogService auditLogService) {
this.orderRepository = orderRepository;
this.auditLogService = auditLogService;
}
public void cancelOrder(Long orderId) {
// appel interne : ceci N'EST PAS intercepté par le proxy de transaction
this.doCancelOrder(orderId);
}
@Transactional
public void doCancelOrder(Long orderId) {
Order order = orderRepository.findById(orderId)
.orElseThrow(() -> new OrderNotFoundException(orderId));
order.cancel();
orderRepository.save(order);
if (order.getTotal().compareTo(BigDecimal.ZERO) > 0) {
throw new RefundRequiredException(orderId);
}
}
}
Ici, cancelOrder appelle doCancelOrder via this, c'est-à-dire directement sur l'objet réel, en contournant totalement le proxy. L'annotation @Transactional sur doCancelOrder est donc ignorée : aucune transaction n'est ouverte, et si orderRepository.save() utilise l'auto-commit par défaut de la connexion, la modification est déjà persistée en base avant même que l'exception ne soit levée. Le rollback attendu n'a jamais eu l'occasion d'exister.
Diagnostiquer : rendre le proxy visible
Le moyen le plus fiable de vérifier qu'une transaction est réellement active est d'activer les logs du framework de transaction :
# application.yml
logging:
level:
org.springframework.transaction: TRACE
org.springframework.orm.jpa: DEBUG
Un appel correctement intercepté produit une ligne explicite : Creating new transaction with name [...]: PROPAGATION_REQUIRED, ISOLATION_DEFAULT. L'absence totale de cette ligne au moment de l'appel à doCancelOrder est la preuve directe du problème, bien plus fiable qu'une relecture du code source.
En test, TransactionSynchronizationManager.isActualTransactionActive() permet d'affirmer programmatiquement qu'une transaction est bien ouverte à un instant donné, ce qui transforme ce diagnostic en assertion automatisée plutôt qu'en inspection manuelle des logs à chaque régression suspectée.
La correction : éviter le self-invocation, pas le contourner
La correction la plus propre consiste à ne pas appeler la méthode transactionnelle depuis la même classe, mais à faire passer l'appel par un autre bean, où Spring injectera naturellement le proxy :
@Service
public class OrderCancellationService {
@Transactional
public void doCancelOrder(Long orderId) {
// ...
}
}
@Service
public class OrderService {
private final OrderCancellationService cancellationService;
public OrderService(OrderCancellationService cancellationService) {
this.cancellationService = cancellationService;
}
public void cancelOrder(Long orderId) {
cancellationService.doCancelOrder(orderId); // passe bien par le proxy
}
}
Scinder le service en deux classes distinctes est préférable à la solution de contournement consistant à récupérer le proxy courant via AopContext.currentProxy() avec @EnableAspectJAutoProxy(exposeProxy = true) : cette dernière fonctionne, mais couple le code applicatif aux détails d'implémentation du framework AOP, et casse silencieusement si quelqu'un retire exposeProxy = true plus tard sans comprendre pourquoi c'était nécessaire.
Le deuxième piège : toutes les exceptions ne déclenchent pas de rollback
Même avec un appel correctement intercepté par le proxy, un deuxième piège attend : par défaut, Spring ne déclenche un rollback que sur une RuntimeException (non vérifiée) ou une Error. Une exception vérifiée (checked exception, qui étend Exception directement) ne déclenche pas de rollback par défaut, même si elle traverse la méthode annotée.
@Transactional
public void processPayment(Long orderId) throws PaymentGatewayException {
Order order = orderRepository.findById(orderId).orElseThrow();
order.markAsPaid();
orderRepository.save(order);
paymentGatewayClient.charge(order); // lève PaymentGatewayException (checked)
}
Si PaymentGatewayException étend Exception et non RuntimeException, la commande est marquée payée en base même si le paiement échoue réellement, parce que Spring commite la transaction malgré l'exception propagée. La correction explicite passe par rollbackFor :
@Transactional(rollbackFor = PaymentGatewayException.class)
public void processPayment(Long orderId) throws PaymentGatewayException {
// ...
}
C'est un comportement documenté mais rarement vérifié tant que personne n'a été mordu par lui, précisément parce qu'il va à l'encontre de l'intuition qu'une exception quelconque devrait toujours annuler la transaction en cours.
Les compromis de la propagation
Spring propose plusieurs types de propagation, et REQUIRES_NEW est souvent utilisé pour isoler un effet de bord qui doit survivre même si la transaction englobante échoue, typiquement un log d'audit :
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void logAuditEvent(AuditEvent event) {
auditRepository.save(event);
}
Ce choix a un coût réel : REQUIRES_NEW suspend la transaction courante et en ouvre une nouvelle, ce qui consomme une connexion supplémentaire du pool pendant que les deux transactions coexistent. Sous forte charge, avec un pool de connexions dimensionné pour un usage normal, multiplier les REQUIRES_NEW dans des chemins d'appel fréquents peut épuiser le pool et provoquer des timeouts qui n'ont rien à voir avec la logique métier d'origine.
Quand @Transactional ne suffit pas
Les appels réseau à l'intérieur d'une transaction sont un piège fréquent : appeler une API HTTP externe (passerelle de paiement, service tiers) depuis une méthode @Transactional maintient la connexion à la base de données ouverte, et les verrous associés aux lignes modifiées, pendant toute la durée de cet appel réseau, potentiellement plusieurs secondes. Sous charge concurrente sur les mêmes lignes, cela peut provoquer des blocages en cascade. La bonne pratique est de sortir l'appel réseau de la transaction, en committant d'abord l'état local, puis en traitant l'appel externe séparément avec sa propre logique de compensation en cas d'échec.
Les transactions en lecture seule profitent d'une optimisation explicite via @Transactional(readOnly = true), qui indique à Hibernate de désactiver le dirty checking automatique sur les entités chargées, réduisant la charge mémoire et CPU sur des endpoints de lecture à fort trafic.
Les tests avec @Transactional méritent une vigilance particulière : Spring Test annule automatiquement la transaction à la fin de chaque test, ce qui est pratique pour l'isolation, mais peut masquer des bugs liés au moment du flush Hibernate (une requête qui dépend d'un flush explicite ne se comporte pas nécessairement de la même façon en production, où le flush survient au commit). TestEntityManager.flush() ou @Commit permettent de vérifier ce comportement explicitement plutôt que de lui faire confiance par défaut.
En bref
@Transactional fonctionne par proxy AOP, ce qui signifie concrètement deux règles à retenir : un appel interne à la même classe ne passe jamais par ce proxy, et seules les exceptions non vérifiées déclenchent un rollback sans configuration explicite. Les deux comportements sont documentés, aucun des deux n'est intuitif, et les deux se découvrent presque toujours en production plutôt qu'en relecture de code.
