Back to Details

spring-boot-resilience4j

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spring Boot Resilience4j Patterns

Spring Boot Resilience4j 弹性模式

When to Use

适用场景

To implement resilience patterns in Spring Boot applications, use this skill when:
  • Preventing cascading failures from external service unavailability with circuit breaker pattern
  • Retrying transient failures with exponential backoff
  • Rate limiting to protect services from overload or downstream service capacity constraints
  • Isolating resources with bulkhead pattern to prevent thread pool exhaustion
  • Adding timeout controls to async operations with time limiter
  • Combining multiple patterns for comprehensive fault tolerance
Resilience4j is a lightweight, composable library for adding fault tolerance without requiring external infrastructure. It provides annotation-based patterns that integrate seamlessly with Spring Boot's AOP and Actuator.
在Spring Boot应用中实现弹性模式时，可在以下场景使用本Skill：
  • 通过断路器模式防止因外部服务不可用导致的级联故障
  • 使用指数退避策略重试瞬时故障
  • 限流以保护服务避免过载，或适配下游服务的容量限制
  • 通过舱壁模式隔离资源，防止线程池耗尽
  • 为异步操作添加超时限制器来控制超时
  • 组合多种模式实现全面的容错能力
Resilience4j是一款轻量级、可组合的容错库，无需依赖外部基础设施。它提供了基于注解的模式，可与Spring Boot的AOP和Actuator无缝集成。

Instructions

操作步骤

1. Setup and Dependencies

1. 环境搭建与依赖配置

Add Resilience4j dependencies to your project. For Maven, add to 
pom.xml
:
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>
For Gradle, add to 
build.gradle
:
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"
Enable AOP annotation processing with 
@EnableAspectJAutoProxy
(auto-configured by Spring Boot).
向项目中添加Resilience4j依赖。对于Maven项目，在
pom.xml
中添加以下内容：
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
中添加以下内容：
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"
启用AOP注解处理（Spring Boot会自动配置
@EnableAspectJAutoProxy
）。

2. Circuit Breaker Pattern

2. 断路器模式

Apply 
@CircuitBreaker
annotation to methods calling external services:
java
@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();
    }
}
Configure in 
application.yml
:
yaml
resilience4j:
  circuitbreaker:
    configs:
      default:
        registerHealthIndicator: true
        slidingWindowSize: 10
        minimumNumberOfCalls: 5
        failureRateThreshold: 50
        waitDurationInOpenState: 10s
    instances:
      paymentService:
        baseConfig: default
See @references/configuration-reference.md for complete circuit breaker configuration options.
在调用外部服务的方法上添加
@CircuitBreaker
注解：
java
@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
中配置：
yaml
resilience4j:
  circuitbreaker:
    configs:
      default:
        registerHealthIndicator: true
        slidingWindowSize: 10
        minimumNumberOfCalls: 5
        failureRateThreshold: 50
        waitDurationInOpenState: 10s
    instances:
      paymentService:
        baseConfig: default
完整的断路器配置选项请参考@references/configuration-reference.md。

3. Retry Pattern

3. 重试模式

Apply 
@Retry
annotation for transient failure recovery:
java
@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();
    }
}
Configure retry in 
application.yml
:
yaml
resilience4j:
  retry:
    configs:
      default:
        maxAttempts: 3
        waitDuration: 500ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
    instances:
      productService:
        baseConfig: default
        maxAttempts: 5
See @references/configuration-reference.md for retry exception configuration.
添加
@Retry
注解以恢复瞬时故障：
java
@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
中配置重试：
yaml
resilience4j:
  retry:
    configs:
      default:
        maxAttempts: 3
        waitDuration: 500ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
    instances:
      productService:
        baseConfig: default
        maxAttempts: 5
重试异常配置请参考@references/configuration-reference.md。

4. Rate Limiter Pattern

4. 限流模式

Apply 
@RateLimiter
to control request rates:
java
@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.");
    }
}
Configure in 
application.yml
:
yaml
resilience4j:
  ratelimiter:
    configs:
      default:
        registerHealthIndicator: true
        limitForPeriod: 10
        limitRefreshPeriod: 1s
        timeoutDuration: 500ms
    instances:
      notificationService:
        baseConfig: default
        limitForPeriod: 5
添加
@RateLimiter
注解以控制请求速率：
java
@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
中配置：
yaml
resilience4j:
  ratelimiter:
    configs:
      default:
        registerHealthIndicator: true
        limitForPeriod: 10
        limitRefreshPeriod: 1s
        timeoutDuration: 500ms
    instances:
      notificationService:
        baseConfig: default
        limitForPeriod: 5

5. Bulkhead Pattern

5. 舱壁模式

Apply 
@Bulkhead
to isolate resources. Use 
type = SEMAPHORE
for synchronous methods:
java
@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);
    }
}
Use 
type = THREADPOOL
for async/CompletableFuture methods:
java
@Service
public class AnalyticsService {
    @Bulkhead(name = "analyticsService", type = Bulkhead.Type.THREADPOOL)
    public CompletableFuture<AnalyticsResult> runAnalytics(
            AnalyticsRequest request) {
        return CompletableFuture.supplyAsync(() ->
            analyticsEngine.analyze(request));
    }
}
Configure in 
application.yml
:
yaml
resilience4j:
  bulkhead:
    configs:
      default:
        maxConcurrentCalls: 10
        maxWaitDuration: 100ms
    instances:
      reportService:
        baseConfig: default
        maxConcurrentCalls: 5

  thread-pool-bulkhead:
    instances:
      analyticsService:
        maxThreadPoolSize: 8
添加
@Bulkhead
注解以隔离资源。同步方法使用
type = SEMAPHORE
：
java
@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
：
java
@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
中配置：
yaml
resilience4j:
  bulkhead:
    configs:
      default:
        maxConcurrentCalls: 10
        maxWaitDuration: 100ms
    instances:
      reportService:
        baseConfig: default
        maxConcurrentCalls: 5

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

6. Time Limiter Pattern

6. 超时限制模式

Apply 
@TimeLimiter
to async methods to enforce timeout boundaries:
java
@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"));
    }
}
Configure in 
application.yml
:
yaml
resilience4j:
  timelimiter:
    configs:
      default:
        timeoutDuration: 2s
        cancelRunningFuture: true
    instances:
      searchService:
        baseConfig: default
        timeoutDuration: 3s
为异步方法添加
@TimeLimiter
注解以强制执行超时边界：
java
@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
中配置：
yaml
resilience4j:
  timelimiter:
    configs:
      default:
        timeoutDuration: 2s
        cancelRunningFuture: true
    instances:
      searchService:
        baseConfig: default
        timeoutDuration: 3s

7. Combining Multiple Patterns

7. 组合多种模式

Stack multiple patterns on a single method for comprehensive fault tolerance:
java
@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);
    }
}
Execution order: Retry → CircuitBreaker → RateLimiter → Bulkhead → Method
All patterns should reference the same named configuration instance for consistency.
在单个方法上叠加多种模式以实现全面的容错能力：
java
@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. Exception Handling and Monitoring

8. 异常处理与监控

Create a global exception handler using 
@RestControllerAdvice
:
java
@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");
    }
}
Enable Actuator endpoints for monitoring resilience patterns in 
application.yml
:
yaml
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,circuitbreakers,retries,ratelimiters
  endpoint:
    health:
      show-details: always
  health:
    circuitbreakers:
      enabled: true
    ratelimiters:
      enabled: true
Access monitoring endpoints:
  • GET /actuator/health
    - Overall health including resilience patterns
  • GET /actuator/circuitbreakers
    - Circuit breaker states
  • GET /actuator/metrics
    - Custom resilience metrics
使用
@RestControllerAdvice
创建全局异常处理器：
java
@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端点以监控弹性模式：
yaml
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
    - 自定义弹性指标

Best Practices

最佳实践

  • Always provide fallback methods: Ensure graceful degradation with meaningful responses rather than exceptions
  • Use exponential backoff for retries: Prevent overwhelming recovering services with aggressive backoff (
    exponentialBackoffMultiplier: 2
    )
  • Choose appropriate failure thresholds: Set 
    failureRateThreshold
    between 50-70% depending on acceptable error rates
  • Use constructor injection exclusively: Never use field injection for Resilience4j dependencies
  • Enable health indicators: Set 
    registerHealthIndicator: true
    for all patterns to integrate with Spring Boot health
  • Separate failure vs. client errors: Retry only transient errors (network timeouts, 5xx); skip 4xx and business exceptions
  • Size bulkheads based on load: Calculate thread pool and semaphore sizes from expected concurrent load and latency
  • Monitor and adjust: Continuously review metrics and adjust timeouts/thresholds based on production behavior
  • Document fallback behavior: Make fallback logic clear and predictable to users and maintainers
  • 始终提供降级方法：确保返回有意义的响应而非抛出异常，实现优雅降级
  • 重试使用指数退避：通过指数退避（
    exponentialBackoffMultiplier: 2
    ）避免压垮正在恢复的服务
  • 设置合适的故障阈值：根据可接受的错误率，将
    failureRateThreshold
    设置在50-70%之间
  • 仅使用构造函数注入：Resilience4j依赖绝不要使用字段注入
  • 启用健康指标：为所有模式设置
    registerHealthIndicator: true
    ，以集成Spring Boot健康检查
  • 区分故障与客户端错误：仅重试瞬时错误（网络超时、5xx状态码）；跳过4xx和业务异常
  • 根据负载配置舱壁大小：根据预期并发负载和延迟计算线程池和信号量大小
  • 监控并调整配置：持续查看指标，根据生产环境表现调整超时时间/阈值
  • 记录降级行为：让降级逻辑对用户和维护人员清晰可预测

Common Mistakes

常见错误

Refer to 
references/testing-patterns.md
for:
  • Testing circuit breaker state transitions
  • Simulating transient failures with WireMock
  • Validating fallback method signatures
  • Avoiding common misconfiguration errors
Refer to 
references/configuration-reference.md
for:
  • Complete property reference for all patterns
  • Configuration validation rules
  • Exception handling configuration
参考
references/testing-patterns.md
了解：
  • 测试断路器状态转换
  • 使用WireMock模拟瞬时故障
  • 验证降级方法签名
  • 避免常见的配置错误
参考
references/configuration-reference.md
了解：
  • 所有模式的完整属性参考
  • 配置验证规则
  • 异常处理配置

References and Examples

参考资料与示例