Resilience4j：熔断/限流/重试/隔离的配置与使用

服务间调用一旦遇到下游变慢或故障，就可能拖垮上游。Resilience4j 是轻量级容错库，提供熔断、限流、重试、舱壁（隔离）与限时能力，是 Spring Cloud CircuitBreaker 抽象层的推荐实现之一（原 Hystrix 已停止演进）。本系列版本锚点同第 01 章：Spring Boot 3.5.x + Spring Cloud 2025.0.x + spring-cloud-alibaba 2025.0.0.x，具体以官方文档为准。

引入依赖

Spring Boot 3 用 resilience4j-spring-boot3 模块（Boot 2.x 对应 resilience4j-spring-boot2）；若走 Spring Cloud CircuitBreaker 统一封装，则引入 spring-cloud-starter-circuitbreaker-resilience4j。

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
</dependency>

熔断：CircuitBreaker

熔断器状态机为 关闭(CLOSED) -> 打开(OPEN) -> 半开(HALF_OPEN)。滑动窗口分为 COUNT_BASED（按最近 N 次调用）与 TIME_BASED（按最近时间段）。

resilience4j:
  circuitbreaker:
    instances:
      stockService:            # 实例名与注解 name 对应
        sliding-window-type: COUNT_BASED
        sliding-window-size: 10
        minimum-number-of-calls: 5     # 最少统计次数，避免冷启动误判
        failure-rate-threshold: 50     # 失败率超过 50% 打开熔断
        wait-duration-in-open-state: 10s
        permitted-number-of-calls-in-half-open-state: 3

import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;

@CircuitBreaker(name = "stockService", fallbackMethod = "stockFallback")
public StockDTO deduct(StockReqDTO req) {
    return stockFeignClient.deduct(req);
}

// 降级方法：参数与原方法一致，可追加 Throwable 接收异常
private StockDTO stockFallback(StockReqDTO req, Throwable t) {
    log.warn("扣减库存失败，进入降级", t);
    return StockDTO.fail("库存服务暂不可用");
}

限流：RateLimiter

令牌桶思路：每个刷新周期放行固定数量的请求，超出后等待或直接拒绝。

resilience4j:
  ratelimiter:
    instances:
      payService:
        limit-refresh-period: 1s    # 令牌刷新周期
        limit-for-period: 20        # 每周期放行 20 个
        timeout-duration: 500ms     # 等待令牌超时

@RateLimiter(name = "payService", fallbackMethod = "payFallback")
public void pay(PayReqDTO req) { /* 支付逻辑 */ }

重试与舱壁：Retry / Bulkhead

resilience4j:
  retry:
    instances:
      stockService:
        max-attempts: 3             # 总尝试 3 次
        wait-duration: 500ms
  bulkhead:
    instances:
      stockService:
        max-concurrent-calls: 20    # 信号量舱壁：最多 20 并发
        max-wait-duration: 10ms     # 排队等待上限

@Retry(name = "stockService", fallbackMethod = "stockFallback")
public StockDTO queryStock(String skuId) { /* 查询逻辑 */ }

要点：重试只适合“临时性失败”（超时、5xx），对业务性异常（参数错误、幂等冲突）不要重试，可用 ignoreExceptions 排除。Bulkhead 提供信号量（默认）与线程池两种舱壁，防止慢调用占满线程；@TimeLimiter 用于异步调用超时控制。

组合使用顺序

熔断、限流、重试可叠加在同一方法上，顺序可由各模块配置调整。常见组合是“重试套在熔断外”或“熔断包住重试”，需结合业务判断；组合顺序的具体配置方式以官方文档为准。

小结

Resilience4j 以“实例配置 + 注解/函数式 API”两种方式工作，默认值（如 failureRateThreshold=50、waitDurationInOpenState=60s）可全部覆盖。实践中先明确每个下游依赖的故障形态，再决定用熔断、重试还是限流，避免“全部注解一把梭”。