必须用Lua脚本实现令牌桶，因其在Redis单线程中执行可保证“读-判-写”原子性，避免客户端多请求并发导致的竞态超卖；所有操作须封装于单次EVAL/EVALSHA调用中。
为什么必须用 Lua 脚本实现令牌桶，而不是客户端计算
Redis 单线程执行 Lua 脚本的原子性，是高并发下限流不超卖的核心保障。如果在客户端算好时间、查 key、判断、再 set，中间必然存在竞态——多个请求同时读到剩余令牌为 1，全部放行。Lua 在服务端一次性完成「读令牌数 + 判断 + 更新 + 返回结果」，彻底规避这个问题。
常见错误现象：INCR 配合 EXPIRE 手动模拟漏桶，但没加锁或没用 Lua，压测时 QPS 轻松突破阈值 2–3 倍。
- 所有操作必须封装在一个
EVAL或EVALSHA调用中 - 不要在 Lua 里调用
redis.call("TIME")—— 它返回的是 Redis 服务器本地时间（秒级），精度不够；改用redis.call("TIME")返回两个整数（秒+微秒），或更推荐直接用ARGV[3]传入客户端毫秒时间戳（由调用方保证时钟一致） - 脚本内避免使用
for循环做大量计算，会阻塞 Redis 主线程
令牌桶 Lua 脚本的关键参数与逻辑拆解
一个生产可用的令牌桶脚本至少要接收 4 个参数：KEYS[1]（桶名）、ARGV[1]（最大容量）、ARGV[2]（每秒补充令牌数）、ARGV[3]（当前毫秒时间戳）。脚本需完成：读旧状态 → 计算应新增令牌 → 截断上限 → 判断是否够用 → 更新并返回结果。
示例核心逻辑（精简版）：
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local rate = tonumber(ARGV[2])
local now_ms = tonumber(ARGV[3])
<p>local bucket = redis.call("HMGET", key, "last_ms", "tokens")
local last_ms = tonumber(bucket[1]) or now_ms
local tokens = tonumber(bucket[2]) or capacity</p><p>-- 计算已过去时间（秒），换算应添加令牌数
local delta_sec = math.max(0, (now_ms - last_ms) / 1000.0)
local new_tokens = math.min(capacity, tokens + delta_sec * rate)</p><p>-- 判断是否允许请求
local allowed = (new_tokens >= 1) and 1 or 0
if allowed == 1 then
new_tokens = new_tokens - 1
end</p><p>-- 写回：更新令牌数和最后时间
redis.call("HMSET", key, "tokens", new_tokens, "last_ms", now_ms)
redis.call("PEXPIRE", key, 60000) -- 自动过期，避免冷 key 残留
return { allowed, math.floor(new_tokens) }</p>注意：PEXPIRE 时间设为远大于预期桶生命周期（如 60 秒），不是“每秒重置”，而是“长期有效但有兜底”；否则频繁过期/重建 key 会引发性能抖动。
Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。
Java 中调用该脚本的典型写法（Lettuce 客户端）
别把 Lua 脚本硬编码在 Java 字符串里——维护困难且无法复用 SHA。应预加载脚本并缓存其 SHA 值，后续用 EVALSHA 调用，降低网络和解析开销。
- 首次加载：用
redisClient.eval(script, ScriptOutputType.MULTI)获取 SHA，存入静态变量或配置中心 - 日常调用：用
redisClient.evalSha(sha, ScriptOutputType.MULTI, keys, args) -
args必须是字符串数组，数值要String.valueOf(...)转换，否则 Lettuce 会序列化失败 - 务必设置超时：
TimeoutOptions.enabled(Duration.ofMillis(50))，防止 Lua 卡死拖垮整个连接池
容易踩的坑：HMGET 返回 nil 时，Lua 的 tonumber(nil) 是 nil，后续计算会报错。必须显式判空，如 tonumber(bucket[1]) or now_ms。
压测时令牌数异常归零或突增的根本原因
这不是脚本 bug，大概率是客户端时间不同步或调用方传入的 ARGV[3] 时间戳混乱。比如 Docker 容器未启用 host.time 共享、K8s 节点时钟漂移、或前端 JS 取 Date.now() 后经多层代理延迟送达。
解决方案很直接：
- 强制所有服务端节点开启 NTP 同步，并监控时钟偏移（
ntpq -p） - 限流脚本中弃用客户端传的时间，改用
redis.call("TIME")（返回秒+微秒数组），再换算成毫秒：(time_arr[1] * 1000 + math.floor(time_arr[2] / 1000)) - 若必须用客户端时间（如需对齐业务日志时间线），增加校验：若传入时间比 Redis 当前时间早 >5s 或晚 >1s，直接拒绝并返回错误码
真正难调试的是跨机房部署时的时钟误差——哪怕只有 100ms 偏移，在 1000 QPS 下就可能造成 10% 以上的误判率。这事没法靠代码绕过，得从基础设施层面卡死。
