Resilience4j 注解顺序与重试策略解析

本文深入剖析了 Resilience4j 中 @Retry、@CircuitBreaker、@TimeLimiter 和 @Bulkhead 四大核心注解的嵌套执行顺序与异常传播机制，揭示其“由外向内执行、由内向外抛异常”的AOP增强本质，并重点解决开发者普遍困惑的痛点——如何让重试策略真正聚焦于服务端错误（如5xx异常），而非误重试超时、断路器拒绝或舱壁满载等基础设施层异常；通过精准配置 ignore-exceptions（优先级高于 retry-exceptions）排除非业务异常，并结合 retry-exceptions 明确指定可重试的服务端异常类型，辅以自定义 Predicate 实现基于HTTP状态码等响应结果的动态判断，最终提供一套零侵入、高可控、生产就绪的重试治理方案。

本文详解 Resilience4j 各核心注解（@Bulkhead、@TimeLimiter、@CircuitBreaker、@Retry）的嵌套执行顺序，结合 CompletableFuture 场景说明异常传播路径，并指导如何通过 retryExceptions、ignoreExceptions 和自定义 Predicate 实现“仅对服务端异常重试”的精准控制。

本文详解 Resilience4j 各核心注解（@Bulkhead、@TimeLimiter、@CircuitBreaker、@Retry）的嵌套执行顺序，结合 CompletableFuture 场景说明异常传播路径，并指导如何通过 retryExceptions、ignoreExceptions 和自定义 Predicate 实现“仅对服务端异常重试”的精准控制。

Resilience4j 的 AOP 增强采用由外向内、层层包裹的执行模型，其实际调用链严格遵循以下嵌套顺序（从最外层到最内层）：

@Retry  
  → @CircuitBreaker  
    → @TimeLimiter  
      → @Bulkhead  
        → 目标方法（downstream1）

这意味着：当方法被调用时，首先由 @Retry 拦截；若需重试，则整个内部链（断路器→超时→舱壁→业务逻辑）将被重复执行。而异常则按逆序向上抛出：目标方法抛出异常 → 舱壁捕获并可能包装为 BulkheadFullException → 超时装饰器捕获并转为 TimeoutException → 断路器检查状态并可能抛 CallNotPermittedException → 最终由 @Retry 决定是否重试。

你对各异常场景的理解基本正确，但需特别注意一个关键细节：@Retry 默认会对所有非受检异常（unchecked exceptions）重试，包括 TimeoutException、CallNotPermittedException 等——这与你的业务诉求（仅对下游服务端错误，如 5xx HTTP 异常重试）相悖。因此，必须显式配置重试过滤策略。

✅ 正确配置方式（推荐组合）

在 application.yml（而非 .properties，更清晰支持嵌套结构）中配置如下：

resilience4j.retry:
  configs:
    default:
      max-attempts: 3
      wait-duration: 100ms
      # ✅ 只对服务端错误重试（如 5xx）
      retry-exceptions:
        - org.springframework.web.client.HttpServerErrorException
        - java.net.SocketTimeoutException
        - java.io.IOException
      # ✅ 明确排除不应重试的异常（优先级高于 retry-exceptions）
      ignore-exceptions:
        - io.github.resilience4j.bulkhead.BulkheadFullException
        - java.util.concurrent.TimeoutException
        - io.github.resilience4j.circuitbreaker.CallNotPermittedException
        - org.springframework.web.client.HttpClientErrorException  # 客户端错误（4xx），不重试

⚠️ 注意：ignore-exceptions 的匹配优先级高于 retry-exceptions，且一旦命中即跳过重试，直接进入 fallback。

? 进阶：基于响应结果的动态重试（可选）

若需更精细控制（例如：HTTP 200 响应但 body 中 status: "FAILED"），可实现 RetryOnResultPredicate：

@Component
public class ShouldRetryOnHttpStatus implements Predicate {
    @Override
    public boolean test(HttpResponse response) {
        return response != null 
            && response.getStatusCode() >= 500 
            && response.getStatusCode() < 600;
    }
}

并在配置中启用：

resilience4j.retry.instances.downstream1:
  base-config: default
  retry-on-result-predicate: com.example.predicates.ShouldRetryOnHttpStatus

? 重要注意事项

• @TimeLimiter + CompletableFuture 是必需组合：你当前代码使用 CompletableFuture 并标注 @TimeLimiter 是正确的；若返回普通 String，则 @TimeLimiter 将无效（无异步上下文）。
• Fallback 方法签名必须兼容所有可能异常类型：你的 downstream1Fallback(String a, Exception e) 已满足要求，能接收各类包装异常。
• 线程池 Bulkhead 与 TimeLimiter 协同：@Bulkhead(type = THREADPOOL) 会提交任务到独立线程池，@TimeLimiter 在该线程内启动超时监控，二者不冲突。
• 避免配置冗余：resilience4j.retry.instances.downstream1.max-attempts=1 在生产环境通常无意义，建议设为 3 并配合指数退避（enable-exponential-backoff: true）。

✅ 总结

你的执行顺序理解准确，但默认重试行为不符合业务目标。无需修改执行顺序（也无法修改），而应通过 ignore-exceptions 精确屏蔽 BulkheadFullException、TimeoutException、CallNotPermittedException 等非服务端异常，再辅以 retry-exceptions 明确限定重试范围。此方案零侵入、高可维护，完全契合“仅对服务端异常重试”的核心诉求。

好了，本文到此结束，带大家了解了《Resilience4j 注解顺序与重试策略解析》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！