Hyperf 3.1 中滑动窗口限流需借助 Redis ZSET 实现，通过 ZADD 记录毫秒级时间戳、ZCOUNT 统计有效请求数，并用 Lua 脚本保障原子性；多实例一致性依赖统一 Redis、严格时间同步（NTP）、合理 key 粒度及原子操作。
Hyperf 3.1 中实现滑动窗口限流并支持多实例分布式部署，关键在于两点：一是算法逻辑要能精确统计“最近 N 秒内”的请求数，二是所有实例必须共享同一份时间窗口状态——这只能靠外部存储（如 Redis）来保证一致性。
滑动窗口在 Hyperf 3.1 中怎么落地
Hyperf 官方 hyperf/rate-limit 组件默认使用的是固定窗口算法，不直接支持滑动窗口。要启用滑动窗口，需自行实现或借助第三方扩展（如 pudongping/hyperf-throttle-requests），它底层基于 Redis 的 ZSET 或 Sorted Set 实现时间分片计数。
核心思路是：每个请求记录一个毫秒级时间戳（如 ZADD key timestamp timestamp），然后用 ZCOUNT key (now - window) now 统计有效请求数。窗口大小（如 60 秒）、时间精度（毫秒/秒）、过期策略（ZREMRANGEBYSCORE）都由代码控制。
注意：Hyperf 3.1 的容器和 AOP 机制让这类自定义限流器很容易注入到中间件链路中，无需修改业务代码。
多实例下如何保证滑动窗口全局一致
多个 Hyperf 实例共用同一个 Redis 实例（或集群）时，只要 key 命名规则统一、时间戳来源可靠，滑动窗口天然就是分布式的。但有三个细节必须处理好：
- 时间同步必须严格：所有应用服务器和 Redis 服务端的系统时间偏差应控制在 100ms 内。建议统一启用 NTP 服务，否则时间滞后会导致窗口统计偏少（误放行），时间超前则导致统计偏多（误拦截）。
-
key 的粒度要合理：比如按
throttle:ip:{client_ip}或throttle:uri:{path}:{user_id}构建 key，避免全局限流成为瓶颈，也防止不同维度请求互相干扰。 -
Redis 命令要原子执行：ZADD + ZCOUNT + ZREMRANGEBYSCORE 这套操作不能拆成多次调用。推荐封装为 Lua 脚本一次性提交，避免并发场景下窗口数据错乱。Hyperf 的
Redis::eval可直接支持。
配置与上线前的关键检查项
在 config/autoload/hyperf-throttle-requests.php 中，重点关注这几个参数：
-
decaySeconds：设为滑动窗口总时长（如 60），不是固定窗口长度； -
storage：确认使用RedisStorage，且连接的是共享 Redis 实例； -
generateKeyCallable：务必根据实际限流维度重写，例如区分用户登录态或 API 分组； -
tooManyAttemptsCallback：建议返回标准 HTTP 429 响应，并带上Retry-After头，方便前端友好降级。
上线前建议用 ab 或 wrk 模拟跨实例请求，验证相同 key 在不同节点触发限流的阈值是否一致，再观察 Redis 中 ZSET 的成员数量和分数范围是否符合预期时间窗口。
为什么不直接用令牌桶替代滑动窗口
令牌桶更适合控制“平均速率 + 突发容量”，而滑动窗口更擅长精准回答“过去 60 秒到底来了多少次请求”。如果你的业务强依赖实时统计数据（比如风控判断短时高频行为、运营监控瞬时热度），滑动窗口不可替代。但要注意：它的内存和 CPU 开销略高，QPS 超过 5 万时建议用分层时间窗口优化（如 60 个 1 秒槽位 + 1 个 60 秒汇总），Hyperf 配合 Lua 脚本可平滑支持。
