1. 从“为什么”开始Lua脚本在Redis中的核心价值如果你用过Redis大概率写过这样的业务逻辑先GET一个计数器判断是否超过阈值如果没超过再INCR。这在客户端看来是两步操作但在高并发下这两步操作之间可能被其他客户端的请求插入导致计数不准确。为了解决这类问题Redis从2.6版本开始内置了Lua脚本引擎。简单说它允许你将多个Redis命令打包成一个脚本在服务器端原子性地执行。这不仅仅是“把命令打包”它彻底改变了我们使用Redis的方式从单纯的数据存储变成了一个可编程的、具备事务能力的计算节点。原子性是其最闪耀的光环。在Lua脚本执行期间整个脚本会被当作一个命令服务器不会处理其他任何命令这完美解决了上述的竞态条件问题。其次它减少了网络开销。原本需要多次往返Round-Trip的多个命令现在只需发送一次脚本和一次结果对于延迟敏感的应用提升显著。最后它带来了逻辑的封装与复用。你可以把复杂的业务校验、计算逻辑固化在服务器端的一个脚本里客户端只需调用一个简单的EVAL或EVALSHA命令降低了客户端的复杂度也保证了逻辑的一致性。但别急着欢呼Lua脚本也是一把双刃剑。用得不好它可能成为整个系统的“血栓”——一个写坏了的脚本可能会长时间阻塞整个Redis实例导致所有请求超时。因此深入理解Lua脚本的每一个细节从编写、调试到运维是每个资深Redis使用者必须掌握的技能。这篇教程我将结合多年踩坑经验带你从入门到精通不止于语法更聚焦于生产环境下的实战要点和避坑指南。2. 脚本编写基础语法、密钥与参数编写Redis Lua脚本你首先得知道它能做什么。脚本中你可以使用几乎全部的Redis命令通过redis.call()或redis.pcall()来调用。两者的区别至关重要call()在执行命令出错时会直接抛出Lua错误导致脚本停止而pcall()则会以Lua表的形式捕获错误允许脚本继续执行并做错误处理。在绝大多数需要严格原子性和一致性的场景比如扣库存你应该使用redis.call()确保任何命令失败都导致整个脚本回滚。只有在某些非核心命令失败你仍希望脚本继续时比如记录日志到另一个不关键的Key才考虑pcall()。2.1 密钥KEYS与参数ARGV的规范这是新手最容易栽跟头的地方。在EVAL命令中你需要显式地传递脚本中用到的所有Redis键名和普通参数。EVAL “return {KEYS[1], ARGV[1]}” 1 mykey hello这里的1表示后面紧跟的1个参数是键名mykey它会被放入Lua脚本的KEYS全局数组中。之后的参数hello则放入ARGV数组。为什么非要分开这关系到Redis集群Cluster的运作。集群模式下Redis需要根据键名来计算这个脚本应该被路由到哪个槽位slot的节点上执行。如果你把所有变量都塞进ARGV对于不操作任何键的脚本是可行的但一旦操作了键集群就无法正确路由脚本会报错。因此一个必须遵守的规范是所有在脚本中会被redis.call操作的键名都必须通过KEYS数组传递并且数量必须在EVAL命令中声明准确。一个常见的反模式是动态拼接键名比如local userKey ‘user:’ .. ARGV[1]; redis.call(‘SET’, userKey, ARGV[2])。这在单机Redis上能跑但在集群模式下由于键名userKey没有出现在KEYS数组中脚本可能会被发送到错误的节点执行导致“-CROSSSLOT”错误。正确的做法是如果键名模式固定应将前缀也放入KEYS如果完全动态则意味着你的数据模型可能不适合在集群下使用此类脚本。2.2 Lua数据类型与Redis的转换Lua和Redis有各自的数据类型系统它们之间的自动转换需要了然于胸。当Redis命令的结果返回到Lua中时Redis的整数回复如INCR的结果会被转换为Lua的number类型浮点数。但要注意Lua number是浮点型超大整数可能会损失精度。Redis的批量字符串回复GET到的字符串被转换为Luastring。Redis的多条批量回复LRANGE列表被转换为Luatable数组。Redis的状态回复OK和错误回复会被转换为Luatable结构比较特殊通常你需要检查返回值的err字段。反过来当Lua脚本返回值给客户端时Luanumber会被转换为Redis的整数回复。但如果这个number是浮点数如3.14Redis会先将其转换为字符串“3.14”然后作为批量字符串回复返回。这里有个大坑redis.call(‘GET’, ‘counter’)返回的可能是Lua string “5”而tonumber()转换后做计算再返回一个Lua number 6。客户端收到的可能是整数6也可能是字符串“6”取决于Lua number是否是整数。为了结果一致性我习惯在脚本最后显式使用tostring()或tonumber()进行格式化。3. 脚本管理实战加载、缓存与持久化没人会每次执行都发送一遍完整的脚本字符串那太浪费网络带宽了。Redis提供了SCRIPT LOAD命令它会计算脚本的SHA1校验和并缓存脚本返回该SHA1值。之后你就可以用EVALSHA sha1 numkeys key [key …] arg [arg …]来执行它效果和EVAL完全一样。3.1 客户端的最佳实践容错与加载在生产环境中直接调用EVALSHA可能会遇到“NOSCRIPT”错误因为脚本可能未被加载或已被Redis清除如执行了SCRIPT FLUSH。因此一个健壮的客户端调用模式应该是def execute_script(script_sha, keys, args): try: return redis.evalsha(script_sha, len(keys), *(keys args)) except redis.exceptions.NoScriptError: # 脚本不存在重新加载 script_content load_script_from_disk(‘my_script.lua’) redis.script_load(script_content) # 重试一次 return redis.evalsha(script_sha, len(keys), *(keys args))更高级的做法是在应用启动时或通过配置中心统一预加载所有需要的脚本到Redis中。对于集群模式你需要确保脚本在所有相关主节点上都被加载因为脚本的缓存是节点级别的。3.2 脚本的版本控制与持久化脚本本身也是代码需要版本管理。我推荐的做法是将Lua脚本作为资源文件存储在项目的资源目录如resources/scripts/中并用有意义的文件名命名deduct_inventory.lua。在构建或部署流程中计算脚本的SHA1可以使用sha1sum命令并将其作为配置项或常量写入客户端代码。这样客户端代码里引用的是固定的SHA1与具体的脚本内容解耦。部署时通过初始化脚本或启动流程将新版脚本SCRIPT LOAD到Redis。如果SHA1与之前不同自然就完成了“更新”。由于旧客户端可能还在用旧的SHA1所以脚本变更应该是向后兼容的或者需要配合客户端灰度发布。千万不要把Lua脚本字符串硬编码在业务代码里那会给维护和调试带来噩梦。4. 性能与阻塞脚本执行的黑暗面这是Lua脚本最需要警惕的部分。Redis是单线程的Lua脚本会在这个线程中运行直到完成。这意味着一个执行缓慢的脚本会阻塞整个实例所有其他请求都会排队等待超时进而可能引发雪崩。4.1 哪些操作会让脚本变慢循环中的大量数据操作在Lua里用for循环遍历一个包含十万个元素的KEYS并对每个元素调用redis.call(‘HGET’, …)。这相当于在Redis单线程里串行执行十万个命令阻塞时间可想而知。执行时间复杂度高的Redis命令在脚本中执行KEYS *、HGETALL在一个巨大的哈希上、LRANGE 0 -1在一个超长列表上。复杂的Lua计算虽然Lua计算本身不涉及Redis但CPU密集型的运算如加密解密、复杂字符串处理同样会长时间占用线程。4.2 监控与规避SCRIPT KILL和SHUTDOWN NOSAVERedis提供了两个救命稻草但都有严格条件SCRIPT KILL只能杀死还未执行过任何写命令的脚本。如果一个脚本已经修改了数据SCRIPT KILL会失败因为Redis无法确定部分执行的状态回滚成本太高。所以这只对纯读的慢脚本有效。SHUTDOWN NOSAVE这是最后的“拔电源”手段。它会强制关闭Redis且不保存数据。这意味着你会丢失最后一次快照RDB之后的所有数据。除非情况万分危急否则不要使用。因此根本之道在于预防对脚本进行性能评估在测试环境用DEBUG SCRIPT相关命令或 simply 用TIME命令测量脚本执行时间。明确脚本的时间复杂度。使用redis.set_repl()和redis.breakpoint()Redis 5.0进行调试虽然生产环境不能用但在测试时你可以用redis.set_repl(redis.REPL_NONE)让脚本的写命令不生效然后用redis.breakpoint()设置断点通过redis-cli –ldb进行单步调试观察脚本行为。设置lua-time-limit在redis.conf中默认是5秒。超过这个时间Redis会开始接受其他客户端的SCRIPT KILL和SHUTDOWN命令。但注意这只是一个检测机制脚本本身并不会自动停止它只是给了你一个干预的机会窗口。分解大脚本如果逻辑允许将一个大脚本拆分成多个原子性小脚本。或者考虑是否真的需要原子性有时用WATCH/MULTI/EXEC事务或者利用Redis的原子命令如INCRBY、HSETNX组合也能达到目的且更安全。5. 调试与运维让脚本无所遁形再严谨的开发也离不开调试。除了上面提到的redis-cli –ldbLua Debugger交互式调试外还有一些运维层面的技巧。5.1 日志与错误追踪在脚本中你不能直接使用print但可以通过redis.log()函数将日志写入Redis日志文件注意日志级别。redis.log(redis.LOG_WARNING, “Script started with key: ” .. KEYS[1])这对于追踪生产环境复杂脚本的执行路径非常有用。另外确保用pcall包裹可能出错的非核心调用并妥善处理错误避免脚本因非关键错误而整体失败。local ok, err redis.pcall(‘SET’, ‘log:’ .. ARGV[1], ‘some info’) if not ok then redis.log(redis.LOG_ERR, “Failed to write log: ” .. err) — 不影响主逻辑继续执行 end5.2INFO命令中的脚本信息运行INFO commandstats可以看到所有命令的调用统计其中也包括EVAL和EVALSHA这可以帮助你发现脚本是否被频繁调用。INFO memory中关于Lua内存的部分可以监控脚本缓存占用的大小。5.3 复制与持久化影响需要特别注意的是Lua脚本的复制Replication和持久化AOF行为。当一个脚本被传播到从节点或写入AOF文件时Redis默认记录的是EVAL命令本身即完整的脚本内容而不是脚本执行过程中产生的具体写命令。这样做保证了从节点或AOF重放时能获得完全一致的结果因为脚本执行是确定性的。但这也意味着如果你的脚本内容非常大会对网络复制和AOF文件大小造成压力。你可以通过redis.replicate_commands()函数Redis 3.2来改变这一行为让Redis改为记录脚本执行产生的实际写命令序列这通常能显著减少数据量但前提是你的脚本必须是纯函数式的即相同的KEYS和ARGV输入总是产生相同的写命令序列否则会导致主从数据不一致。6. 经典模式与实战案例解析理论说了这么多来看几个实战中高频使用的脚本模式。6.1 分布式锁的加强版简单的SET key value NX PX timeout可以实现锁但释放时需要用Lua保证原子性避免误删其他客户端的锁。— KEYS[1]: 锁的key — ARGV[1]: 当前客户端持有的锁标识UUID — ARGV[2]: 锁的过期时间毫秒 local lockKey KEYS[1] local lockId ARGV[1] local ttl tonumber(ARGV[2]) — 尝试获取锁 local currentLockId redis.call(‘GET’, lockKey) if currentLockId false then — 锁不存在可以获取 redis.call(‘SET’, lockKey, lockId, ‘PX’, ttl) return true elseif currentLockId lockId then — 锁是自己持有的刷新过期时间可重入锁的简单实现 redis.call(‘PEXPIRE’, lockKey, ttl) return true else — 锁被其他客户端持有 return false end释放锁的脚本— KEYS[1]: 锁的key — ARGV[1]: 期望的锁标识 if redis.call(‘GET’, KEYS[1]) ARGV[1] then return redis.call(‘DEL’, KEYS[1]) else return 0 end6.2 滑动窗口限流实现一个在最近N秒内最多允许M次请求的限流器。— KEYS[1]: 限流器key如 rate_limiter:user123 — ARGV[1]: 窗口大小秒 — ARGV[2]: 最大请求次数 local key KEYS[1] local window tonumber(ARGV[1]) local limit tonumber(ARGV[2]) local now redis.call(‘TIME’) — Redis 5.0返回秒和微秒 local currentTime tonumber(now[1]) * 1000 math.floor(tonumber(now[2]) / 1000) — 转换为毫秒时间戳 local clearBefore currentTime – window * 1000 — 移除窗口之前的记录 redis.call(‘ZREMRANGEBYSCORE’, key, 0, clearBefore) — 获取当前窗口内的请求数 local currentCount redis.call(‘ZCARD’, key) if currentCount limit then — 未超限添加本次请求记录用时间戳作为score和member redis.call(‘ZADD’, key, currentTime, currentTime) — 设置整个key的过期时间避免冷数据堆积 redis.call(‘PEXPIRE’, key, window * 1000 1000) — 多加1秒缓冲 return true — 允许通过 else return false — 拒绝 end6.3 库存扣减与恢复电商秒杀场景保证库存不超卖。— KEYS[1]: 商品库存key (如 stock:sku_1001) — ARGV[1]: 需要扣减的数量 — ARGV[2]: 本次操作的唯一流水号用于幂等和恢复 local stockKey KEYS[1] local deductAmount tonumber(ARGV[1]) local txId ARGV[2] — 检查库存是否充足 local currentStock tonumber(redis.call(‘GET’, stockKey)) if currentStock nil then return {err “stock key not exist”} end if currentStock deductAmount then return {err “insufficient stock”, available currentStock} end — 扣减库存 local newStock currentStock – deductAmount redis.call(‘SET’, stockKey, newStock) — 记录扣减流水用于可能的恢复如订单取消 local recordKey ‘stock_record:’ .. txId redis.call(‘HSET’, recordKey, ‘sku_key’, stockKey, ‘amount’, deductAmount, ‘time’, redis.call(‘TIME’)[1]) redis.call(‘PEXPIRE’, recordKey, 86400000) — 24小时过期 return {ok true, new_stock newStock}对应的库存恢复脚本如订单取消时调用— KEYS[1]: 流水记录key local recordKey KEYS[1] local record redis.call(‘HGETALL’, recordKey) if #record 0 then return {err “record not found or expired”} end — 解析记录 local skuKey, amount for i 1, #record, 2 do if record[i] ‘sku_key’ then skuKey record[i1] elseif record[i] ‘amount’ then amount tonumber(record[i1]) end end if skuKey and amount then redis.call(‘INCRBY’, skuKey, amount) redis.call(‘DEL’, recordKey) return {ok true} else return {err “invalid record format”} end7. 集群环境下的特殊考量在Redis Cluster中使用Lua脚本除了前述的KEYS规范还有更多细节。7.1 多键操作与哈希标签Hash TagRedis Cluster要求一个命令包括脚本中的所有键必须位于同一个哈希槽slot。如果你需要对多个键进行原子操作而这些键天然不在同一个槽怎么办这时可以使用哈希标签。哈希标签是指键名中{}包围的部分集群在计算slot时只使用这部分。例如user:{1000}:profile和user:{1000}:orders尽管键名不同但因为哈希标签都是1000它们会被分配到同一个slot。你可以在脚本中操作它们。但务必谨慎使用滥用哈希标签会导致数据分布不均某些节点负载过重。7.2 跨节点脚本的替代方案有时原子性的多键操作确实需要涉及不同节点。此时Lua脚本无法直接实现。常见的替代方案是使用两阶段提交2PC或Saga事务模式但这会引入复杂性并削弱一致性。另一种思路是重新设计数据模型看看能否将要一起操作的数据聚合到同一个键里比如使用Hash或Sorted Set结构。这往往是从根本上更优的解决方案。8. 我踩过的坑与血泪经验最后分享几个只有踩过才知道的坑。坑1数字精度丢失。如前所述Lua的number是双精度浮点。一个经典的场景是操作金融余额以分为单位。如果你在Lua中计算local balance 100.01 – 0.01在极少数情况下由于浮点误差结果可能不是精确的100.00。对于精确计算要么在客户端用高精度库算好再传要么在Redis中全部用字符串存储在Lua中用字符串操作或者使用Redis的INCRBYFLOAT命令它本身也是浮点但由Redis处理。坑2脚本中的随机数。Lua的math.random()在同一个Redis实例内每次执行脚本时如果种子不变生成的随机序列是确定的。这破坏了脚本的“纯函数”性可能会影响复制和AOF。如果确实需要不可预测的随机性可以从ARGV传入一个随机种子或者使用redis.call(‘TIME’)的微秒部分作为随机源。坑3redis.call()的错误处理不够直观。比如redis.call(‘HGET’, ‘non_exist_hash’, ‘field’)返回的是nil在Lua中是false而不是一个错误。而redis.call(‘GET’, ‘non_exist_key’)也返回nil。但redis.call(‘HGETALL’, ‘non_exist_hash’)返回的是空表{}。你需要熟悉每个命令在键不存在时的返回行为并在脚本中做健壮的判空处理。坑4脚本的“副作用”与只读脚本。即使你的脚本只包含GET等读命令它依然会阻塞其他命令。对于复杂的只读脚本可以考虑使用Redis的READONLY命令需要在脚本中调用redis.set_repl(redis.REPL_NONE)不READONLY是一个独立的命令但更根本的是优化脚本性能。另外在集群只读副本上执行脚本需要确保脚本确实是只读的否则会报错。掌握Lua脚本是你从Redis“用户”进阶为“玩家”的关键一步。它赋予了Redis更强的能力但也带来了更大的责任。始终记住原子性不等于性能能力越大阻塞的风险也越大。在享受它带来的便利时务必通过严谨的测试、充分的监控和清晰的设计来驾驭它。