---
name: circuit-breaker
when: '服务降级, 熔断, 限流, 降级, 级联故障, 服务雪崩, Sentinel, Hystrix, Resilience4j, 服务保护, 容错'
scope:
  - backend
products:
  - '*'
id: ka-pattern-circuit-breaker
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 服务降级
  - 熔断
  - 限流
  - 降级
  - 级联故障
  - 服务雪崩
  - Sentinel
  - Hystrix
  - Resilience4j
  - 服务保护
  - 容错
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 外部依赖（第三方 API、中间件、其他微服务）必须配置超时时间，禁止无限等待
- 核心链路的外部调用必须配置熔断器：失败率阈值（建议 50%）、熔断时长（建议 30s）、半开探测数（建议 5）
- 熔断触发后必须有降级策略：返回缓存数据/默认值/友好提示，禁止直接抛异常给用户
- 接口必须有限流保护（令牌桶/漏桶），防止突发流量击穿服务
- 降级方案必须提前定义：降级行为、用户提示文案、数据一致性保障、恢复条件
- 重试必须满足幂等性，重试间隔必须使用指数退避（initial 100ms, multiplier 2, max 3 次）
- 线程池隔离：不同外部依赖使用独立线程池，防止一个慢服务拖垮所有请求
- 必须有服务健康检查端点（/actuator/health），包含依赖组件状态（DB/Redis/MQ）
- 熔断器必须配置 half-open 状态的探测请求量（如允许 5 个请求通过测试），成功后才恢复
- 降级 fallback 必须返回有意义的默认值或缓存数据，禁止返回 null 或空对象
- 熔断/降级事件必须触发监控告警，不能静默降级
- 外部调用必须设置独立的超时时间（不依赖全局超时），与熔断器配合使用
- 熔断器状态变化必须有日志记录（closed → open → half-open → closed）

## 验收项
- [AC-01] 外部调用有超时和熔断配置
- [AC-02] 熔断后有降级策略和用户提示
- [AC-03] 重试有指数退避和幂等保障
- [AC-04] 有限流保护
- [AC-05] 健康检查端点包含依赖状态
- [AC-06] half-open 探测机制配置
- [AC-07] fallback 返回有意义的值
- [AC-08] 熔断事件有监控告警
- [AC-09] 外部调用有独立超时
