Spring Cloud Gateway断路器必须配合Resilience4j使用，其本身不内置熔断逻辑；需显式引入resilience4j-spring-cloud2依赖并正确配置实例名、fallback路径及失败判定规则，否则过滤器将静默失效。
断路器过滤器必须配合 Resilience4j 使用
Spring Cloud Gateway 本身不内置熔断逻辑，Resilience4j 是当前 Spring Cloud 2026 默认集成的容错库。如果你还在用旧版的 Hystrix（已废弃）或没显式引入 resilience4j-spring-cloud2，Retry、CircuitBreaker 这类过滤器会静默失效，连日志都不报错——这是最常被忽略的启动失败点。
确保 pom.xml 中有：
<dependency> <groupId>io.github.resilience4j</groupId> <artifactId>resilience4j-spring-cloud2</artifactId> </dependency>
- 版本需与 Spring Boot 3.x + Spring Cloud 2026 兼容（如
resilience4j-spring-cloud2:2.1.0） - 不要同时引入
spring-cloud-starter-circuitbreaker-resilience4j和resilience4j-spring-cloud2，后者已包含前者功能，重复引入会导致CircuitBreakerFilter初始化冲突 - 启用全局断路器需配置
spring.cloud.gateway.default-filters，而非只在单个路由里加
全局熔断必须显式配置断路器实例和 fallback URI
CircuitBreaker 过滤器不是开箱即用的“开关”，它依赖预定义的断路器配置。直接写 - CircuitBreaker 会抛出 No circuit breaker found for name 'default' 错误。
正确做法是两步走：先声明断路器 bean 或 yml 配置，再在过滤器中引用名称：
resilience4j.circuitbreaker:
instances:
backend-service:
failure-rate-threshold: 50
minimum-number-of-calls: 10
automatic-transition-from-open-to-half-open-enabled: true
wait-duration-in-open-state: 30s然后在路由或默认过滤器中使用：
OpenClaw Gateway 重启性能分析工具：分析重启速度、定位启动慢原因、生成性能报告、诊断启动问题。支持 Windows (PowerShell) 与 Linux (Bash)。触发场景：分析 gateway 重启、检查启动时间、生成报告、诊断异常。
- CircuitBreaker=backend-service, forward:/fallback
-
forward:/fallback是关键：它必须指向网关内部的一个 controller 路径（如@GetMapping("/fallback")），不能是外部 URL - 如果 fallback 返回 503 但客户端收不到响应体，检查是否漏配了
spring.cloud.gateway.httpclient.response-timeout，超时会中断 fallback 流程 - 断路器名称（如
backend-service）必须与 yml 中resilience4j.circuitbreaker.instances.*下的 key 完全一致，大小写敏感
熔断触发条件容易被路径匹配干扰
断路器只对「成功转发到下游但返回异常响应」的请求计数，比如服务返回 5xx、连接超时、ReadTimeout。但它**不会**因路由未匹配（404）、断言失败（如 Path 不匹配）或网关自身异常（如 NPE）而开启。
这意味着：如果你的 predicates 写错了导致大量 404，断路器完全无感；反过来，若下游服务偶发 500，但你没设 ignore-exceptions，一次 NPE 就可能让断路器立刻跳闸。
- 用
record-exceptions显式指定哪些异常计入失败（默认只记CallNotPermittedException和 IO 异常） - 避免把
NullPointerException这类编程错误纳入熔断，否则故障定位会被掩盖 - 测试时用
curl -v http://localhost:8080/api/users触发真实调用，别只测/actuator/health—— 健康端点走的是 WebMvc，绕过了 Gateway 的 Filter 链
fallback 响应体必须手动构造，不能依赖下游返回
当断路器打开后，forward:/fallback 会走 Spring MVC 流程，但此时请求上下文（ServerWebExchange）已被切断，原始请求头、body、query 参数默认不可见。
如果你在 fallback controller 里直接返回 JSON 字符串，客户端看到的 Content-Type 可能是 text/plain，前端解析失败。
- fallback 接口必须用
@RestController，且显式设置produces = "application/json" - 想透传原始请求 ID，得靠
ServerWebExchange的getAttributes()提前存入，不能依赖 header 传递 - 别在 fallback 里再调其他服务——它本就是降级终点，二次调用会让熔断失去意义
熔断不是加一行配置就完事的事。真正难的是判断「什么算失败」、决定「谁该看到降级页」、以及确保 fallback 路径本身不成为新的单点故障。这些细节不提前对齐，上线后只会把问题从下游转移到网关层。
