Hyperf熔断器不会自动生效，必须同时启用hyperf/circuit-breaker、hyperf/load-balancer和hyperf/service-governance（如Nacos），且仅对RPC或Guzzle标准客户端调用有效；@CircuitBreaker注解仅作用于RPC接口方法（需@RpcService标记），非Controller方法，fallback类须无参构造且签名一致，failureThreshold指连续失败次数，stat_window与sleep_window共同控制恢复节奏。
Hyperf 的熔断器组件不会自动生效，装了 hyperf/circuit-breaker 也不代表能防雪崩——它必须和 hyperf/load-balancer、hyperf/service-governance（如 hyperf/service-governance-nacos）联动，且只对 RPC 或 Guzzle 标准客户端调用起作用。
为什么加了 @CircuitBreaker 注解却没熔断？
常见现象：RPC 接口抛异常，fallback 类没执行，日志里也看不到熔断状态变更。根本原因不是注解写错了，而是整个链路缺失支撑：
-
@CircuitBreaker只作用于Hyperf\Rpc\Client或Hyperf\Guzzle\ClientFactory发起的调用，直接用curl、file_get_contents或原生PDO不会触发任何统计 - 熔断器依赖
hyperf/load-balancer提供的节点健康快照和失败计数，没启用该组件，reportFailure()就是空操作 - 服务实例的上下线、健康状态需由
hyperf/service-governance（比如 Nacos 驱动）上报并同步，否则熔断器连“下游是谁”都不知道 - Controller 方法上加注解无效——必须加在 RPC 接口的 Service 类方法上，且该类需被
@RpcService标记
熔断器启用的三步硬性配置
缺一不可，顺序也不能错：
- 安装必要组件：
composer require hyperf/circuit-breaker hyperf/load-balancer hyperf/service-governance-nacos（注意不是hyperf/nacos） - 启用服务治理与负载均衡：在
config/autoload/services.php中确保'enable' => ['register' => true, 'discovery' => true]，且'drivers' => ['nacos' => [...]]配置正确（host/port/username/password 必须和 Nacos 实例一致） - RPC 调用走标准路径：Consumer 端用
$this->client->send($request)，不要自己 new GuzzleHttp\Client；Provider 端方法必须带@CircuitBreaker(failureThreshold=3, timeout=2000)，timeout单位是毫秒，别写成秒
failureThreshold 和 fallback 容易踩的坑
这个参数不是“总失败次数”，而是“连续失败次数”：
- 设
failureThreshold=5意味着同一节点连续 5 次调用都失败（网络超时、连接拒绝等），才会熔断；中间只要成功一次，计数就归零 -
fallback类必须是无参构造、独立存在（不能是匿名类或闭包），且方法签名要和原方法完全一致，包括返回类型声明 - 限流导致的
RateLimitException和真实服务故障混在一起统计，会导致误熔断——建议在handle()里区分异常类型，只对ConnectException、RequestTimeoutException调用reportFailure() - 熔断后默认不自动恢复，得靠
stat_window（滑动窗口时间）+sleep_window（休眠期）组合控制；生产环境建议stat_window=60000（1分钟），sleep_window=30000（30秒）
真正防雪崩的关键不在熔断器本身，而在于它能否准确感知下游节点的真实健康度——如果服务注册没通、负载均衡没启、调用没走标准客户端，那再细的 failureThreshold 都只是摆设。
