Java 后端 / 知识点
Spring Cloud 微服务速查手册
手册条目
核对统计窗口、失败判定、慢调用阈值和最小请求数量。
排查断路器误触发
当下游仍可访问,但请求突然大量进入降级逻辑或出现 CallNotPermittedException 时,先确认触发的是哪个断路器,再对照窗口样本、失败分类和慢调用统计。目标不是立即放宽阈值,而是找出“哪些调用被计入、何时达到阈值、是否被重试放大”。

先确认触发对象与事件
确保 Actuator 已暴露 circuitbreakers 和 circuitbreakerevents 端点,然后按实例名过滤最近事件。若返回 404,先检查端点暴露配置;若实例名不存在,常见原因是注解中的 name、工厂创建时的 ID 与配置键不一致。
BASE_URL=http://localhost:8080
CB_NAME=inventoryService
curl -fsS "$BASE_URL/actuator/circuitbreakers"
curl -fsS "$BASE_URL/actuator/circuitbreakerevents" \
| jq --arg name "$CB_NAME" \
'[.circuitBreakerEvents[] | select(.circuitBreakerName == $name)][-10:]'预期输出
{"circuitBreakers":["inventoryService","paymentService"]}
[
{
"circuitBreakerName": "inventoryService",
"type": "ERROR",
"creationTime": "<TIME>",
"errorMessage": "java.net.SocketTimeoutException: Read timed out",
"durationInMs": 1204
}
]<TIME> 和耗时会随环境变化。若日志只有业务异常或客户端 4xx,却被记录为 ERROR,优先检查失败判定;若同一入口短时间出现多条相似事件,继续确认重试是否让一次业务请求被统计多次。
核对窗口与阈值
management:
endpoints:
web:
exposure:
include: health,metrics,circuitbreakers,circuitbreakerevents
resilience4j:
circuitbreaker:
instances:
inventoryService:
slidingWindowType: COUNT_BASED
slidingWindowSize: 20
minimumNumberOfCalls: 10
failureRateThreshold: 50
slowCallDurationThreshold: 800ms
slowCallRateThreshold: 60
permittedNumberOfCallsInHalfOpenState: 5
waitDurationInOpenState: 10s
eventConsumerBufferSize: 100配置生效后,至少累计 minimumNumberOfCalls 个样本才会计算失败率或慢调用率。排查时重点比较正常流量基线:最小样本过小会被瞬时抖动击穿;slowCallDurationThreshold 低于正常高分位延迟会把健康请求计为慢调用;时间窗口过短会放大突发失败,过长则会让旧故障持续影响当前状态。
检查失败判定与组合顺序
逐项确认 recordExceptions、ignoreExceptions、recordFailurePredicate 是否把业务校验异常、限流异常、主动取消或可接受的 4xx 算作失败。再检查 Retry、TimeLimiter 与断路器的组合:超时异常可能被计为失败,外层重试还可能让一次业务请求多次穿过断路器。
临时验证应只针对一个实例调整谓词或阈值,并配合事件端点观察;不要直接修改全局默认配置。Spring Cloud CircuitBreaker 的属性配置优先级通常高于 Java Customizer,所以代码里看似正确的设置仍可能被配置文件覆盖。
风险与边界
直接把失败率阈值调高、最小请求数调大或长时间强制关闭,可能掩盖真实下游故障并放大线程、连接池耗尽。更安全的替代方案是先修正异常分类、慢调用基线和实例名映射,再小范围调整单实例配置并观察一个完整窗口。
不要把断路器 OPEN 直接映射为应用整体不可用,除非该依赖确实决定服务生存状态;否则健康检查可能触发实例摘除,进一步加剧流量集中。
排障清单
- 实例名是否与注解、工厂 ID、配置键完全一致。
- 实际样本量是否达到
minimumNumberOfCalls,窗口类型和大小是否符合流量特征。 - 失败事件是否主要来自被误分类的业务异常、4xx、超时或取消。
- 正常延迟是否经常超过
slowCallDurationThreshold。 - Retry、TimeLimiter、线程池或连接池饱和是否放大失败统计。
- 配置中心、环境变量或启动参数是否覆盖了本地配置。
速查结论:先用事件确认“谁触发、记了什么”,再校准窗口和分类;仅调大阈值通常只是延后下一次误触发。


