Spring Boot 3.x 服务容错：用…

在 Spring Boot 3.x 中为调用外部服务的代码添加熔断、重试、限流、舱壁隔离、超时和降级，防止级联故障。

适用场景

解决思路

1. 添加依赖：在 pom.xml 中加入 io.github.resilience4j:resilience4j-spring-boot3:2.2.0、spring-boot-starter-aop、spring-boot-starter-actuator；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(name = "paymentService", fallbackMethod = "paymentFallback")，并编写同名降级方法（参数相同并额外接收 Exception）；在 application.yml 的 resilience4j.circuitbreaker 下配置 default 与实例级参数，如 registerHealthIndicator: true、slidingWindowSize: 10、minimumNumberOfCalls: 5、failureRateThreshold: 50、waitDurationInOpenState: 10s。
3. 对瞬时失败使用 @Retry(name = "productService", fallbackMethod = "getProductFallback") 并编写降级方法；在 resilience4j.retry 下配置 maxAttempts: 3、waitDuration: 500ms、enableExponentialBackoff: true、exponentialBackoffMultiplier: 2，可按实例覆盖（如 maxAttempts: 5）。
4. 对请求速率控制使用 @RateLimiter(name = "notificationService", fallbackMethod = "rateLimitFallback")，降级方法可抛出 RateLimitExceededException；在 resilience4j.ratelimiter 下配置 registerHealthIndicator: true、limitForPeriod: 10、limitRefreshPeriod: 1s、timeoutDuration: 500ms，可按实例覆盖（如 limitForPeriod: 5）。
5. 对同步方法使用 @Bulkhead(name = "reportService", type = Bulkhead.Type.SEMAPHORE) 隔离资源；对异步/CompletableFuture 方法使用 @Bulkhead(name = "analyticsService", type = Bulkhead.Type.THREADPOOL)；在 resilience4j.bulkhead 下配置 maxConcurrentCalls: 10、maxWaitDuration: 100ms，在 resilience4j.thread-pool-bulkhead 下配置 maxThreadPoolSize: 8。
6. 对异步方法使用 @TimeLimiter(name = "searchService", fallbackMethod = "searchFallback") 强制超时边界，降级方法返回 CompletableFuture.completedFuture(...)；在 resilience4j.timelimiter 下配置 timeoutDuration: 2s、cancelRunningFuture: true，可按实例覆盖（如 timeoutDuration: 3s）。
7. 在单个方法上叠加多个模式实现综合容错，例如同时标注 @CircuitBreaker(name = "orderService")、@Retry(name = "orderService")、@RateLimiter(name = "orderService")、@Bulkhead(name = "orderService")；执行顺序为 Retry → CircuitBreaker → RateLimiter → Bulkhead → Method，所有模式应引用同一个命名配置实例以保持一致。
8. 使用 @RestControllerAdvice 创建全局异常处理器：用 @ExceptionHandler(CallNotPermittedException.class) 返回 503 SERVICE_UNAVAILABLE，用 @ExceptionHandler(RequestNotPermitted.class) 返回 429 TOO_MANY_REQUESTS，用 @ExceptionHandler(BulkheadFullException.class) 返回 503 CAPACITY_EXCEEDED。
9. 在 application.yml 中启用 Actuator 监控：management.endpoints.web.exposure.include: health,metrics,circuitbreakers,retries,ratelimiters；management.endpoint.health.show-details: always；management.health.circuitbreakers.enabled: true；management.health.ratelimiters.enabled: true；通过 GET /actuator/health、GET /actuator/circuitbreakers、GET /actuator/metrics 查看状态与指标。
10. 按验证流程测试各模式：熔断——调用失败端点后检查 GET /actuator/circuitbreakers 显示 OPEN，等待 waitDurationInOpenState 后验证转为 HALF_OPEN 再到 CLOSED；重试——启用 resilience4j.retry.metrics.enabled: true 后调用端点，验证 retry.{instance}.successful-calls-with-retry-attempts 指标增长；限流——发送超过 limitForPeriod 的请求，验证返回 429 且 GET /actuator/ratelimiters 显示 LIMITED；舱壁——并发压测超过 maxConcurrentCalls，验证多余请求立即以 BulkheadFullException 失败；超时——模拟超过 timeoutDuration 的异步延迟，验证超时后触发降级。
11. 遵循最佳实践：始终提供有意义的降级方法实现优雅降级；使用指数退避（exponentialBackoffMultiplier: 2）避免压垮正在恢复的服务；failureRateThreshold 设置在 50-70% 之间；使用构造器注入而非字段注入；为所有模式设置 registerHealthIndicator: true；只对瞬时错误（网络超时、5xx）重试，跳过 4xx 和业务异常；根据预期并发量计算舱壁的线程池和信号量大小；清晰记录降级行为。
12. 注意约束与警告：降级方法必须与原方法签名相同并额外接收可选的异常参数；熔断器状态是按实例的，多租户场景需确保正确的 bean 作用域；重试操作必须幂等（可能执行多次）；对必须完成的操作不要用熔断器，应改用超时；限流器可能导致线程阻塞，需配置合适的等待时长；对非幂等操作（如 POST 请求）慎用 @Retry；高并发下使用线程池舱壁时需监控内存。

适用边界 · 注意事项

• 对必须始终完成的操作不要使用熔断器，应改用超时机制
• 对非幂等操作（如 POST 请求）慎用 @Retry，因为重试可能重复执行
• 高并发场景下使用线程池舱壁时需谨慎，可能带来内存压力