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. Concrètement, vous avez un appel réseau quelconque (ici paymentClient.charge(order)), et chaque pattern l'enveloppe d'une couche de protection supplémentaire — sans jamais toucher au code de l'appel lui-même :

// The remote call, unchanged. Each pattern wraps it like an onion layer.
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(); // nothing runs until this line

3Circuit Breaker — le disjoncteur

Pensez au disjoncteur électrique de votre maison : tant que tout va bien, le courant passe. En cas de court-circuit, il coupe — non pas pour vous embêter, mais pour éviter que le problème ne mette le feu à toute l'installation. Après réparation, vous le réarmez et le courant repasse.

Le circuit breaker logiciel fait exactement pareil avec les appels vers une dépendance. Déroulons un scénario concret avec cette configuration : fenêtre des 20 derniers appels, seuil d'échec 50 %, coupure de 30 s, 5 appels d'essai.

1. Tout va bien → état CLOSED (circuit fermé = le courant passe, comme en électricité). Chaque appel part réellement vers la dépendance, et le breaker note son résultat — succès ou échec — dans sa fenêtre des 20 derniers appels. Il ne bloque rien, il observe.
2. La dépendance commence à tomber. Sur les 20 derniers appels, 12 ont échoué → taux d'échec 60 %, au-dessus du seuil de 50 %. Le breaker bascule en OPEN (circuit ouvert = coupé).
3. Pendant 30 secondes, plus aucun appel ne part. Toute tentative reçoit instantanément une CallNotPermittedException — pas d'appel réseau, pas de thread bloqué, pas de timeout de 30 s à attendre. Votre service échoue en 0 ms et peut servir un fallback. Pendant ce temps, la dépendance respire au lieu de recevoir du trafic qu'elle ne peut pas traiter.
4. Après 30 secondes, le breaker teste la guérison → état HALF_OPEN (semi-ouvert). Il laisse passer exactement 5 appels réels, comme des éclaireurs.
5. Verdict : les 5 essais réussissent → la dépendance est remise, retour à CLOSED, le trafic normal reprend. Ils échouent → retour à OPEN pour 30 s de plus, et on recommencera l'essai plus tard.

Le diagramme reprend exactement ce scénario. Point de départ : la boîte 🚀 en haut — au démarrage, un breaker est toujours en CLOSED — puis suivez les flèches numérotées ① → ② → ③, qui correspondent aux étapes ci-dessus :

flowchart TD
    START(["🚀 DÉPART — démarrage du service<br/>Le breaker commence toujours ici, en CLOSED."]) --> CLOSED
    CLOSED["🟢 CLOSED — circuit fermé, état normal<br/>Les appels passent normalement.<br/>Le breaker compte succès et échecs<br/>sur les 20 derniers appels."]
    OPEN["🔴 OPEN — circuit coupé<br/>Plus aucun appel ne part vers la dépendance.<br/>Rejet immédiat en 0 ms :<br/>CallNotPermittedException"]
    HALFOPEN["🟡 HALF_OPEN — période d'essai<br/>5 appels réels sont laissés passer<br/>pour tester si la dépendance est guérie."]
    CLOSED -- "① la dépendance tombe :<br/>12 échecs sur les 20 derniers appels<br/>(60 % ≥ seuil de 50 %)" --> OPEN
    OPEN -- "② après 30 s d'attente<br/>(waitDurationInOpenState)" --> HALFOPEN
    HALFOPEN -- "③✓ les 5 essais réussissent<br/>→ retour à la normale" --> CLOSED
    HALFOPEN -- "③✗ les essais échouent encore<br/>→ on recoupe pour 30 s" --> OPEN

En temps normal, le breaker passe sa vie dans la boîte verte CLOSED et n'en bouge jamais. Tout le reste du diagramme ne se déclenche que le jour où la dépendance tombe : coupure (①), attente (②), test de guérison (③) — et la boucle ③✗ → ② → ③ se répète tant que la dépendance n'est pas remise.

Le même scénario en code

// 1. Build the breaker with the scenario's configuration
CircuitBreakerConfig config = CircuitBreakerConfig.custom()
    .slidingWindowSize(20)                              // sample = last 20 calls
    .minimumNumberOfCalls(10)                           // no decision before 10 calls
    .failureRateThreshold(50)                           // open at ≥ 50% failures
    .slowCallDurationThreshold(Duration.ofSeconds(2))   // a call > 2s counts as "slow"
    .slowCallRateThreshold(80)                          // open at ≥ 80% slow calls
    .waitDurationInOpenState(Duration.ofSeconds(30))
    .permittedNumberOfCallsInHalfOpenState(5)
    .ignoreExceptions(BusinessValidationException.class) // business errors ≠ outage
    .build();

CircuitBreaker breaker = CircuitBreaker.of("paymentService", config);

// 2. Watch state transitions — this is your alerting hook
breaker.getEventPublisher().onStateTransition(event ->
    log.warn("Breaker '{}' transition: {}",
             event.getCircuitBreakerName(), event.getStateTransition()));
// e.g. logs: "Breaker 'paymentService' transition: CLOSED_TO_OPEN"

// 3. Wrap the remote call
Supplier<PaymentResult> protectedCall =
    CircuitBreaker.decorateSupplier(breaker, () -> paymentClient.charge(order));

// 4. Call it — and handle the "circuit is open" case explicitly
try {
    return protectedCall.get();            // real network call (CLOSED or HALF_OPEN)
} catch (CallNotPermittedException e) {
    // breaker is OPEN: NO network call happened, we failed in ~0 ms
    return PaymentResult.deferred();       // ✓ fallback: degraded but instant answer
}

La même configuration en YAML pour l'intégration Spring Boot (section 8️⃣) :

resilience4j:
  circuitbreaker:
    instances:
      paymentService:
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 20
        minimumNumberOfCalls: 10
        failureRateThreshold: 50
        slowCallDurationThreshold: 2s
        slowCallRateThreshold: 80
        waitDurationInOpenState: 30s
        permittedNumberOfCallsInHalfOpenState: 5
        ignoreExceptions:
          - com.acme.payment.BusinessValidationException

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 28 s « 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).

RetryConfig config = RetryConfig.custom()
    .maxAttempts(3)   // 1 initial call + 2 retries
    // exponential backoff WITH jitter: ~500ms, ~1s, ~2s (each ± random factor)
    .intervalFunction(IntervalFunction.ofExponentialRandomBackoff(
        Duration.ofMillis(500),   // initial wait
        2.0,                      // multiplier
        0.5))                     // jitter factor: ±50% randomness
    .retryOnException(ex -> ex instanceof IOException
                         || ex instanceof HttpServerErrorException)  // ✓ retry 5xx
    .ignoreExceptions(HttpClientErrorException.class)                // ⚠️ never retry 4xx
    .build();

Retry retry = Retry.of("paymentService", config);

// Each attempt is observable — plug your metrics here
retry.getEventPublisher().onRetry(event ->
    log.info("Attempt #{} failed with {}, retrying...",
             event.getNumberOfRetryAttempts(), event.getLastThrowable().toString()));

Supplier<PaymentResult> withRetry =
    Retry.decorateSupplier(retry, () -> paymentClient.charge(order));

// Runs up to 3 attempts. If all fail, the LAST exception is rethrown.
PaymentResult result = withRetry.get();

Équivalent YAML pour Spring Boot :

resilience4j:
  retry:
    instances:
      paymentService:
        maxAttempts: 3
        waitDuration: 500ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
        enableRandomizedWait: true
        randomizedWaitFactor: 0.5
        retryExceptions:
          - java.io.IOException
          - org.springframework.web.client.HttpServerErrorException
        ignoreExceptions:
          - org.springframework.web.client.HttpClientErrorException

Les trois règles d'un retry sain :

1. Backoff exponentiel — chaque tentative attend plus longtemps que la précédente (500 ms → 1 s → 2 s), pour laisser la dépendance récupérer au lieu de la marteler.
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. Le jitter désynchronise les vagues.
3. Trier les exceptions — réessayer un 500 ou un timeout : oui, c'est peut-être transitoire. Réessayer un 400/404/422 : non, la requête est invalide et 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.

BulkheadConfig config = BulkheadConfig.custom()
    .maxConcurrentCalls(20)                    // at most 20 calls in flight
    .maxWaitDuration(Duration.ofMillis(100))   // wait max 100ms for a free slot
    .build();

Bulkhead bulkhead = Bulkhead.of("pdfExport", config);

Supplier<byte[]> protectedExport =
    Bulkhead.decorateSupplier(bulkhead, () -> pdfClient.render(report));

try {
    return protectedExport.get();   // acquires a slot, runs, releases the slot
} catch (BulkheadFullException e) {
    // 20 calls already in flight and no slot freed within 100ms:
    // the 21st caller is rejected — the rest of the service keeps its threads
    throw new ServiceBusyException("PDF export saturated, retry later");
}

resilience4j:
  bulkhead:
    instances:
      pdfExport:
        maxConcurrentCalls: 20
        maxWaitDuration: 100ms

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.

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). La nuance : 50 appels/seconde qui durent chacun 10 ms ne font que ~0,5 appel concurrent en moyenne — débit élevé, concurrence faible. Usage typique du rate limiter : respecter le quota d'une API externe payante, ou protéger une dépendance fragile d'un pic de trafic.

RateLimiterConfig config = RateLimiterConfig.custom()
    .limitForPeriod(50)                          // 50 calls...
    .limitRefreshPeriod(Duration.ofSeconds(1))   // ...per second
    .timeoutDuration(Duration.ZERO)              // no queueing: reject immediately
    .build();

RateLimiter limiter = RateLimiter.of("geocodingApi", config);

Supplier<Coordinates> limited =
    RateLimiter.decorateSupplier(limiter, () -> geoClient.geocode(address));

try {
    return limited.get();
} catch (RequestNotPermitted e) {
    // quota of 50 calls this second is exhausted
    return cachedCoordinates(address);   // ✓ fallback: last known position
}

TimeLimiter borne la durée d'un appel asynchrone : au-delà du seuil, il complète le futur avec une TimeoutException et peut annuler la tâche sous-jacente.

TimeLimiter timeLimiter = TimeLimiter.of("paymentService",
    TimeLimiterConfig.custom()
        .timeoutDuration(Duration.ofSeconds(3))
        .cancelRunningFuture(true)     // also cancel the underlying task
        .build());

ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();

// ⚠️ the protected call MUST return a CompletableFuture / CompletionStage
CompletableFuture<PaymentResult> future = timeLimiter.executeCompletionStage(
        scheduler,
        () -> CompletableFuture.supplyAsync(() -> paymentClient.charge(order)))
    .toCompletableFuture();

// If the dependency hangs, after 3s the future completes
// exceptionally with TimeoutException — the caller is never stuck forever.

Équivalents YAML :

resilience4j:
  ratelimiter:
    instances:
      geocodingApi:
        limitForPeriod: 50
        limitRefreshPeriod: 1s
        timeoutDuration: 0
  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, plus besoin de construire les objets à la main comme dans les sections précédentes : tout se pilote par annotations, et la configuration vient du YAML (les blocs instances.paymentService vus plus haut) :

@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