参考：Opossum 配置、事件与三态速查
基于 Opossum 8.x · 核于 2026-08
速查
- Opossum：Red Hat 维护的 Node.js 熔断器库，把异步函数包进熔断器，错误率超阈值就跳闸快速失败，防雪崩。
- 三态：Closed（正常放行+统计）、Open（全拒快速失败）、Half-Open（放一个试探恢复）。
- 错误率：窗口内失败数 / 总调用数，超 errorThresholdPercentage（默认 50%）跳闸。
- fallback：熔断或失败时的兜底函数，返回缓存/默认值，保业务降级可用。
- 核心配置：timeout（默认 10s）、errorThresholdPercentage（默认 50）、resetTimeout（默认 30s）、rollingCountTimeout（默认 10s）、rollingCountBuckets（默认 10）、volumeThreshold（默认 0）。
- 事件：success/failure/timeout/reject/open/close/halfOpen/fallback/semaphoreLocked。
- vs circuit-breaker-js：后者 2013 年停更（12 年+），Opossum 是 Node.js 事实标准。
- 容错组合：超时 + 重试 + 熔断 + 降级 + 限流，单一模式不够。
一、熔断器三态转换图
错误率 > 阈值 且 调用量 ≥ volumeThreshold
┌──────────────────────────────────────────┐
▼ │
┌─────────┐ ┌─────────┐
│ Closed │ │ Open │
│ (放行) │◄────── halfOpen 试探成功 ──────│ (全拒) │
│ +统计 │ │ +fallback│
└─────────┘ └─────────┘
▲ │
│ resetTimeout 到期
│ ▼
│ ┌──────────────┐ ┌──────────┐
└────────────│ Half-Open │◄───────│ (放一个 │
试探成功 │ (试探一个) │ 切入 │ 请求) │
└──────────────┘ └──────────┘
│
│ 试探失败
▼
回 Open（再等 resetTimeout）| 转换 | 触发条件 | 事件 |
|---|---|---|
| Closed → Open | 错误率超阈值 + 调用量达标 | open |
| Open → Half-Open | resetTimeout 到期 | halfOpen |
| Half-Open → Closed | 试探请求成功 | close |
| Half-Open → Open | 试探请求失败 | open |
二、配置项速查
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
timeout | Number/false | 10000 | 单次调用超时（ms），false 禁用 |
errorThresholdPercentage | Number | 50 | 错误率跳闸阈值（%） |
resetTimeout | Number | 30000 | Open 后多久试探（ms） |
rollingCountTimeout | Number | 10000 | 统计窗口长度（ms） |
rollingCountBuckets | Number | 10 | 窗口分桶数 |
volumeThreshold | Number | 0 | 最小调用量才统计 |
maxCapacity | Number | 无限 | 最大并发调用数 |
maxFailures | Number | - | 已废弃，用 errorThresholdPercentage 替代 |
cache | Boolean | false | 是否缓存成功结果 |
enabled | Boolean | true | 是否启用熔断 |
name | String | 自动生成 | 熔断器名（用于日志/指标） |
healthCheckFunc | Function | - | 自定义健康检查函数 |
生产调参建议
| 场景 | timeout | errorThresholdPercentage | resetTimeout | volumeThreshold |
|---|---|---|---|---|
| 快速 API | 1-2s | 30-50 | 10-15s | 5 |
| 普通服务 | 3-5s | 50 | 30s | 5-10 |
| 慢操作（如报表） | 10-30s | 50-60 | 60s | 3 |
- 禁忌：①timeout 留默认 10s（太长，失去保护）；②volumeThreshold 留默认 0（低调用量误判）；③errorThresholdPercentage 设太低（正常抖动就跳闸）。
三、事件清单
| 事件 | 触发时机 | 用途 |
|---|---|---|
fire | 发起一次调用 | 调用日志 |
success | 调用成功 | 成功计数 |
failure | 调用失败（业务异常） | 错误日志/告警 |
timeout | 调用超时 | 超时监控 |
reject | Open/Half-Open 时拒绝 | 熔断生效计数 |
open | Closed → Open | 熔断告警（下游故障） |
close | Half-Open → Closed | 恢复通知 |
halfOpen | Open → Half-Open | 试探开始 |
fallback | 触发降级 | 降级监控 |
semaphoreLocked | 并发达 maxCapacity | 限流计数 |
healthCheckFailed | 健康检查失败 | 下游探活失败 |
shutdown | 熔断器关闭 | 生命周期 |
四、容错模式对比
| 模式 | 解决问题 | 与熔断器关系 |
|---|---|---|
| 超时 | 单次调用无限等待 | 熔断器内部配超时，超时是失败依据之一 |
| 重试 | 瞬时失败提高成功率 | 熔断 Open 时停止重试（联动） |
| 限流 | 入口流量过载 | 与熔断方向不同（入口 vs 出口），互补 |
| 舱壁 | 资源被一个故障耗尽 | maxCapacity 是简化舱壁 |
| 降级 | 故障保业务可用 | 熔断器的 fallback 就是降级 |
五、Node.js 熔断器选型
| 库 | 状态 | 推荐 |
|---|---|---|
| Opossum | Red Hat 维护，活跃 | ✅ Node.js 事实标准 |
| circuit-breaker-js | 2013 年停更（12 年+） | ❌ 不要用 |
| cockatiel | 活跃，熔断+重试+舱壁 | 备选（功能更全） |
| opossum（Red Hat Build） | 企业版 | 企业场景首选 |
六、易错点清单
- 「熔断器能修复下游故障」：错。熔断器只是「症状治疗」——下游真挂了还得修，它只争取时间防级联，让上游活下来。
- 「熔断器 Open 就完全不调下游了」：对主路径而言是对的（Open 时直接 reject/fallback）。但 Half-Open 时会放一个请求试探——这是「调一次」的例外。
- 「volumeThreshold 留默认 0 没问题」：错。默认 0 意味着调 1 次失败（错误率 100%）就跳闸，正常抖动会误熔断。生产必设非零。
- 「fallback 成功就不算失败」：错。Opossum 里触发 fallback 仍计为失败（主路径没成功），错误率继续累积，直到 Closed 恢复主路径。
- 「熔断器和限流是一回事」：错。限流主动控制入口流量（防自己被过载），熔断被动反应下游故障（防自己被拖垮），方向不同。
- 「重试越多越好」：错。下游真挂时重试放大流量冲击下游（重试风暴）。要配熔断器联动——Open 时停止重试。
- 「timeout 设长一点更安全」：错。timeout 太长（如默认 10s）下游慢时上游资源被占满，失去保护。生产调小到秒级。
- 「Half-Open 立刻放全部流量」：错。Half-Open 只放一个请求试探——下游可能刚恢复还很脆弱，放全部会再打挂。
- 「circuit-breaker-js 和 Opossum 差不多」：错。circuit-breaker-js 已停更 12 年+，功能简陋、无人维护；Opossum 是 Red Hat 维护的活跃项目。新项目必选 Opossum。
- 「Opossum 能跨语言用」：错。Opossum 是 Node.js 库，跨语言不通。Java 用 Resilience4j、Go 用 sony/gobreaker——各自生态内选各自的标准。