☕ JPA – Mapping, Requêtes, Transactions & Performance

Les briques indispensables

Si tu “sens” du flou : pense “un EntityManager = une session de travail” avec un cache L1, qui pousse vers la base lors du flush/commit.

Cas d’usage typiques

• Applications métiers CRUD avec règles de gestion complexes.
• Domain model riche (relations, invariants, agrégats).
• Accès DB standardisé + possibilité d’optimiser par provider.

Ce que JPA ne “fait pas” tout seul

• Choisir les bons index, partitions, paramètres DB.
• Éviter les N+1 si tu ne maîtrises pas fetch/joins.
• Garantir la perf : tu dois profiler et lire des plans.

Flush vs Commit

Flush = synchroniser l’état mémoire vers la base (SQL envoyé), sans forcément valider la transaction. Commit = valider la transaction DB.

Dirty checking

En état managed, le provider compare l’état initial à l’état final et génère l’UPDATE si nécessaire.

// English-only example
em.getTransaction().begin();

Customer c = em.find(Customer.class, 10L); // managed
c.setStatus("ACTIVE"); // dirty

em.flush();  // sends UPDATE (still in TX)
em.getTransaction().commit();

À grande échelle : flush/clear périodiques + batching, sinon explosion mémoire.

Pièges fréquents

• LazyInitializationException : accès à une relation lazy hors contexte.
• N+1 : itération sur une collection lazy qui déclenche 1 requête par ligne.
• merge() : peut dupliquer du travail (SELECT + UPDATE) si mal utilisé.
• equals/hashCode : dangereux si basé sur ID non assigné ou mutable.

Règle de base

Décide explicitement où se termine la transaction, et quelles relations doivent être chargées avant de sortir de ce scope.

Voir le SQL “utile”

• Activer logs SQL (et paramètres bind), mais attention au bruit.
• Mettre un slow query log côté DB, et corréler avec trace applicative.
• Sur incidents : extraire les requêtes réelles et faire EXPLAIN (ANALYZE).

# English-only sample (Spring Boot)
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.orm.jdbc.bind=TRACE

DDL : stratégie saine

Reco : Flyway ou Liquibase pour versionner le schéma, et JPA pour valider/mapper.

Contraintes : où les mettre ?

Les annotations JPA sont utiles, mais la DB reste la source d’autorité. Pour la validation métier : Bean Validation (jakarta.validation) + contraintes DB.

// English-only sample
@Column(unique = true, nullable = false)
private String email;

@Enumerated(EnumType.STRING)
@Column(nullable = false, length = 20)
private CustomerTier tier;

Important : “unique=true” côté JPA n’est pas une stratégie d’indexing en soi : en prod, passe par migrations.

Dates / Instants

• Préférer Instant / OffsetDateTime / LocalDate selon besoin.
• Fixer la timezone (DB + JVM + app) pour éviter “heisenbugs”.

Enums

Toujours EnumType.STRING (stable) sauf cas particulier.

UUID : quand et pourquoi

• Utile en systèmes distribués (génération côté app).
• Attention : index plus gros, locality faible, impact perf sur inserts.
• Mitigation : UUID “ordered” / ULID / UUIDv7 (selon stack).

// English-only sample
@Id
@Column(columnDefinition = "uuid")
private java.util.UUID id;

Composite keys (prudence)

Souvent mieux : une clé technique + contrainte unique métier. Mais si tu dois : @EmbeddedId.

// English-only sample
@Embeddable
public class OrderLineId implements java.io.Serializable {
  private Long orderId;
  private Integer lineNo;
}

@Entity
public class OrderLine {
  @EmbeddedId
  private OrderLineId id;
}

@Converter : types métier ↔ types DB

// English-only sample
@Converter(autoApply = false)
public class MoneyConverter implements AttributeConverter {
  public Long convertToDatabaseColumn(Money attribute) { return attribute == null ? null : attribute.cents(); }
  public Money convertToEntityAttribute(Long dbData) { return dbData == null ? null : Money.ofCents(dbData); }
}

Très pratique pour encapsuler un modèle (Money, Email, JsonMap, etc.).

Inheritance strategies

OneToMany : préfère “ManyToOne + collection inverse”

Le mapping “@OneToMany” côté parent seul peut créer une table de jointure implicite selon provider. Le pattern stable : FK côté enfant (ManyToOne) + collection inverse.

Helper methods (cohérence)

// English-only sample
public void addLine(OrderLine line) {
  lines.add(line);
  line.setOrder(this);
}

public void removeLine(OrderLine line) {
  lines.remove(line);
  line.setOrder(null);
}

ManyToMany : prudence

• Bien en lecture simple, mais complexe dès que la jointure porte des attributs.
• Si la table de jointure a des colonnes métier : modèle-la comme entité (ex: Membership).

// English-only sample
@Entity
class Membership {
  @ManyToOne User user;
  @ManyToOne Group group;
  @Column String role;
}

Solution #1 : JOIN FETCH (ciblé)

// English-only sample
List orders =
  em.createQuery(
    "select distinct o from Order o " +
    "left join fetch o.lines " +
    "where o.status = :s", Order.class)
  .setParameter("s", "OPEN")
  .getResultList();

“distinct” évite les doublons d’objets racine quand la jointure multiplie les lignes.

Limites

• Pagination + join fetch collection = souvent problématique.
• Risque de charger trop de données (cartésien).

Solution #2 : EntityGraph (pilotage propre)

// English-only sample
EntityGraph graph = em.createEntityGraph(Order.class);
graph.addAttributeNodes("customer");
Subgraph sg = graph.addSubgraph("lines");
sg.addAttributeNodes("product");

Order o = em.find(Order.class, 10L, Map.of("jakarta.persistence.fetchgraph", graph));

Solution #3 : Batch fetching

L’idée : quand une collection lazy est demandée, le provider la charge pour plusieurs parents en une requête IN.

# English-only sample (Hibernate)
hibernate.default_batch_fetch_size=50

orphanRemoval = “remove when unlinked”

// English-only sample
@OneToMany(mappedBy = "order", orphanRemoval = true, cascade = CascadeType.ALL)
private List lines;

Si une ligne est retirée de la collection et n’est plus référencée, elle est supprimée au flush. Idéal pour “enfants owned” (agrégat).

Pièges

• Cascade REMOVE sur relation partagée = catastrophe (effets de bord).
• Supprimer un parent avec énorme collection = storm de DELETE (batch à prévoir).
• Les helpers add/remove sont indispensables pour garder le graphe cohérent.

Projection DTO

// English-only sample
public record CustomerSummary(Long id, String name, long orderCount) {}

List rows =
  em.createQuery(
      "select new com.example.CustomerSummary(c.id, c.name, count(o)) " +
      "from Customer c left join c.orders o " +
      "group by c.id, c.name",
      CustomerSummary.class)
    .getResultList();

DTO = moins de data, moins de lazy surprises, plus stable en API.

Pagination

// English-only sample
List page =
  em.createQuery("select o from Order o order by o.createdAt desc", Order.class)
    .setFirstResult(0)
    .setMaxResults(50)
    .getResultList();

Si pagination + join fetch collection : préférer deux requêtes (ids page -> fetch graph).

Exemple : projection simple

// English-only sample
List rows = em.createNativeQuery(
  "select c.id, c.name, count(o.id) as cnt " +
  "from customer c left join orders o on o.customer_id = c.id " +
  "group by c.id, c.name " +
  "order by cnt desc")
.getResultList();

En pratique : map vers DTO (ou SqlResultSetMapping) pour garder un code propre.

Risques

• Portabilité réduite (dialect).
• Maintenance : SQL long dans le code (à versionner/tester).
• Attention aux injections : toujours bind params, jamais concat.

Isolation & verrous

L’isolation est DB-level. JPA n’invente pas la cohérence : elle s’appuie sur la DB.

En pratique : lock ciblé + optimistic locking + retries.

Spring (@Transactional) : points d’attention

• Proxy-based : appels internes (self-invocation) ne passent pas toujours par le proxy.
• Propagation : REQUIRED, REQUIRES_NEW, SUPPORTS, etc.
• Read-only : utile pour hints perf (selon provider), mais pas magique.

// English-only sample
@Transactional
public void placeOrder(Long customerId) {
  // business work
}

Locks pessimistes : quand il faut bloquer

// English-only sample
Account a = em.find(Account.class, id, LockModeType.PESSIMISTIC_WRITE);

• Protège fortement, mais peut générer contention et deadlocks.
• À utiliser sur “hot rows” (solde, stock critique) avec TX courte.

Stratégie retry (recommandée)

• Optimistic : retries applicatifs sur collisions.
• Backoff exponentiel + jitter sur contention.
• Mesure : taux de collisions, latence, timeouts.

// English-only pseudo
for (int attempt=1; attempt<=3; attempt++) {
  try { doWork(); break; }
  catch (OptimisticLockException e) { sleep(backoff(attempt)); }
}

Cache L2 (second-level)

Partagé entre EntityManagers (selon provider). Très efficace en lecture “reference data”, mais exige une stratégie d’invalidation.

# English-only sample (Hibernate-ish)
hibernate.cache.use_second_level_cache=true
hibernate.cache.region.factory_class=org.hibernate.cache.jcache.JCacheRegionFactory

Query cache : utile mais facile à rendre incohérent. À activer seulement si maîtrisé.

Invalidation : le sujet qui décide

• Données peu volatiles : L2 excellent.
• Données très mutables : L2 peut coûter plus qu’il ne rapporte.
• En cluster : attention à cohérence (replication/invalidation events).

Tracer ce qui compte

• Nombre de requêtes par endpoint (détecter N+1).
• Temps DB vs temps applicatif.
• Top queries (slow log) + explain plans.

# English-only idea
request_id -> app logs -> SQL logs -> db slow logs -> explain analyze

Workflow perf (pro)

1. Reproduire (dataset réaliste).
2. Capturer SQL réel + binds.
3. EXPLAIN ANALYZE + index review.
4. Fix fetch strategy / queries / indexes.
5. Re-bench + regression tests.

Derived queries

// English-only sample
List findByStatusAndTierOrderByNameAsc(String status, CustomerTier tier);

Super pour CRUD, mais attention : sur du complexe, préfère @Query ou specs.

Specifications + paging

// English-only sample
Page findAll(Specification spec, Pageable pageable);

Très bon pour écrans de recherche avancée, surtout avec filtres optionnels.