需自定义@SLA注解实现限流：先声明带Target::METHOD的Annotation类并继承AbstractAnnotation，再在config/autoload/annotations.php中注册命名空间；切面通过getAnnotation提取注解，动态构造Redis key调用RateLimiter::attempt，注意处理空值、类型转换及Redis异常降级。
Hyperf里怎么写一个@SLA注解来限流
Hyperf本身不带@SLA这种注解，得自己定义。核心是两步：声明注解类 + 注册到容器扫描范围。注解类必须加@Annotation和@Target，且目标得包含Target::METHOD——因为SLA控制通常按接口维度生效。
常见错误是忘了在composer.json的autoload.annotation里加路径，导致注解不被扫描；或者用了Target::CLASS但切面只拦截方法，结果注解根本没生效。
- 注解类需继承
AbstractAnnotation，字段如qps、timeout用public $xxx声明，不能用private - 必须在
config/autoload/annotations.php中把注解所在命名空间加入scan列表，否则AspectContainer找不到它 - 如果想支持类+方法两级配置（比如类设默认QPS，方法覆写），注解里加
inherit字段，并在切面里手动合并逻辑
切面里怎么拿到@SLA注解并触发限流
切面类要实现AbstractAspect，$classes属性填目标控制器命名空间，$annotations填['SLA']。关键在process方法里用$annotation = $this->getAnnotation($proceedingJoinPoint, SLA::class)提取注解实例。
别直接用$proceedingJoinPoint->getMethod()->getDocComment()去手动解析，Hyperf的注解解析器已经做了缓存和类型转换，重复解析既慢又容易漏掉@var或嵌套结构。
-
getAnnotation返回null时，说明该方法没打@SLA，按需跳过或走默认策略 - 注解字段值默认是字符串，
qps = "10"得自己(int)$annotation->qps，不然传给限流器会报类型错误 - 建议在切面里加
if (empty($annotation->qps)) return $proceedingJoinPoint->process();，避免零值误触发限流
用RateLimiter还是自己封装Redis Lua脚本
Hyperf自带的RateLimiter组件基于Redis，底层调的是redis.eval执行Lua，能保证原子性，够用。但要注意它的key生成规则是rate_limiter:{name}:{ip}，而SLA场景往往要按用户ID、设备号甚至业务单号区分，不是单纯按IP。
这时候就得改key构造逻辑。别硬改组件源码，应该在切面里动态拼$key = sprintf('sla:%s:%s', $annotation->name ?? 'default', $userId)，再传给RateLimiter::attempt($key, $maxAttempts, $decaySeconds)。
- 如果
$userId来自Header或Token，记得提前做非空校验，空值会导致所有请求打到同一个key上，集体被限 - Redis连接超时或失败时，
RateLimiter::attempt抛RedisException，切面里得try/catch并决定是放行还是拒绝——线上一般选择“降级放行”，避免Redis抖动拖垮整个服务 - 别用
sleep()或usleep()模拟等待，Hyperf是协程环境，会阻塞整个协程调度
为什么@SLA(timeout=500)没让接口超时就返回
timeout参数在这里不是HTTP超时，而是指“限流窗口内允许的最大等待毫秒数”——即当当前QPS已满，新请求愿意排队等多久。Hyperf的RateLimiter不原生支持排队等待，它只做“通过/拒绝”二值判断。
真要实现带等待的SLA，得自己补逻辑：先attempt，失败后用Redis::zRangeByScore查当前窗口内最早请求时间，算出还需等多久，再go协程co::sleep对应时长（注意单位换算）。但这会增加延迟不确定性，多数业务其实只需要快速失败。
- 如果注解写了
timeout=500但没生效，大概率是切面里压根没读这个字段，或者读了但没集成到限流决策分支中 - Hyperf 3.x 的
RateLimiter新增了remaining和reset_in返回值，可以用来构造更精细的响应头（如X-RateLimit-Reset），但需要手动解析attempt返回的数组 - SLA里的
timeout语义容易和Swoole的http_client超时混淆，命名建议改成wait_ms或queue_timeout更准确
SLA限流真正的复杂点不在注解或切面，而在“如何定义一个请求的唯一身份”。IP不可靠，Token可能未解析，用户ID可能为空——这些边界情况不处理好，限流就变成随机丢包。
