JPA / Hibernate — 20 pièges à éviter en production

🎯 OBJECTIF

Catalogue condensé des 20 pièges Hibernate/JPA les plus fréquents en production : symptômes, causes, et solutions. À utiliser comme checklist de review de code et de diagnostic de performances.

🧠 MODÈLE MENTAL

La plupart des problèmes Hibernate en production ne viennent pas de bugs Hibernate — ils viennent d'une méconnaissance du mapping ou d'hypothèses incorrectes sur ce que JPA fait automatiquement. Hibernate fait exactement ce que le mapping lui ordonne. Les "surprises" sont des comportements spec-conformes qu'on n'a pas anticipés.

Ce catalogue est organisé par famille : problèmes de chargement (N+1, EAGER, OSIV), problèmes de collections (BAG, orphanRemoval), problèmes d'écriture (bulk, batching, @Version), problèmes de transactions (durée, appels externes), et problèmes de modèle (equals/hashCode, indexes). Chaque piège a un symptôme visible et une correction directe.

1Chargement et requêtes

Piège 1 — OSIV activé

Symptôme : N+1 invisibles pendant la sérialisation JSON, latence imprévisible, DB surchargée
Cause : spring.jpa.open-in-view=true (défaut) garde la session ouverte jusqu'à la fin de la requête HTTP
Solution : spring.jpa.open-in-view=false + construire les DTO dans la transaction avec fetch contrôlé

Piège 2 — JOIN FETCH sur plusieurs collections

Symptôme : résultats dupliqués, consommation mémoire énorme, MultipleBagFetchException
Cause : JOIN FETCH sur 2+ @OneToMany → explosion cartésienne
Solution : une seule collection en JOIN FETCH, ou pattern deux temps (parents puis enfants via IN)

Piège 3 — Pagination + JOIN FETCH collection

Symptôme : HHH90003004, pages incohérentes, très mauvaises performances
Cause : Pageable + JOIN FETCH sur collection → pagination en mémoire
Solution : paginer sur IDs uniquement, puis deuxième requête avec IN + JOIN FETCH

Piège 4 — fetch EAGER partout

Symptôme : gros volumes chargés inutilement, réponses lentes
Cause : @OneToMany(fetch = EAGER) — chargement automatique même quand inutile
Solution : LAZY par défaut, chargement explicite avec EntityGraph ou JOIN FETCH selon le besoin

Piège 5 — N+1 classique sur relations LAZY

Symptôme : 1 + N requêtes SQL dans les logs, DB saturée
Cause : boucle sur entités + accès à une relation LAZY à l'intérieur
Solution : @BatchSize(size=25) / default_batch_fetch_size, ou EntityGraph, ou JOIN FETCH

2Collections

Piège 6 — List sans @OrderColumn (BAG)

Symptôme : DELETE ALL + INSERT ALL pour un seul ajout d'élément
Cause : Hibernate ne peut pas calculer le delta d'une List non ordonnée
Solution : Set si pas d'ordre métier, List + @OrderColumn si ordre nécessaire, ne jamais remplacer la collection entière

Piège 7 — orphanRemoval + remplacement de collection

Symptôme : suppression massive et silencieuse en DB
Cause : entity.setCollection(new ArrayList<>()) avec orphanRemoval=true → tous les enfants deviennent orphelins
Solution : toujours modifier la collection existante (add()/remove()), jamais remplacer l'instance

Piège 8 — cascade = ALL partout

Symptôme : suppressions ou updates inattendus en cascade
Cause : CascadeType.ALL sur des relations partagées propage REMOVE/MERGE sans contrôle
Solution : cascades minimales et intentionnelles — PERSIST seul dans la plupart des cas, REMOVE uniquement pour les agrégats forts

3Modèle et identité

Piège 9 — Mauvais equals/hashCode

Symptôme : remove() inefficace dans les Sets, duplicats, DELETE + INSERT inattendus au lieu d'UPDATE
Cause : equals()/hashCode() basés sur champs mutables ou collections
Solution : baser sur l'ID technique ou une clé métier immuable — jamais sur des champs qui changent

Piège 10 — save() avec ID déjà défini

Symptôme : SELECT + UPDATE au lieu d'INSERT, batching dégradé
Cause : Spring Data voit l'ID non-null → merge() → SELECT pour vérifier l'existence
Solution : persist() pour les vrais inserts, save() uniquement sur entités MANAGED

4Écriture et performances

Piège 11 — JDBC batching inactif sans le savoir

Symptôme : 1 INSERT par entité malgré batch_size configuré
Cause : stratégie IDENTITY, statements non identiques, ou flush trop fréquent
Solution : SEQUENCE + order_inserts=true + order_updates=true + persist() + flush()/clear() par lots

Piège 12 — Bulk UPDATE/DELETE sans flush/clear

Symptôme : incohérences entre mémoire et DB, données périmées dans le L1
Cause : @Modifying bypass Hibernate → L1 désynchronisé
Solution : flushAutomatically=true avant le bulk + clearAutomatically=true après

Piège 13 — @Version + batching non configuré

Symptôme : 1 UPDATE par entité malgré le batching configuré
Cause : batch_versioned_data=false (défaut) désactive le batching sur entités versionnées
Solution : hibernate.batch_versioned_data=true

Piège 14 — Flush surprise (FlushMode AUTO)

Symptôme : UPDATE anticipé, contraintes déclenchées trop tôt, comportement inattendu
Cause : modification d'entité suivie d'un SELECT JPQL → flush automatique avant le SELECT
Solution : réorganiser les opérations, ou FlushMode.COMMIT sur les queries ciblées

5Transactions et concurrence

Piège 15 — Transactions trop longues

Symptôme : OptimisticLockException, timeouts, contention élevée
Cause : logique métier lente + appels externes dans la même @Transactional
Solution : transactions courtes, outbox pattern pour les events, REQUIRES_NEW ciblé

Piège 16 — Hot row (ligne très concurrente)

Symptôme : OptimisticLockException en boucle sur la même ligne
Cause : tous les pods tentent de modifier la même ligne simultanément
Solution : sharding de la ligne, réduction de la fréquence d'update, lock pessimiste en dernier recours

Piège 17 — Appels externes dans la transaction

Symptôme : locks prolongés, rollbacks coûteux, timeout
Cause : appel HTTP/Kafka dans @Transactional → transaction ouverte pendant l'appel externe
Solution : outbox pattern, ApplicationEventPublisher avec after-commit, async hors transaction

6Mémoire et infrastructure

Piège 18 — Persistence Context trop rempli

Symptôme : OOM, GC intensif, ralentissement progressif
Cause : chargement massif d'entités MANAGED sans clear() — L1 conserve tout
Solution : traitement par chunks + flush() + clear() réguliers (tous les N=batch_size)

Piège 19 — Mauvais indexes DB

Symptôme : latence aléatoire, full scan en prod visible dans EXPLAIN ANALYZE
Cause : requêtes filtrées sans index adapté → verrous longs
Solution : EXPLAIN ANALYZE sur les requêtes lentes, index composites adaptés à l'ordre des clauses WHERE

Piège 20 — @Lob / gros champs inutilement chargés

Symptôme : lenteur inexpliquée sur des entités normalement légères
Cause : champ @Lob ou TEXT chargé systématiquement même quand inutile
Solution : table séparée pour les gros champs, projections ou DTO pour éviter le chargement de l'entité complète

⚡ TL;DR — les 5 pièges les plus coûteux en prod

OSIV (Piège 1) ✓ Désactiver spring.jpa.open-in-view et construire les DTO dans la transaction. ⚠ Activé par défaut dans Spring Boot — source n°1 de N+1 invisibles en production.

List BAG (Piège 6) ✓ Utiliser Set pour toutes les collections @OneToMany sauf si l'ordre est métier. ⚠ Un seul ajout à une List de 500 éléments = 501 DELETE + 501 INSERT.

IDENTITY + batching (Piège 11) ✓ SEQUENCE + order_inserts=true + persist() + flush()/clear() par lots. ⚠ IDENTITY désactive silencieusement le batching — aucun log, aucun avertissement.

Appels externes en transaction (Piège 17) ✓ Outbox pattern ou after-commit pour les events — jamais d'appel HTTP/Kafka dans @Transactional. ⚠ Un appel externe lent dans une transaction = lock prolongé sur les tables modifiées.

Persistence Context gonfle (Piège 18) ✓ flush() + clear() tous les N éléments dans les traitements batch. ⚠ saveAll() sur 100 000 entités sans flush intermédiaire → OOM avant le premier commit.

🎓 À retenir

OSIV est activé par défaut — spring.jpa.open-in-view=true dans Spring Boot. Sur la majorité des applications de production, le désactiver immédiatement et construire les DTOs dans la couche service/transaction.
HHH90003004 est une alarme silencieuse — Hibernate affiche ce warning dans les logs quand il pagine en mémoire à cause de JOIN FETCH + setMaxResults. L'application continue de fonctionner mais charge potentiellement des milliers de lignes en RAM. Chercher ce pattern dans les logs de CI.
EXPLAIN ANALYZE avant d'optimiser le code JPA — avant de changer le mapping ou d'ajouter du cache, vérifier le plan d'exécution SQL. Un index manquant peut être la vraie cause d'une lenteur qu'on attribue à tort à Hibernate.

Sources

jpa-hibernate-gerer-le-n-1-quand-n-est-grand — JOIN FETCH, EntityGraph, @BatchSize, pattern deux temps (pièges 2, 3, 4, 5)
jpa-hibernate-relations-mapping-collections — cascade, orphanRemoval, List vs Set, equals/hashCode (pièges 6, 7, 8, 9)
jpa-hibernate-bulk-operations-pieges-du-persistence-context — @Modifying, flush/clear, @Version (pièges 12, 13, 14)
jpa-hibernate-jdbc-batching — batch_size, SEQUENCE vs IDENTITY, persist() vs save() (pièges 10, 11)
jpa-hibernate-locks-concurrence — @Version, pessimistic lock, isolation (pièges 15, 16)
pattern-outbox-publication-fiable-de-messages-depuis-une-transaction-db — appels externes et transactions longues (piège 17)