说到滑动窗口限流，绕不开 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 变量插值 - 声明
DefaultRedisScriptbean，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 怎么防冲突——这些细节不抠准，脚本再漂亮，上线就是事故。
