Spring Cloud Gateway集成Resilience4j断路器不触发问题排查

结合你使用的Spring Boot 2.7.10 + Spring Cloud 2021.0.6（Jubilee）版本，代码配置断路器未触发跳闸的常见原因如下：

1. 未正确关联TimeLimiter与断路器 #

Resilience4j的断路器本身不处理超时逻辑，超时需要通过TimeLimiter组件触发，若代码中仅配置了CircuitBreaker，未绑定对应的TimeLimiter，后端超时不会被识别为失败事件，自然不会触发断路器跳闸。

排查与修复：

• 确保代码中同时创建TimeLimiterConfig并绑定到网关过滤器：

  // 配置TimeLimiter
  TimeLimiterConfig timeLimiterConfig = TimeLimiterConfig.custom()
          .timeoutDuration(Duration.ofMillis(200))
          .build();
  timeLimiterRegistry.addConfiguration("backend-tl", timeLimiterConfig);
  
  // 路由配置中同时指定断路器和TimeLimiter
  .filters(f -> f.resilience4j(config -> config
          .circuitBreaker(cb -> cb.name("backend-cb"))
          .timeLimiter(tl -> tl.name("backend-tl"))))
  

2. 断路器未记录超时相关异常 #

默认情况下，Resilience4j断路器不会自动将网关超时异常（如GatewayTimeoutException、TimeoutException）标记为失败。若未配置异常记录规则，超时请求不会被计入失败计数。

排查与修复：

• 在CircuitBreakerConfig中明确添加需要记录的异常：

  CircuitBreakerConfig circuitBreakerConfig = CircuitBreakerConfig.custom()
          .failureRateThreshold(50) // 失败率阈值，默认50%
          .slidingWindowSize(10) // 滑动窗口大小，默认100
          .recordExceptions(GatewayTimeoutException.class, TimeoutException.class)
          .build();
  

3. 断路器实例与过滤器绑定错误 #

若代码中创建的CircuitBreaker配置未正确注册到Spring容器的CircuitBreakerRegistry，或过滤器引用的断路器名称与配置的名称不匹配，会导致过滤器使用默认配置而非自定义配置。

排查与修复：

• 确保自定义的CircuitBreakerConfig通过circuitBreakerRegistry.addConfiguration()注册，且路由配置中指定的断路器名称与注册的名称一致。
• 避免手动创建独立的CircuitBreaker实例，优先使用Spring自动配置的CircuitBreakerRegistry管理实例。

4. 过滤器顺序错误 #

Resilience4j网关过滤器需要包裹后端调用逻辑，若过滤器顺序晚于NettyRoutingFilter（负责实际转发请求到后端），超时逻辑不会生效。

排查与修复：

• 确认路由配置中Resilience4j过滤器的顺序，可显式设置优先级（默认优先级已足够，但需确保未被其他过滤器覆盖）：

  .filters(f -> f.resilience4j(...)
          .order(-1)) // 确保在NettyRoutingFilter之前执行
  

5. 版本依赖冲突 #

Spring Cloud 2021.0.6默认依赖Resilience4j 1.7.x版本，若pom中手动指定了其他版本的Resilience4j依赖，可能导致配置API不兼容，自定义配置无法生效。

排查与修复：

• 移除pom中手动指定的Resilience4j版本，直接使用Spring Cloud提供的依赖管理：

  <dependencyManagement>
      <dependencies>
          <dependency>
              <groupId>org.springframework.cloud</groupId>
              <artifactId>spring-cloud-dependencies</artifactId>
              <version>2021.0.6</version>
              <type>pom</type>
              <scope>import</scope>
          </dependency>
      </dependencies>
  </dependencyManagement>
  

6. 滑动窗口配置与请求次数不匹配 #

若断路器配置的滑动窗口类型为COUNT_BASED（默认）且窗口大小大于你的测试请求次数（比如窗口大小设为100，而你只请求了20次），即使全部失败，也未达到失败率阈值的统计基数，不会触发跳闸。

排查与修复：

• 调整滑动窗口大小为测试次数范围内的值，比如：

  CircuitBreakerConfig.custom()
          .slidingWindowType(SlidingWindowType.COUNT_BASED)
          .slidingWindowSize(10) // 10次请求内失败率达标即跳闸
          .build();
  

额外验证步骤 #

• 启用Actuator端点，访问/actuator/circuitbreakers查看断路器的实时状态，确认失败计数、失败率是否符合预期。
• 查看网关TRACE日志，确认是否有GatewayTimeoutException或TimeoutException抛出，若没有则说明超时配置未生效。

内容的提问来源于stack exchange，提问作者silverfox