Hyperf 的熔断器需满足四大前提才生效：启用 hyperf/service-governance（如 Nacos）、hyperf/load-balancer、使用 RPC 或 Guzzle 标准客户端调用、且 @CircuitBreaker 注解仅作用于 RPC 接口方法，非 Controller 方法；fallback 必须为无参构造的独立类，配置中 stat_window、ephemeral 和超时参数须合理设置。
Hyperf 本身不内置熔断器，hyperf/circuit-breaker 是官方提供的可选组件，但默认未启用，且必须配合 hyperf/load-balancer 和服务治理（如 Nacos）才能生效；单纯在 Controller 里加注解或配置 fallback，不会触发熔断逻辑。
Hyperf 中 circuit-breaker 组件的启用前提
很多人以为装了 hyperf/circuit-breaker 就能自动熔断，结果发现调用失败时既没跳 fallback，也没记录熔断状态——根本原因是缺少依赖链路支撑：
-
hyperf/service-governance（或具体实现如hyperf/service-governance-nacos）必须启用，否则无法识别下游服务实例健康状态 -
hyperf/load-balancer必须启用，因为熔断器依赖其提供的Node管理和故障统计能力 - 服务调用必须走
Hyperf\Rpc\Client或Hyperf\Guzzle\ClientFactory的标准客户端（非原生curl或file_get_contents） -
hyperf/circuit-breaker的配置项（如failure_threshold、sleep_window）只对通过ClientInterface发起的 RPC 调用生效
@CircuitBreaker 注解在什么场景下才真正起作用
这个注解常被误用于 HTTP Controller 方法上，但它实际只对 RPC 客户端接口方法有效。例如：
interface UserServiceInterface
{
#[CircuitBreaker(failureThreshold: 3, sleepWindow: 30)]
public function getUser(int $id): array;
}
此时熔断行为发生在调用方（Consumer）侧，由 hyperf/rpc-client 拦截并执行状态机判断。如果直接在 Controller 里写：
#[CircuitBreaker(...)]
public function index() { ... }
——这不会触发任何熔断逻辑，因为没有下游服务调用上下文，只是个空壳注解。
常见错误现象：Call to undefined method Hyperf\CircuitBreaker\Annotation\CircuitBreaker::getFallback()，说明你试图在非 RPC 接口方法上使用它，或未正确注册 Fallback 类。
降级 fallback 的两种写法与兼容性差异
Hyperf 支持两种 fallback 实现方式，但行为和适用范围完全不同：
-
RPC 接口级 fallback：必须定义独立的 Fallback 类，实现对应接口，并在
@CircuitBreaker中指定fallback属性。该类会在熔断打开或调用失败时被实例化并调用同名方法 -
HTTP 请求级 fallback：仅适用于
Hyperf\Guzzle\ClientFactory创建的客户端，需手动在try/catch中捕获ConnectException、RequestException，然后返回默认值。Hyperf 不提供自动 HTTP fallback 注解
注意：hyperf/circuit-breaker 的 fallback 类必须是无参构造、public 方法，且不能依赖注入其他协程上下文敏感对象（如 RequestInterface），否则在熔断态下会因上下文丢失而报错。
生产环境容易忽略的三个配置细节
即使组件装全、注解写对，以下三点仍会导致熔断失效或误判：
-
config/autoload/circuit-breaker.php中的stat_window（统计窗口，默认 60 秒）若设得太短（如 5 秒），在低频调用场景下可能永远凑不够失败次数，导致熔断不触发 - Nacos 实例的
ephemeral配置为false（持久化实例）时，服务下线不会被及时感知，熔断器仍会尝试向已宕机节点发请求，造成“假熔断” - 使用
Hyperf\Guzzle\ClientFactory时，若未设置timeout和connect_timeout，网络超时可能长达 30 秒以上，单次失败耗时过长，拉低错误率统计精度，使熔断阈值难以达到
真正的高可用不是堆配置，而是让熔断器能在 2–3 次连续失败后快速响应，同时 fallback 返回的数据结构必须与主逻辑完全一致——这点在接口变更时最容易被绕过测试。
