Redis Lua脚本封装ZSET实现滑动窗口高精度限流

说到滑动窗口限流，绕不开 Lua 脚本——这并非锦上添花，而是底线要求。原因很简单：ZSet 的清理、统计、写入这三步操作，如果拆成多个 Redis 命令拼接，在高并发下必然翻车。先把这个结论摆在这儿，后面慢慢解释为什么。

为什么不能用多个 Redis 命令拼接实现滑动窗口

直接在应用层调用 ZREMRANGEBYSCORE、ZCARD、ZADD 三步操作，逻辑上看似没问题，但高并发下等着踩坑。两个请求几乎同时执行，都查到当前请求数为 99，都判断“没超限”，结果一起写入，变成了 101 次——这就是典型的竞态条件。

根子在于：ZSet 的清理、统计、写入不是原子的。网络延迟加上应用层调度间隙，让并发请求有机可乘。哪怕你在应用层加了本地锁，也只对单机有效，分布式环境照样崩溃。

• 固定窗口（INCR + EXPIRE）只能做到“每秒重置”，无法支持“任意 1 秒内”统计
• Pipeline 虽然能减少网络往返，但改不了多命令非原子的本质，仍然可能被其他客户端的命令插队
• 光靠 ZCOUNT 不清理旧数据，内存持续增长，早晚撑爆

EVAL 脚本中必须包含的三个核心操作

那么，一个能用的 Lua 脚本到底要干哪几件事？三件，一件不能少：

• 用 ZREMRANGEBYSCORE 清理窗口外数据：范围设为 0 到 now - window_ms，注意左闭右闭语义，避免边界时间点被重复计入两个窗口
• 用 ZCARD 获取当前窗口内请求数量：别绕弯子用 ZCOUNT 再算一次，ZCARD 更快、结果更确定
• 仅当未超限时，才用 ZADD 写入新请求：score 必须是毫秒级时间戳（比如 System.currentTimeMillis()），member 建议用唯一标识（UUID 或 req_+毫秒+随机数），避免 score 相同导致覆盖

核心代码长这样：

local windowStart = now - window
redis.call('ZREMRANGEBYSCORE', key, 0, windowStart)
local current = redis.call('ZCARD', key)
if current < threshold then
  redis.call('ZADD', key, now, requestId)
  redis.call('EXPIRE', key, math.ceil(window / 1000) + 1)
  return 1
else
  return 0
end

key 设计与过期策略的隐性陷阱

key 不是随便起的名字，它直接决定了限流粒度和内存安全。这里有几个要点千万注意：

• key 名一定要带上业务上下文，比如 rate:login:ip:192.168.1.100 或 rate:api:/order/create:uid:12345，避免不同资源共用同一个 key 导致误限
• 必须显式调用 EXPIRE 设置过期时间，否则空 ZSet 永远留在内存里。过期时间建议设为 window_ms / 1000 + 1 秒，比窗口稍微长一点，防止刚清空就过期，结果新请求一来又要重建
• 别指望 ZSet 自己会“自动过期”——它不会自动删空 key，得靠 EXPIRE 老老实实地控制生命周期

漏掉 EXPIRE 是线上最容易踩的坑之一：ZSet 看上去没数据（ZCARD 返回 0），但 key 本身还占着内存，积少成多直接拖垮 Redis。这不是危言耸听。

Java 中调用 Lua 脚本的最小可行封装

Spring Boot 项目里，别手写 EVAL 字符串拼接了，用 DefaultRedisScript 封装一次，到处复用：

• 把脚本文件（sliding_window.lua）放在 resources/ 下，内容保持纯 Lua，不带 Java 变量插值
• 声明 DefaultRedisScript bean，resultType 设为 Long.class，因为返回值就是 1 或 0
• 调用时传入 KEYS[1]（key）、ARGV[1]（当前毫秒时间戳）、ARGV[2]（窗口毫秒数）、ARGV[3]（阈值）、ARGV[4]（requestId）

调用代码大概长这样：

redisTemplate.execute(limitScript,
    Collections.singletonList(key),
    String.valueOf(now),
    String.valueOf(windowMs),
    String.valueOf(maxCount),
    requestId);

注意：now 必须由应用层传入（而不是在 Lua 里用 redis.call("TIME")），否则各节点系统时间不一致会导致窗口漂移。这个细节很多人忽略，等到出问题才后悔。

说到底，真正难的从来不是写对那几行 Lua，而是想清楚 key 怎么分、时间戳谁来提供、过期时间设多长、member 怎么防冲突——这些细节不抠准，脚本再漂亮，上线就是事故。