Resilience4j — Circuit Breaker, Retry, Bulkhead : les patterns de résilience en Java

1📖 Glossaire — le vocabulaire de base

• Panne en cascade (cascading failure) — une dépendance défaillante épuise les ressources (threads, connexions) de ses appelants, qui deviennent défaillants à leur tour.
• Fenêtre glissante (sliding window) — l'échantillon d'appels récents sur lequel le circuit breaker calcule son taux d'échec ; par nombre d'appels (count-based) ou par durée (time-based).
• Slow call — appel qui aboutit mais dépasse un seuil de durée ; Resilience4j le compte séparément des échecs, car la lenteur est souvent le vrai signal de dégradation.
• Fallback — comportement de repli exécuté quand l'appel protégé échoue : valeur en cache, réponse dégradée, valeur par défaut.
• Backoff exponentiel — augmenter le délai entre chaque nouvelle tentative (1s, 2s, 4s, 8s…) pour laisser la dépendance respirer.
• Jitter — part d'aléatoire ajoutée au backoff pour éviter que tous les clients réessaient au même instant (effet « troupeau », thundering herd).
• Idempotence — propriété d'une opération qu'on peut rejouer sans changer le résultat ; condition indispensable pour un retry sûr.

2Pourquoi Resilience4j — le successeur de Hystrix

Hystrix (Netflix) a popularisé le circuit breaker en Java, mais est en mode maintenance depuis 2018 — Netflix lui-même recommande Resilience4j. Les différences ne sont pas cosmétiques :

Le cœur du design : chaque résilience-pattern est un décorateur d'ordre supérieur. Sans Spring, ça s'écrit littéralement comme une composition de fonctions :

Supplier<PaymentResult> decorated = Decorators
    .ofSupplier(() -> paymentClient.charge(order))
    .withCircuitBreaker(circuitBreaker)   // ✓ opens on repeated failures
    .withRetry(retry)                     // ✓ retries transient errors
    .withBulkhead(bulkhead)               // ✓ caps concurrent calls
    .withFallback(List.of(CallNotPermittedException.class),
                  ex -> PaymentResult.deferred())  // ✓ graceful degradation
    .decorate();

PaymentResult result = decorated.get(); // actual call happens here

3Circuit Breaker — le disjoncteur

Le circuit breaker est une machine à états qui observe les résultats des appels et coupe le circuit quand la dépendance va mal — exactement comme un disjoncteur électrique protège une installation.

stateDiagram-v2
    [*] --> CLOSED
    CLOSED --> OPEN : taux d'échec ou de slow calls ≥ seuil
    OPEN --> HALF_OPEN : après waitDurationInOpenState
    HALF_OPEN --> CLOSED : les N appels d'essai réussissent
    HALF_OPEN --> OPEN : taux d'échec des essais ≥ seuil
    note right of OPEN
        Rejet immédiat :
        CallNotPermittedException
        (aucun appel réseau)
    end note
    note right of HALF_OPEN
        permittedNumberOfCallsInHalfOpenState
        appels de test autorisés
    end note

• CLOSED — état nominal : les appels passent, le breaker enregistre succès/échecs dans sa fenêtre glissante.
• OPEN — circuit coupé : chaque appel est rejeté immédiatement avec CallNotPermittedException, sans toucher au réseau. C'est le « fail fast » : on ne gaspille ni thread ni latence sur une dépendance qu'on sait malade.
• HALF_OPEN — période d'essai : un petit nombre d'appels réels est autorisé pour sonder la guérison. Succès → retour à CLOSED ; échec → retour à OPEN.

La configuration qui compte

resilience4j:
  circuitbreaker:
    instances:
      paymentService:
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 20               # last 20 calls form the sample
        minimumNumberOfCalls: 10            # ⚠️ no decision before 10 calls
        failureRateThreshold: 50            # open if ≥ 50% failures
        slowCallDurationThreshold: 2s       # a call slower than 2s is "slow"
        slowCallRateThreshold: 80           # open if ≥ 80% slow calls
        waitDurationInOpenState: 30s
        permittedNumberOfCallsInHalfOpenState: 5
        recordExceptions:
          - java.io.IOException
          - java.util.concurrent.TimeoutException
        ignoreExceptions:
          - com.acme.payment.BusinessValidationException  # ✓ not an outage signal

Trois subtilités qui font la différence en prod :

1. minimumNumberOfCalls — en dessous de ce volume, le breaker ne calcule rien. Valeur par défaut : 100. Sur un endpoint peu sollicité, un breaker avec les défauts peut ne jamais s'ouvrir.
2. slowCallRateThreshold — le breaker peut s'ouvrir sur la lenteur seule, sans aucune exception. C'est souvent lui qui sauve le système : une dépendance qui répond en 28s « fonctionne » du point de vue des erreurs, mais elle est en train de vider votre pool de threads.
3. ignoreExceptions — une erreur métier (validation refusée, solde insuffisant) n'est pas un signal de panne. La compter ferait s'ouvrir le circuit sur un comportement parfaitement normal.

4Retry — réessayer sans aggraver la panne

Une grande partie des erreurs en distribué sont transitoires : micro-coupure réseau, redéploiement d'un pod, deadlock ponctuel. Un simple réessai les absorbe. Mais un retry naïf est dangereux : réessayer immédiatement et en boucle, c'est multiplier la charge sur une dépendance déjà à genoux — le remède devient le poison (retry storm).

resilience4j:
  retry:
    instances:
      paymentService:
        maxAttempts: 3                      # 1 initial call + 2 retries
        waitDuration: 500ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2     # 500ms → 1s → 2s
        enableRandomizedWait: true          # jitter: avoids thundering herd
        randomizedWaitFactor: 0.5
        retryExceptions:
          - java.io.IOException
          - org.springframework.web.client.HttpServerErrorException  # 5xx
        ignoreExceptions:
          - org.springframework.web.client.HttpClientErrorException  # ⚠️ never retry 4xx

Les trois règles d'un retry sain :

1. Backoff exponentiel — chaque tentative attend plus longtemps que la précédente, pour laisser la dépendance récupérer.
2. Jitter — sans aléatoire, tous les clients tombés en même temps réessaient au même instant : la dépendance reçoit des vagues synchronisées qui la re-tuent à chaque cycle.
3. Trier les exceptions — réessayer un 500 ou un timeout : oui. Réessayer un 400/404/422 : non, la réponse sera identique — on ne fait que doubler la charge et la latence.

5Bulkhead — cloisonner pour survivre

Le nom vient des cloisons étanches des navires : une voie d'eau inonde un compartiment, pas le bateau entier. Appliqué au backend : limiter le nombre d'appels concurrents vers chaque dépendance, pour qu'une dépendance lente ne puisse pas monopoliser toutes les ressources du service.

Sans bulkhead : le service d'export PDF (lent, non critique) reçoit un pic de trafic, ses appels s'accumulent et occupent les 200 threads du pool Tomcat → plus aucun thread pour le checkout (critique). Avec un bulkhead à 20 sur l'export : au pire, 20 threads y sont bloqués, les 180 autres continuent de servir le checkout.

Deux implémentations :

Quand le choisir : semaphore dans 95 % des cas — léger et suffisant. Thread pool uniquement si vous voulez une isolation stricte à la Hystrix pour une dépendance particulièrement instable, ou que l'appelant a besoin d'asynchronisme de toute façon.

resilience4j:
  bulkhead:
    instances:
      pdfExport:
        maxConcurrentCalls: 20
        maxWaitDuration: 100ms   # callers wait max 100ms for a permit, then BulkheadFullException

6RateLimiter et TimeLimiter — les deux gardiens du temps

RateLimiter limite le débit (appels/période), là où le bulkhead limite la concurrence (appels simultanés). Usage typique : respecter le quota d'une API externe payante, ou protéger une dépendance fragile d'un pic de trafic.

resilience4j:
  ratelimiter:
    instances:
      geocodingApi:
        limitForPeriod: 50          # 50 calls...
        limitRefreshPeriod: 1s      # ...per second
        timeoutDuration: 0          # don't wait for a permit: fail immediately

TimeLimiter borne la durée d'un appel asynchrone : au-delà du seuil, il lève TimeoutException et peut annuler le futur sous-jacent.

resilience4j:
  timelimiter:
    instances:
      paymentService:
        timeoutDuration: 3s
        cancelRunningFuture: true

7Composer les patterns — l'ordre des décorateurs

C'est le point qui surprend tout le monde avec l'intégration Spring. Quand plusieurs annotations sont posées sur la même méthode, Resilience4j applique un ordre fixe (du plus externe au plus interne) :

flowchart LR
    A[Appelant] --> R[Retry]
    R --> CB[CircuitBreaker]
    CB --> RL[RateLimiter]
    RL --> TL[TimeLimiter]
    TL --> B[Bulkhead]
    B --> F["Méthode métier<br/>(appel réseau)"]

Retry ( CircuitBreaker ( RateLimiter ( TimeLimiter ( Bulkhead ( méthode ) ) ) ) )

Conséquences concrètes de cet ordre :

• Chaque tentative du Retry traverse le CircuitBreaker → chaque échec est compté individuellement dans la fenêtre du breaker. Trois retries qui échouent = trois échecs enregistrés. C'est généralement souhaitable : le breaker voit la vraie santé de la dépendance.
• Si le breaker est OPEN, le Retry va réessayer… des CallNotPermittedException → configurez le retry pour ignorer cette exception, sinon vous attendez maxAttempts × backoff pour rien alors que le breaker avait justement coupé pour échouer vite.
• L'ordre est personnalisable via les propriétés resilience4j.<module>.<module>Aspect-order, mais le défaut est presque toujours le bon.

8Intégration Spring Boot — annotations et fallback

Avec resilience4j-spring-boot3, tout se pilote par annotations + configuration YAML :

@Service
public class PaymentService {

    private final PaymentClient paymentClient;

    @CircuitBreaker(name = "paymentService", fallbackMethod = "chargeFallback")
    @Retry(name = "paymentService")
    @Bulkhead(name = "paymentService")
    public PaymentResult charge(Order order) {
        return paymentClient.charge(order);   // remote call
    }

    // ⚠️ same return type + same params + exception as last arg
    private PaymentResult chargeFallback(Order order, CallNotPermittedException ex) {
        log.warn("Circuit open for paymentService, deferring order {}", order.id(), ex);
        return PaymentResult.deferred();       // ✓ degraded but honest response
    }

    // ✓ several fallbacks can coexist: most specific exception type wins
    private PaymentResult chargeFallback(Order order, Exception ex) {
        log.error("Payment failed for order {}", order.id(), ex);
        return PaymentResult.deferred();
    }
}

Les pièges classiques de cette intégration :

1. Signature du fallback — même type de retour, mêmes paramètres, plus l'exception en dernier argument. Une signature qui ne matche pas → NoSuchMethodException au moment de l'échec, pas au démarrage.
2. Proxy AOP — comme @Transactional, les annotations passent par un proxy Spring : un appel interne this.charge(order) contourne toute la protection. La méthode doit être appelée depuis un autre bean.
3. Fallback silencieux — un fallback qui retourne une valeur par défaut sans log ni métrique masque la panne : le service « marche », les données sont fausses, personne n'est alerté. Toujours logger + compter.

Observabilité

Resilience4j expose ses métriques via Micrometer : état des breakers (resilience4j_circuitbreaker_state), taux d'échec, appels rejetés par bulkhead… Avec Actuator, /actuator/circuitbreakers et /actuator/circuitbreakerevents montrent l'état et l'historique des transitions. Un circuit breaker sans alerte sur le passage à OPEN ne sert qu'à moitié : le fallback masque la panne aux utilisateurs, l'alerte la révèle à l'équipe.

9Tableau de synthèse — quel pattern pour quel problème

Sources

• Documentation officielle Resilience4j — référence complète des modules et de leur configuration
• Resilience4j — GitHub — code source, changelog et discussions de design
• Guide Spring Boot 3 — intégration annotations, propriétés YAML et ordre des aspects
• Hystrix — statut maintenance — l'annonce de Netflix recommandant Resilience4j
• Martin Fowler — CircuitBreaker — l'article fondateur du pattern
• AWS Builders' Library — Timeouts, retries, and backoff with jitter — le pourquoi du jitter, chiffres à l'appui