Circuit Breaker
解释下游持续失败时为什么要暂时停止真实调用，以及 Closed、Open、Half-Open 状态如何限制故障扩散并探测恢复。
#concept
#growing
#backend
#reliability
[!info] related notes
Circuit Breaker
[!abstract] 一句话定义 Circuit Breaker 在下游持续失败或变慢时暂时停止真实调用，直接快速失败或降级，并在冷却后用少量探测请求判断是否恢复，避免调用方不断浪费资源并放大故障。
为什么 Retry 不够
Downstream unavailable
→ every request waits timeout
→ every request retries 3 times
→ traffic and resource use multiply
→ downstream recovery becomes harderCircuit Breaker 的目的不是修复依赖，而是减少无意义调用和级联占用。
三个经典状态
Closed
→ normal calls pass
→ failures exceed threshold
Open
→ fail fast / fallback
→ after cooldown
Half-Open
→ allow limited probes
→ enough success: Closed
→ failure: Open again实际实现可能使用滑动窗口、错误率、慢调用率、最小样本数和不同探测策略，但核心状态机一致。
什么错误应计入
通常计入：
- 网络连接失败；
- Timeout；
- 5xx；
- 依赖明确过载；
- 超过慢调用阈值。
通常不应计入：
- 当前用户输入非法；
- 业务规则拒绝；
- 认证/授权失败；
- Client 主动取消；
- 与依赖健康无关的本地 Bug。
分类错误会让一个健康下游因为大量 400 被错误熔断。429 也要区分单租户额度耗尽与共享 Provider 过载；前者不能直接触发所有租户的全局熔断。
Circuit Breaker 保护谁
它首先保护调用方的线程、连接和延迟预算，同时减少对故障下游的压力。它不保证：
- 数据不会丢；
- 副作用幂等；
- 所有实例共享同一状态；
- 下游真正恢复；
- Fallback 输出满足质量要求。
因此仍需 Timeout、Bulkhead、Idempotency、Observability 和 Fallback。
Breaker 粒度
可按：
- Provider / Host；
- Endpoint / Capability；
- Region；
- Tenant；
- Model；
- Tool。
粒度太粗会让一个小故障关闭全部能力；太细则样本不足且状态复杂。应围绕共同故障域划分。
Half-Open 的风险
如果所有实例同时到期并大量探测，会产生恢复风暴。可采用：
- 随机化冷却时间；
- 限量 Probe；
- 分布式状态或每实例错峰；
- 逐步提升流量；
- 与健康信号和 Canary 结合。
Agent / Model 场景
Provider 429 / timeout rate high
→ open breaker for that provider-capability
→ route compatible traffic to fallback
→ probe after cooldown
→ close only after success threshold认证失败通常是配置错误，不应不断探测；模型输出质量下降也不应只靠 HTTP Breaker 判断，而要接 Eval / Quality Gate。Half-Open 探测若会产生写入或工具副作用，仍需授权与幂等约束，不能为了探活重复执行用户操作。
观测重点
state transitions
failure and slow-call rate
open duration
rejected calls
half-open probes
fallback rate
per-dependency latency and errors设计检查表
- 失败分类与最小样本量明确。
- 慢调用和错误率阈值来自 SLO / 容量，而不是随意数字。
- Open 时的错误/降级对调用方可理解。
- Half-Open Probe 有严格上限并避免同步恢复风暴。
- Breaker 与 Timeout、Bulkhead、Retry 顺序明确。
- 状态转换和 Fallback 使用率可观测。
Digital Biome