应使用 sony/gobreaker 而非已归档的 hystrix-go；每个第三方 api 需独立 circuitbreaker 实例，避免故障扩散；需正确配置 requestvolumethreshold、超时与 context 透传，并手动处理 fallback 与可观测性。

直接用 sony/gobreaker，别碰 hystrix-go——它已归档、原子计数有竞态、不支持 context，2026 年生产环境踩坑率极高。

每个第三方 API 必须配独立 gobreaker.CircuitBreaker 实例

复用一个实例包多个依赖（比如 user-api 和 payment-api 共用同一个 breaker），等于把故障面拉平：A 接口挂了，B 接口的调用也被拦住。这不是熔断，是误杀。

• 初始化方式：存在包级变量，或注入到 client 结构体里，例如 type UserClient struct { cb *gobreaker.CircuitBreaker }
• 禁止在函数内调用 gobreaker.NewCircuitBreaker——每次都新建 = 每次都从零统计，熔断失效
• 配置中 RequestVolumeThreshold 建议设为 6～10；太小易误熔，太大响应迟钝

cb.Execute 的 fallback 不是自动触发的降级入口

很多人以为只要传了 fallback 函数，熔断或超时就会走它。实际只在两种情况触发：gobreaker.ErrOpenState（熔断器处于 Open）或主函数 panic。主函数返回 error（比如网络超时、5xx）不会进 fallback，但会记为失败。

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

• 正确写法：显式捕获 err == gobreaker.ErrOpenState，再手动调用降级逻辑
• fallback 函数本身不能发 HTTP、查 DB、调其他 breaker，必须快、无副作用、不 panic
• HTTP 场景下，fallback 返回的 *http.Response 必须带非 nil 的 Body 字段，否则上层 io.Copy 会 panic

超时必须由 context.WithTimeout 控制，且 HTTP 超时应比 breaker.Timeout 短 20%～30%

gobreaker.Settings.Timeout 是熔断器等待 Execute 内部函数返回的最大时长，不是请求超时。它不中断底层 HTTP 连接，goroutine 会一直挂着直到真正完成或被系统 kill。

• 所有 http.Client.Do 必须传入带超时的 ctx，例如 ctx, cancel := context.WithTimeout(req.Context(), 800*time.Millisecond)
• 建议设置：HTTP 超时 800ms，breaker.Timeout 设为 1.2s，确保多数失败由超时捕获，而非填满窗口才响应
• 漏掉 ctx 透传，会导致连接堆积、goroutine 泄漏、长尾请求拖垮整个 handler

可观测性只能靠 OnStateChange 手动埋点

gobreaker 没内置 metrics，也没有 WithMetrics 选项。Prometheus 或 Datadog 接入全靠你监听 OnStateChange 回调，并用原子变量维护瞬时指标（当前请求数、失败率、Open 次数等）。

• 暴露 /health/circuit 接口，返回各 breaker 的 State()、Counts() 和最近切换时间
• 别只记录状态切换事件，却没同步更新成功率、被拒绝数等关键瞬时值
• 常见错误：在 OnStateChange 中做阻塞操作（如发 HTTP 告警），导致主流程卡顿

最易被忽略的是降级数据的业务有效性——缓存过期、结构体字段变更、空 Body 导致 panic，这些都不会在单元测试里暴露，只会在真实流量中突然炸开。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！