SpringBoot3 下使用 Resilience4j 实现高可用容错机制

📌 前言

在微服务或接口聚合系统中，服务调用可能由于网络抖动、第三方不稳定等因素而失败。为了提升系统的弹性与稳定性，Resilience4j 提供了一套完整的容错组件，涵盖了重试、熔断、限流、超时控制和资源隔离。

本文将介绍 Resilience4j 的 核心模块原理、注解用法 以及如何在 Spring Boot 项目中优雅集成，并通过图表帮助理解模块协作逻辑。

📦 1. 引入依赖

使用 Spring Boot + Maven 管理项目，添加如下依赖：

XML

<dependency>
  <groupId>io.github.resilience4j</groupId>
  <artifactId>resilience4j-spring-boot3</artifactId>
</dependency>

🧩 2. Resilience4j 核心模块说明

模块名	功能	应用场景
`Retry`	失败自动重试	网络抖动、瞬时失败
`CircuitBreaker`	熔断器	故障隔离，避免雪崩
`RateLimiter`	限流器	限制调用频率
`Bulkhead`	线程隔离/信号量隔离	防止单点服务拖垮系统
`TimeLimiter`	超时限制	控制服务调用响应时间

🔄 模块协作流程图

flowchart TD
    A[调用方] --> R[Retry 重试器]
    R --> CB[CircuitBreaker 熔断器]
    CB --> RL[RateLimiter 限流器]
    RL --> TL[TimeLimiter 超时控制器]
    TL --> BH[Bulkhead 资源隔离器]
    BH --> S[最终服务调用]

CodeBlock Loading...

上图展示了各模块可串联执行的调用链，所有模块都是可选启用的。

🧾 3. 注解方式使用详解

Spring Boot 集成 Resilience4j 后，支持以下注解方式：

🔁 @Retry

JAVA

@Retry(name = "imageRetry", fallbackMethod = "fallback")
public String generateImage(String prompt) {
    return callImageApi(prompt);
}

public String fallback(String prompt, Throwable t) {
    return "fallback result";
}

YAML 配置：

YAML

resilience4j.retry:
  instances:
    imageRetry:
      max-attempts: 3
      wait-duration: 1s

⚡ @CircuitBreaker

JAVA

@CircuitBreaker(name = "imageCB", fallbackMethod = "fallback")
public String generateImage(String prompt) {
    return callImageApi(prompt);
}

YAML

resilience4j.circuitbreaker:
  instances:
    imageCB:
      failure-rate-threshold: 50
      sliding-window-size: 5
      wait-duration-in-open-state: 10s

🚦 @RateLimiter

JAVA

@RateLimiter(name = "imageRL", fallbackMethod = "fallback")
public String generateImage(String prompt) {
    return callImageApi(prompt);
}

YAML

resilience4j.ratelimiter:
  instances:
    imageRL:
      limit-for-period: 5
      limit-refresh-period: 1s

⛓️ @Bulkhead

JAVA

@Bulkhead(name = "imageBH", fallbackMethod = "fallback")
public String generateImage(String prompt) {
    return callImageApi(prompt);
}

YAML

resilience4j.bulkhead:
  instances:
    imageBH:
      max-concurrent-calls: 3

⏱️ @TimeLimiter（用于异步方法）

JAVA

@TimeLimiter(name = "imageTL", fallbackMethod = "fallback")
public CompletableFuture<String> generateImage(String prompt) {
    return CompletableFuture.supplyAsync(() -> callImageApi(prompt));
}

YAML

resilience4j.timelimiter:
  instances:
    imageTL:
      timeout-duration: 2s

🔗 注解组合推荐顺序

JAVA

@Retry(name = "img")
@CircuitBreaker(name = "img")
@RateLimiter(name = "img")
@Bulkhead(name = "img")
public String generateImage(String prompt) {
    return callImageApi(prompt);
}

所有模块共享一个名字 img，通过 application.yml 统一配置。

❗ 注解与 fallback 的注意事项

❓ 如果 `@Retry` 触发了 fallback，还会进入 `@CircuitBreaker` 吗？

❌ 不会！
一旦 @Retry 的 fallbackMethod 成功返回了结果，就不会继续抛出异常，也就不会被 CircuitBreaker 感知。

✅ 推荐方式：

使用 @CircuitBreaker 管理 fallback，让 @Retry 负责重试：

JAVA

@Retry(name = "imgRetry")
@CircuitBreaker(name = "imgCB", fallbackMethod = "fallback")
public String generateImage(String prompt) {
    return callImageApi(prompt);
}

🧠 高级用法：多级 fallback 链式降级（A → B → C）

使用注解无法实现多级 fallback，可以通过编程式方式链式组合：

JAVA

Try.ofSupplier(callA)
   .recover(t1 -> Try.ofSupplier(callB)
       .recover(t2 -> Try.ofSupplier(callC)
           .recover(t3 -> "最终fallback结果")
           .get())
       .get())
   .get();

配合 CircuitBreaker.decorateSupplier(...) 等函数式接口可构建完整容错链。

📈 Micrometer 指标集成

Spring Boot 集成 Resilience4j 后，默认支持 Actuator + Prometheus，可观察以下指标：

resilience4j_circuitbreaker_calls_total
resilience4j_retry_calls_total
resilience4j_rate_limiter_wait_duration_seconds

✅ 总结

功能	注解	YAML配置	支持 fallback
Retry	✅	✅	✅
CircuitBreaker	✅	✅	✅
RateLimiter	✅	✅	✅
Bulkhead	✅	✅	✅
TimeLimiter	✅	✅	✅ (异步)

推荐在 Spring Boot 项目中结合注解 + YAML 快速落地
复杂容错链推荐用编程式组合实现
fallback 策略建议交由 CircuitBreaker 管理更清晰

📚 延伸阅读

官方文档：https://resilience4j.readme.io/
GitHub 项目：https://github.com/resilience4j/resilience4j
Micrometer 指标整合：https://micrometer.io

SpringBoot3 下使用 Resilience4j 实现高可用容错机制

SpringBoot3 下使用 Resilience4j 实现高可用容错机制

📌 前言

📦 1. 引入依赖

🧩 2. Resilience4j 核心模块说明

🔄 模块协作流程图

🧾 3. 注解方式使用详解

🔁 @Retry

⚡ @CircuitBreaker

🚦 @RateLimiter

⛓️ @Bulkhead

⏱️ @TimeLimiter（用于异步方法）

🔗 注解组合推荐顺序

❗ 注解与 fallback 的注意事项

❓ 如果 @Retry 触发了 fallback，还会进入 @CircuitBreaker 吗？

✅ 推荐方式：

🧠 高级用法：多级 fallback 链式降级（A → B → C）

📈 Micrometer 指标集成

✅ 总结

📚 延伸阅读

❓ 如果 `@Retry` 触发了 fallback，还会进入 `@CircuitBreaker` 吗？