API 熔断器设计指南（免费版）
一、它解决什么问题
下游服务故障或变慢时，若调用方持续重试、等待，连接池/线程池会被逐步占满，
故障沿调用链向上蔓延，最终拖垮整条链路——级联雪崩。
熔断器像家里的电闸：下游异常到一定程度就"跳闸"，调用立即快速失败（fail-fast），
不再压向下游；给下游恢复时间，恢复后自动"合闸"。
它是微服务韧性三件套之一：超时重试（timeout-retry）→ 限流（rate-limit）→ 熔断（circuit-breaker）。
二、三态状态机
失败率≥阈值(且样本≥min_calls)
CLOSED ───────────────────────────────► OPEN
▲ │
│ 半开探测全部成功 │ 冷却 wait_duration 后
│ ▼
└─────────────────────────────── HALF_OPEN
探测期任一失败 → 重新 OPEN
| 状态 | 含义 | 对请求的动作 |
|---|---|---|
| CLOSED（闭合） | 下游正常 | 放行，同时在滑动窗口统计成败 |
| OPEN（打开/熔断中） | 下游异常 | 直接快速失败，不发往下游；可返回降级结果 |
| HALF_OPEN（半开） | 冷却结束，试探下游 | 仅放行少量探测请求，据结果决定恢复或重新熔断 |
三、关键参数设计规则
| 参数 | 含义 | 设计要点 |
|---|---|---|
| 失败率阈值 fail_threshold | 触发熔断的失败比例，常取 0.5 | 超时、拒绝、5xx 都应计为失败 |
| 最小样本 min_calls | 窗口内至少多少请求才参与判定，常取 10~20 | 防止小样本误判：只来了 2 个请求恰好都失败，不应立刻熔断 |
| 冷却时间 wait_duration | OPEN 持续多久才进入 HALF_OPEN，常取 30s 起 | 太短下游没恢复会反复跳，太长恢复慢 |
| 半开探测数 half_open_calls | HALF_OPEN 放行的探测请求数，常取 3~5 | 探测期并发要受限，避免又把下游压垮 |
| 滑动窗口 window_size | 统计窗口大小 | 只看近期请求，过期结果不影响判定 |
四、落地检查清单
- [ ] 调用下游前先问熔断器是否放行；OPEN 时走快速失败或降级（缓存默认值/兜底文案）
- [ ] 每次调用结果（成功/失败/超时）都回填熔断器
- [ ] 失败统计覆盖：连接失败、超时、5xx；业务级 4xx 是否计失败需按场景定
- [ ] 设置了 min_calls，样本不足不熔断
- [ ] HALF_OPEN 限制探测并发，任一探测失败即重新 OPEN 并重置冷却
- [ ] 探测全部成功才 CLOSED，并清空旧统计窗口
- [ ] 熔断状态变更有日志/指标（state、opened_at），便于告警与复盘
- [ ] OPEN 期间提供有意义的降级响应，而不是把错误原样抛给终端用户
五、判定示例
- 窗口内 10 个请求、6 个失败（60% ≥ 阈值 50%，样本达标）→ CLOSED 转 OPEN
- OPEN 后仅过 20s（< 冷却 30s）→ 请求仍被拒绝；过 40s → 转 HALF_OPEN 放行探测
- HALF_OPEN 放行 3 个探测请求：3 个都成功 → CLOSED；其中 1 个失败 → 重新 OPEN
- 窗口内只有 5 个请求且全部失败，但 min_calls=10 → 样本不足，保持 CLOSED
六、硬性规则
- 阈值、样本、冷却时间必须按下游真实容量与历史故障时长设定，不照搬数字。
- 熔断器只负责"快速失败与恢复探测"，不替代降级逻辑与重试策略，三者配合。
- 不得在样本不足时熔断，也不得在下游未真正恢复时盲目合闸。
- 本指南为设计方法；需要按真实成败数据自动计算状态，请使用专业版。
