如何通过 Lua 脚本在 Redis 中与 Java 逻辑结合实现高一致性分布式限流策略？

本文共计1080个文字，预计阅读时间需要5分钟。

Redis与Lua脚本结合使用，本身就能保证强一致性，Java只需安全调用，无需参与状态判断。限流逻辑必须在Lua中全部执行，任何在Java层先查后写的操作都会破坏原子性，直接导致泄漏或拒绝。

为什么不能在 Java 里做 if-else 判断是否超限

常见错误是 Java 先 stringRedisTemplate.opsForValue().get() 拿当前计数，再 if (count >= max) throw new RuntimeException()，最后才 incr()。这三步之间存在竞态窗口：多个请求可能同时读到旧值、同时判定未超限、同时写入，最终实际 QPS 翻倍。

• Redis 单线程执行 Lua，整个脚本内所有 redis.call() 是原子的
• Java 层的网络往返、本地计算、条件分支全在 Redis 外，天然非原子
• 哪怕用 pipeline 或事务（multi/exec）也无法替代 Lua —— 它们只保证命令序列不被穿插，不保证「读-算-写」逻辑不被并发干扰

EVAL 与 EVALSHA 的选择要点

生产环境必须用 EVALSHA，而非每次传完整 Lua 字符串。原因很实际：

• EVAL 每次发送脚本，增大网络包体积，尤其当脚本含注释或空格时更明显
• Redis 会缓存已执行过的 Lua 脚本 SHA1 值，EVALSHA 只传 40 字符哈希，带宽和解析开销都更低
• 首次调用需先 SCRIPT LOAD 注册脚本，否则 EVALSHA 返回 NOSCRIPT 错误 —— 这个错误容易被忽略，导致限流完全失效
• Spring Data Redis 的 RedisTemplate.execute(RedisScript, …) 默认走 EVALSHA，但要求脚本对象已预热（即提前执行过一次 loadScript()）

令牌桶 Lua 脚本中几个关键参数含义

以典型令牌桶为例，KEYS[1] 是限流 key（如 "rate:uid:123"），ARGV 通常按顺序传入：

立即学习“Java免费学习笔记（深入）”；

• ARGV[1]：当前毫秒时间戳（System.currentTimeMillis()），用于计算令牌生成量
• ARGV[2]：桶容量（max_permits），比如 100
• ARGV[3]：令牌生成速率（rate），单位是「个/秒」，如 50 → 每 20ms 补 1 个
• ARGV[4]：本次申请令牌数（常为 1），支持批量获取，但多数场景固定为 1

注意：redis.call('TIME') 在 Redis 内部获取的是秒+微秒，但时区和精度不如客户端传入的 System.currentTimeMillis() 可控，且无法对齐业务系统时钟，容易引发漂移。

Java 调用时最容易被忽略的细节

不是脚本写得对就万事大吉，Java 层的几个配置点一错，强一致性立刻瓦解：

• StringRedisTemplate 的序列化器必须设为 StringRedisTemplate.setDefaultSerializer(new StringRedisSerializer())，否则 KEYS 和 ARGV 可能被转成乱码，Lua 里 tonumber(ARGV[1]) 返回 nil
• Lua 脚本返回值是 Long 类型（如 1 表示通过，0 表示拒绝），Java 接收时必须用 Long.class 做泛型，若误用 Integer.class 会抛 ClassCastException
• Redis 连接池配置要合理：max-active 过小会导致 EVAL 请求排队，看似限流生效，实则是连接瓶颈；timeout 过短会让正常脚本被中断，返回 RedisCommandTimeoutException
• 不要在 Lua 脚本里用 redis.log() —— 它不阻塞，但高频打日志会拖慢 Redis 主线程，且日志内容无法回传给 Java，调试时反而掩盖真实问题

真正难的从来不是写对一行 redis.call('zadd', ...)，而是让整个链路——从 Java 时钟、序列化、连接池，到 Redis 的 script cache 和 clock drift——全都对齐在同一个语义下。稍有偏差，「强一致」就只剩名字了。