Spring Boot Resilience4j パターン

概要

Spring Boot 3.x の障害耐性を実現する Resilience4j パターン (サーキットブレーカー、リトライ、レート制限、バルクヘッド、タイムリミッター、フォールバック) を提供し、設定とテストワークフローを含みます。

使用する場面

• 障害耐性の実装とカスケード障害の防止
• サービス呼び出しへのサーキットブレーカー、リトライロジック、またはレート制限の追加
• 指数バックオフによる一時的な障害への対処
• サービスをオーバーロードとリソース枯渇から保護
• 包括的な復元性のための複数パターンの組み合わせ

手順

1. セットアップと依存関係

Resilience4j の依存関係をプロジェクトに追加します。Maven の場合、pom.xml に追加します:

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-spring-boot3</artifactId>
    <version>2.2.0</version> // Use latest stable version
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Gradle の場合、build.gradle に追加します:

implementation "io.github.resilience4j:resilience4j-spring-boot3:2.2.0"
implementation "org.springframework.boot:spring-boot-starter-aop"
implementation "org.springframework.boot:spring-boot-starter-actuator"

@EnableAspectJAutoProxy で AOP アノテーション処理を有効にします (Spring Boot により自動設定されます)。

2. サーキットブレーカーパターン

外部サービスを呼び出すメソッドに @CircuitBreaker アノテーションを適用します:

@Service
public class PaymentService {
    private final RestTemplate restTemplate;

    public PaymentService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    @CircuitBreaker(name = "paymentService", fallbackMethod = "paymentFallback")
    public PaymentResponse processPayment(PaymentRequest request) {
        return restTemplate.postForObject("http://payment-api/process",
            request, PaymentResponse.class);
    }

    private PaymentResponse paymentFallback(PaymentRequest request, Exception ex) {
        return PaymentResponse.builder()
            .status("PENDING")
            .message("Service temporarily unavailable")
            .build();
    }
}

application.yml で設定します:

resilience4j:
  circuitbreaker:
    configs:
      default:
        registerHealthIndicator: true
        slidingWindowSize: 10
        minimumNumberOfCalls: 5
        failureRateThreshold: 50
        waitDurationInOpenState: 10s
    instances:
      paymentService:
        baseConfig: default

完全なサーキットブレーカー設定オプションについては @references/configuration-reference.md を参照してください。

3. リトライパターン

一時的な障害復旧のために @Retry アノテーションを適用します:

@Service
public class ProductService {
    private final RestTemplate restTemplate;

    public ProductService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    @Retry(name = "productService", fallbackMethod = "getProductFallback")
    public Product getProduct(Long productId) {
        return restTemplate.getForObject(
            "http://product-api/products/" + productId,
            Product.class);
    }

    private Product getProductFallback(Long productId, Exception ex) {
        return Product.builder()
            .id(productId)
            .name("Unavailable")
            .available(false)
            .build();
    }
}

application.yml でリトライを設定します:

resilience4j:
  retry:
    configs:
      default:
        maxAttempts: 3
        waitDuration: 500ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
    instances:
      productService:
        baseConfig: default
        maxAttempts: 5

リトライの例外設定については @references/configuration-reference.md を参照してください。

4. レート制限パターン

リクエストレートを制御するために @RateLimiter を適用します:

@Service
public class NotificationService {
    private final EmailClient emailClient;

    public NotificationService(EmailClient emailClient) {
        this.emailClient = emailClient;
    }

    @RateLimiter(name = "notificationService",
        fallbackMethod = "rateLimitFallback")
    public void sendEmail(EmailRequest request) {
        emailClient.send(request);
    }

    private void rateLimitFallback(EmailRequest request, Exception ex) {
        throw new RateLimitExceededException(
            "Too many requests. Please try again later.");
    }
}

application.yml で設定します:

resilience4j:
  ratelimiter:
    configs:
      default:
        registerHealthIndicator: true
        limitForPeriod: 10
        limitRefreshPeriod: 1s
        timeoutDuration: 500ms
    instances:
      notificationService:
        baseConfig: default
        limitForPeriod: 5

5. バルクヘッドパターン

リソースを分離するために @Bulkhead を適用します。同期メソッドの場合は type = SEMAPHORE を使用します:

@Service
public class ReportService {
    private final ReportGenerator reportGenerator;

    public ReportService(ReportGenerator reportGenerator) {
        this.reportGenerator = reportGenerator;
    }

    @Bulkhead(name = "reportService", type = Bulkhead.Type.SEMAPHORE)
    public Report generateReport(ReportRequest request) {
        return reportGenerator.generate(request);
    }
}

非同期/CompletableFuture メソッドの場合は type = THREADPOOL を使用します:

@Service
public class AnalyticsService {
    @Bulkhead(name = "analyticsService", type = Bulkhead.Type.THREADPOOL)
    public CompletableFuture<AnalyticsResult> runAnalytics(
            AnalyticsRequest request) {
        return CompletableFuture.supplyAsync(() ->
            analyticsEngine.analyze(request));
    }
}

application.yml で設定します:

resilience4j:
  bulkhead:
    configs:
      default:
        maxConcurrentCalls: 10
        maxWaitDuration: 100ms
    instances:
      reportService:
        baseConfig: default
        maxConcurrentCalls: 5

  thread-pool-bulkhead:
    instances:
      analyticsService:
        maxThreadPoolSize: 8

6. タイムリミッターパターン

非同期メソッドにタイムアウト境界を強制するために @TimeLimiter を適用します:

@Service
public class SearchService {
    @TimeLimiter(name = "searchService", fallbackMethod = "searchFallback")
    public CompletableFuture<SearchResults> search(SearchQuery query) {
        return CompletableFuture.supplyAsync(() ->
            searchEngine.executeSearch(query));
    }

    private CompletableFuture<SearchResults> searchFallback(
            SearchQuery query, Exception ex) {
        return CompletableFuture.completedFuture(
            SearchResults.empty("Search timed out"));
    }
}

application.yml で設定します:

resilience4j:
  timelimiter:
    configs:
      default:
        timeoutDuration: 2s
        cancelRunningFuture: true
    instances:
      searchService:
        baseConfig: default
        timeoutDuration: 3s

7. 複数パターンの組み合わせ

単一のメソッドに複数のパターンをスタックして、包括的な障害耐性を実現します:

@Service
public class OrderService {
    @CircuitBreaker(name = "orderService")
    @Retry(name = "orderService")
    @RateLimiter(name = "orderService")
    @Bulkhead(name = "orderService")
    public Order createOrder(OrderRequest request) {
        return orderClient.createOrder(request);
    }
}

実行順序: リトライ → サーキットブレーカー → レート制限 → バルクヘッド → メソッド

すべてのパターンは、一貫性のために同じ名前の設定インスタンスを参照する必要があります。

8. 例外処理とモニタリング

@RestControllerAdvice を使用してグローバル例外ハンドラを作成します:

@RestControllerAdvice
public class ResilienceExceptionHandler {

    @ExceptionHandler(CallNotPermittedException.class)
    @ResponseStatus(HttpStatus.SERVICE_UNAVAILABLE)
    public ErrorResponse handleCircuitOpen(CallNotPermittedException ex) {
        return new ErrorResponse("SERVICE_UNAVAILABLE",
            "Service currently unavailable");
    }

    @ExceptionHandler(RequestNotPermitted.class)
    @ResponseStatus(HttpStatus.TOO_MANY_REQUESTS)
    public ErrorResponse handleRateLimited(RequestNotPermitted ex) {
        return new ErrorResponse("TOO_MANY_REQUESTS",
            "Rate limit exceeded");
    }

    @ExceptionHandler(BulkheadFullException.class)
    @ResponseStatus(HttpStatus.SERVICE_UNAVAILABLE)
    public ErrorResponse handleBulkheadFull(BulkheadFullException ex) {
        return new ErrorResponse("CAPACITY_EXCEEDED",
            "Service at capacity");
    }
}

application.yml で Actuator エンドポイントを有効にして復元性パターンをモニタリングします:

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,circuitbreakers,retries,ratelimiters
  endpoint:
    health:
      show-details: always
  health:
    circuitbreakers:
      enabled: true
    ratelimiters:
      enabled: true

モニタリングエンドポイントにアクセスします:

• GET /actuator/health - 復元性パターンを含む全体的なヘルスチェック
• GET /actuator/circuitbreakers - サーキットブレーカーの状態
• GET /actuator/metrics - カスタム復元性メトリクス

テストと検証ワークフロー

1. サーキットブレーカー: 障害を含むエンドポイントを呼び出す → GET /actuator/circuitbreakers が OPEN を表示することを確認 → waitDurationInOpenState を待つ → 状態が HALF_OPEN → CLOSED に遷移することを確認

2. リトライ: resilience4j.retry.metrics.enabled: true を有効化 → エンドポイントを呼び出す → retry.{instance}.successful-calls-with-retry-attempts メトリクスが増加することを確認

3. レート制限: limitForPeriod を超えるリクエストを送信 → 429 ステータスを確認 → GET /actuator/ratelimiters が LIMITED を表示することを確認

4. バルクヘッド: maxConcurrentCalls を超える並行リクエストで負荷テスト → 超過リクエストが BulkheadFullException で即座に失敗することを確認

5. タイムリミッター: timeoutDuration を超える非同期遅延をモック → タイムアウト後にフォールバックがトリガーされることを確認

ユニットテストと統合テストの戦略については @references/testing-patterns.md を参照してください。

ベストプラクティス

• フォールバックメソッドを提供する: 意味のある応答による適切な機能低下を確保する
• 指数バックオフを使用する: 回復中のサービスに過負荷をかけるのを防ぐ (exponentialBackoffMultiplier: 2)
• 適切なしきい値を設定する: failureRateThreshold を 50-70% に設定
• コンストラクタインジェクションを使用する: Resilience4j の依存関係にフィールドインジェクションを使用しない
• ヘルスインジケータを有効にする: すべてのパターンに対して registerHealthIndicator: true を設定
• 一時的なエラーのみをリトライする: ネットワークタイムアウト、5xx; 4xx とビジネス例外はスキップ
• 負荷に基づいてバルクヘッドをサイズ設定する: 予想される並行性からスレッドプールとセマフォのサイズを計算
• フォールバック動作を文書化する: フォールバックロジックを明確で予測可能にする

制約と警告

• フォールバックメソッドは、同じシグネチャにオプションの例外パラメータを追加したものである必要があります
• サーキットブレーカーの状態はインスタンスごと; マルチテナントシナリオで適切なビーンスコープを確保してください
• リトライ操作は冪等である必要があります (複数回実行される可能性があります)
• 必ず完了する必要のある操作にはサーキットブレーカーを使用しないでください; 代わりにタイムアウトを使用してください
• レート制限スレッドをブロックする可能性があります; 適切なウェイト期間を設定してください
• POST リクエストなどの非冪等操作で @Retry を使用する場合は注意してください
• 高い並行性でスレッドプールバルクヘッドを使用する場合、メモリ使用量をモニタリングしてください

例

Before → After: サーキットブレーカー

// BEFORE: 保護なし
public PaymentResponse processPayment(PaymentRequest request) {
    return restTemplate.postForObject("http://payment-api/process", request, PaymentResponse.class);
}

// AFTER: フォールバック付きサーキットブレーカー
@CircuitBreaker(name = "paymentService", fallbackMethod = "paymentFallback")
public PaymentResponse processPayment(PaymentRequest request) {
    return restTemplate.postForObject("http://payment-api/process", request, PaymentResponse.class);
}
private PaymentResponse paymentFallback(PaymentRequest request, Exception ex) {
    return PaymentResponse.builder().status("PENDING").message("Service temporarily unavailable").build();
}

Before → After: バックオフ付きリトライ

// BEFORE: 単一の試行
public Order getOrder(Long orderId) {
    return orderRepository.findById(orderId).orElseThrow(() -> new OrderNotFoundException(orderId));
}

// AFTER: 指数バックオフ付きリトライ
@Retry(name = "orderService", maxAttempts = 3, waitDuration = @WaitDuration(500L), fallbackMethod = "getOrderFallback")
public Order getOrder(Long orderId) {
    return orderRepository.findById(orderId).orElseThrow(() -> new OrderNotFoundException(orderId));
}
private Order getOrderFallback(Long orderId, Exception ex) { return Order.cachedOrder(orderId); }

Before → After: レート制限

// BEFORE: 無制限のリクエスト
@GetMapping("/api/data") public Data fetchData() { return dataService.process(); }

// AFTER: レート制限付き
@RateLimiter(name = "dataService", fallbackMethod = "rateLimitFallback")
@GetMapping("/api/data") public Data fetchData() { return dataService.process(); }
private ResponseEntity<ErrorResponse> rateLimitFallback(Exception ex) {
    return ResponseEntity.status(429).body(new ErrorResponse("TOO_MANY_REQUESTS", "Rate limit exceeded"));
}

関連リンク: Configuration Reference · Testing Patterns · Examples · Resilience4j Docs · Actuator Skill