Hyperf中限流与熔断需分离配置存储且不可混用同一Redis实例；@RateLimit注解无法触发熔断统计，须手动调用RateLimiterInterface并区分上报限流失败与业务异常，避免熔断误判。
Hyperf 默认的 hyperf/rate-limit 组件只做限流，不带熔断能力；要实现「限流 + 熔断」组合保护，必须手动桥接 hyperf/circuit-breaker，且两者不能共用同一组存储后端（比如 Redis）而不加隔离，否则会互相干扰。
限流器和熔断器必须分开配置存储
很多人直接把 rate_limit 和 circuit_breaker 都配成同一个 Redis 连接，结果发现限流计数异常、熔断状态错乱——根本原因是两个组件对 Redis key 的使用逻辑不同，且都依赖原子操作，混用会竞争 key 或覆盖 TTL。
-
rate_limit默认使用rate_limit:{name}:{key}存储滑动窗口计数，依赖INCR+EXPIRE -
circuit_breaker使用circuit_breaker:{name}:state和circuit_breaker:{name}:metrics，依赖HSET+EXPIRE，且内部有状态机轮转逻辑 - 建议：限流走一个 Redis DB（如 db 1），熔断走另一个（如 db 2），或至少用不同前缀 + 不同连接池
@RateLimit 注解无法触发熔断，需手动包装调用
@RateLimit 是个前置拦截器，失败时直接抛 RateLimitException，根本不会进入业务方法体，自然也没机会让熔断器统计失败次数。想让「超限请求也参与熔断统计」，得绕过注解，改用 RateLimiterInterface 手动判断 + 显式上报。
- 不要这样写：
@RateLimit(limit=100, interval=60) public function handle() { ... } - 应该这样写：
public function handle() { $result = $this->rateLimiter->acquire('api:submit', 100, 60); if (!$result->isAvailable()) { // 此处可手动调用熔断器 reportFailure() $this->circuitBreaker->reportFailure('api_submit'); throw new RateLimitException(); } try { $res = $this->doRealWork(); $this->circuitBreaker->reportSuccess('api_submit'); return $res; } catch (\Throwable $e) { $this->circuitBreaker->reportFailure('api_submit'); throw $e; } }
熔断器的 failureThreshold 值容易设错
默认 failureThreshold=5 是指「连续失败 5 次」才熔断，但实际生产中，限流导致的 RateLimitException 和业务异常（如 DB 超时）应区别对待——前者是可控拒绝，后者才是服务真实不可用。混在一起统计会让熔断过于敏感。
- 推荐做法：为限流失败单独打标，
reportFailure('api_submit:rate_limited')，再在熔断器配置里为该 key 设置更高阈值或忽略它 - 或者自定义
CircuitBreaker实现，在reportFailure中过滤掉RateLimitException子类 - 注意：
hyperf/circuit-breaker的failureThreshold是 per-key 的，不是全局值，别在 config.php 里误配成数字数组
真正难的不是集成两个组件，而是厘清「谁该在什么时机记录什么失败」——限流是守门员，熔断是急救员，守门员拦下的球，不该算进急救员的抢救失败统计里。
