1. 为什么你需要认真对待Redis Lua脚本如果你用过Redis大概率已经熟悉了SET、GET、HSET这些基础命令。它们很快但有时候你会遇到一些头疼的场景比如你需要先检查一个键是否存在如果不存在就设置它并设置过期时间如果存在就递增它。用客户端代码你需要发送EXISTS、SETEX、INCR三个命令这中间网络往返三次而且更关键的是这三个操作不是原子的——在EXISTS返回后、SETEX执行前其他客户端可能已经修改了这个键导致数据竞争。这就是Redis Lua脚本登场的时候。它不是一个可选项而是你从Redis“用户”进阶到“玩家”的关键技能。简单说Lua脚本让你能把一系列Redis命令打包成一个原子操作在服务端一次性执行。这带来的好处是实实在在的原子性避免了竞态条件减少网络开销提升了性能并且把复杂的业务逻辑下沉到数据库层让客户端代码更清爽。我见过太多项目因为初期忽略了脚本的使用在业务量上来后不得不花大力气重构去解决那些因非原子操作导致的零星但棘手的数据不一致问题。所以无论你是刚接触Redis还是已经用它处理百万级并发深入理解Lua脚本都至关重要。这篇内容我会把我这些年踩过的坑、总结的最佳实践毫无保留地拆开揉碎讲给你听从“为什么用”到“怎么用好”甚至“怎么避免用坏”让你能真正掌握这门“Redis内功”。2. Lua脚本核心机制与原子性深度解析很多人知道Lua脚本是原子的但对其背后的机制一知半解这会导致使用时犯下致命错误。我们来彻底搞懂它。2.1 脚本的执行模型并非真正的“事务”首先要纠正一个常见的误解Lua脚本的执行不等于一个多命令事务MULTI/EXEC。虽然它们都提供原子性但底层机制完全不同。当你通过EVAL或EVALSHA命令发送一个Lua脚本时Redis会做以下几件事解析与编译Redis的Lua环境会加载并编译这段脚本。如果脚本较长这个阶段会有微小的开销所以才有SCRIPT LOAD和EVALSHA的优化。执行编译后的脚本在一个独立的Lua虚拟机中运行。关键点来了脚本运行期间Redis服务器会被“锁住”——更准确地说脚本的执行是单线程、串行的。Redis不会在处理该脚本的期间去处理其他客户端的任何命令。这意味着脚本内的所有Redis命令比如redis.call(‘SET‘, KEYS[1], ARGV[1])都会像排队一样一个接一个地、不间断地执行完毕。返回结果脚本执行完成后将最后一个命令的结果或你在Lua中return的值返回给客户端然后Redis服务器才继续处理下一个客户端请求。这种“串行化”执行正是原子性的根源。它保证了脚本执行过程中数据视图不会被其他操作改变。对比MULTI/EXEC事务它只是将命令排队在EXEC时批量执行但排队过程中其他客户端的命令是可以被执行的不具备这种强隔离性。2.2 脚本的“副作用”与复制脚本的原子性带来了一个延伸问题主从复制和AOF持久化。Redis需要保证从库和重启恢复后的数据状态与主库完全一致。那么一个复杂的Lua脚本是如何被复制的呢Redis采用了一种聪明且高效的方式它不复制脚本本身的具体操作序列而是复制整个脚本的最终效果。更具体地说在脚本执行成功后Redis会将脚本本身通过EVAL命令携带的脚本体作为一个“命令”追加到AOF文件并传播给所有从库。从库在重放时会重新完整地执行一遍这个脚本从而得到完全相同的结果。这引出一个极其重要的实践你的Lua脚本必须是纯函数式的。也就是说给定相同的输入参数KEYS和ARGV脚本执行必须产生完全相同的Redis数据变更序列。脚本内部不能依赖外部状态比如系统时间(os.time)、随机数(math.random)、或者访问外部服务。因为从库重放脚本时这些外部状态可能已经改变导致主从数据不一致。踩坑实录早期我在一个促销活动中写了一个脚本里面用math.random()来生成一个优惠码。在单机测试完美一上主从集群就出事了。主库生成的码和从库生成的码完全对不上导致后续验券时一片混乱。教训就是所有动态值必须在客户端生成好通过ARGV参数传入脚本。2.3 KEYS与ARGV必须严格遵守的规范EVAL命令的签名是EVAL script numkeys key [key ...] arg [arg ...]。这里的numkeys、KEYS、ARGV不是建议是必须遵守的契约。numkeys指明后面跟了多少个键名。它必须是一个准确的数字。KEYS一个Lua数组包含了脚本要操作的所有Redis键。为什么必须显式声明这与Redis集群有关。集群模式下Redis需要根据numkeys来确定这个脚本应该被发送到哪个槽位slot的节点上执行。如果你声明了numkeys为2但实际在脚本里通过redis.call操作了第三个未声明的键而这个键恰好位于另一个节点脚本就会执行失败。ARGV一个Lua数组包含所有非键名的参数比如要设置的数值、过期时间、标志位等。一个黄金法则是所有在脚本中会被redis.call或redis.pcall操作的键都必须出现在KEYS数组中。即使这个键是你根据ARGV参数动态拼接出来的你也必须提前计算好并放入KEYS。对于集群环境这更是铁律。-- 错误示范集群下可能失败 local dynamicKey “prefix:” .. ARGV[1] redis.call(‘SET‘, dynamicKey, ‘value‘) -- dynamicKey未在KEYS中声明 -- 正确示范 -- 假设我们知道ARGV[1]是’id123‘那么客户端调用时应将完整的键名放入KEYS -- EVAL “script” 1 “prefix:id123” “id123” local theKey KEYS[1] -- 即 “prefix:id123” redis.call(‘SET‘, theKey, ‘value‘)3. 从入门到精通脚本编写全流程拆解理解了原理我们动手写脚本。我会用一个经典的“分布式限流”场景作为主线带你走完编写、调试、优化、部署的全过程。3.1 场景定义与脚本初版假设我们要实现一个接口的分钟级限流每个用户userId每分钟只能访问10次。客户端逻辑问题所在构造键名rate:limit:${userId}:${minuteTimestamp}。发送INCR命令给Redis。如果返回值为1第一次访问同时发送EXPIRE命令设置60秒过期。判断INCR的返回值是否大于10如果大于则拒绝访问。这里步骤2和3不是原子的可能在INCR后、EXPIRE前进程崩溃导致这个键永远不过期限流失效。Lua脚本第一版-- KEYS[1]: 限流键如 rate:limit:user123:1715203200 -- ARGV[1]: 限流阈值如 10 -- ARGV[2]: 过期时间秒如 60 local current current redis.call(‘INCR‘, KEYS[1]) if current 1 then -- 第一次访问设置过期时间 redis.call(‘EXPIRE‘, KEYS[1], ARGV[2]) end -- 如果当前计数大于阈值返回0表示拒绝否则返回1表示允许 if current tonumber(ARGV[1]) then return 0 else return 1 end这个脚本已经解决了原子性问题。调用方式EVAL “上面脚本内容” 1 rate:limit:user123:1715203200 10 60。返回1允许返回0拒绝。3.2 脚本调试与错误处理直接在Redis CLI里写长脚本很痛苦。我推荐的方式是在本地用文本编辑器写好.lua文件。使用redis-cli --eval命令进行测试。这是最接近生产的调试方式。redis-cli --eval /path/to/rate_limiter.lua rate:limit:test:1 , 10 60注意--eval参数后键和参数之间有一个逗号,分隔且逗号前后要有空格。这是redis-cli的语法要求。在脚本中积极使用redis.log函数输出调试信息。日志级别可以是redis.LOG_DEBUG、redis.LOG_NOTICE等可以在Redis配置文件中设置loglevel来查看。redis.log(redis.LOG_NOTICE, “Key: “ .. KEYS[1] .. “, Current count: “ .. tostring(current))错误处理是脚本健壮性的关键。在Lua脚本中调用Redis命令有两个函数redis.call()如果命令执行错误如对字符串执行HGET错误会抛出Lua异常导致整个脚本回滚之前已执行的命令也会被撤销。redis.pcall()以保护模式调用。如果命令出错它会返回一个Lua table表示错误脚本可以捕获并处理这个错误脚本不会中止。实操心得绝大多数情况下你应该使用redis.call()。因为脚本的原子性意味着“要么全做要么不做”。如果中间某个命令失败了比如类型错误通常意味着业务逻辑有问题应该让整个脚本失败回滚。使用redis.pcall()的场景极少除非你明确知道某个命令可能失败且这个失败是可接受的、需要脚本继续执行其他补救逻辑。滥用pcall会掩盖错误导致数据处于一个难以理解的中间状态。3.3 性能优化与高级技巧初版脚本可以工作但还有优化空间。1. 参数类型转换Lua脚本中KEYS和ARGV中的值都是字符串。如果你需要将它们作为数字比较或运算必须显式转换。tonumber()和tostring()是你的好朋友。忘记转换是新手最常见的错误之一会导致诡异的逻辑错误比如“10“ “2“在字符串比较中是false因为”1“的ASCII码小于”2“。2. 使用局部变量Lua中局部变量local var的访问速度远快于全局变量。在脚本开始处将常用的KEYS和ARGV元素赋值给局部变量是一个好习惯。local limitKey KEYS[1] local threshold tonumber(ARGV[1]) local ttl tonumber(ARGV[2])3. 避免循环与复杂计算Redis的单线程模型意味着脚本执行会阻塞其他所有命令。绝对不要在Lua脚本里写死循环、耗时的复杂计算如解析大JSON、或发起网络请求。脚本应该只包含必要的逻辑和Redis命令。复杂的业务计算应该放在客户端。4. 使用SCRIPT LOAD与EVALSHA每次发送EVAL都会传输完整的脚本源码。如果脚本很长且被频繁调用网络开销不容忽视。优化方案是 - 在应用启动时用SCRIPT LOAD your_script命令将脚本加载到Redis服务器。Redis会返回一个该脚本的SHA1校验和例如“a1b2c3d4...“。 - 后续调用时使用EVALSHA sha1 numkeys key [key ...] arg [arg ...]来代替EVAL。 - 如果EVALSHA失败例如脚本未加载客户端需要捕获错误并回退到使用EVAL。成熟的Redis客户端库如Jedis、Lettuce、ioredis都内置了这种“EVALSHA失败转EVAL”的机制。优化后的限流脚本-- 速率限制脚本 (优化版) -- KEYS[1]: 限流键 -- ARGV[1]: 阈值 (数字) -- ARGV[2]: 过期时间 (秒数字) local key KEYS[1] local threshold tonumber(ARGV[1]) local ttl tonumber(ARGV[2]) local current redis.call(‘INCR‘, key) if current 1 then redis.call(‘EXPIRE‘, key, ttl) end -- 更简洁的比较和返回 return current threshold and 1 or 04. 实战进阶复杂业务场景的脚本设计掌握了基础我们来看几个更复杂的、能体现脚本威力的真实场景。4.1 场景一带权重的分布式锁与续期简单的SETNX锁存在锁过期但业务未执行完的问题。我们需要一个能续期、且value具有客户端唯一标识的锁。-- 加锁脚本 -- KEYS[1]: 锁键 -- ARGV[1]: 锁值唯一标识如UUID -- ARGV[2]: 过期时间(毫秒) local key KEYS[1] local value ARGV[1] local ttl tonumber(ARGV[2]) -- 尝试设置锁NX表示仅当键不存在时设置PX设置毫秒过期时间 local result redis.call(‘SET‘, key, value, ‘NX‘, ‘PX‘, ttl) if result then return 1 -- 加锁成功 else -- 锁已存在检查是否是自己持有的防止误删他人锁 local currentValue redis.call(‘GET‘, key) if currentValue value then -- 是自己持有的锁刷新过期时间 redis.call(‘PEXPIRE‘, key, ttl) return 2 -- 续期成功 else return 0 -- 加锁失败被其他客户端持有 end end-- 解锁脚本 (确保只能解自己的锁) -- KEYS[1]: 锁键 -- ARGV[1]: 锁值唯一标识 local key KEYS[1] local value ARGV[1] if redis.call(‘GET‘, key) value then -- 确认是自己持有的锁删除它 return redis.call(‘DEL‘, key) else -- 不是自己的锁什么都不做 return 0 end这个方案比许多客户端库自带的锁更安全因为它用脚本保证了“判断-删除”的原子性解决了锁误删的经典问题。4.2 场景二秒杀库存扣减与订单创建秒杀的核心是超卖问题。脚本要确保库存检查、扣减、记录订单流水是原子的。-- 秒杀扣减脚本 -- KEYS[1]: 商品库存键 (hash field: stock) -- KEYS[2]: 已售集合键 (set记录成功用户ID防重复购买) -- ARGV[1]: 商品ID -- ARGV[2]: 用户ID -- ARGV[3]: 购买数量 (通常为1) local stockKey KEYS[1] local soldKey KEYS[2] local itemId ARGV[1] local userId ARGV[2] local quantity tonumber(ARGV[3]) -- 1. 检查是否已购买过 (防重) if redis.call(‘SISMEMBER‘, soldKey, userId) 1 then return {-1, “重复购买“} -- 自定义返回格式表示业务失败 end -- 2. 检查并扣减库存 local currentStock tonumber(redis.call(‘HGET‘, stockKey, ‘stock‘)) if not currentStock or currentStock quantity then return {0, “库存不足“} -- 库存不足 end -- 3. 原子操作扣库存 记录购买用户 redis.call(‘HINCRBY‘, stockKey, ‘stock‘, -quantity) redis.call(‘SADD‘, soldKey, userId) -- 4. 可以在这里生成一个订单ID需通过ARGV传入保证幂等 local orderId “ORDER_“ .. itemId .. “_“ .. userId .. “_“ .. redis.call(‘TIME‘)[1] -- 注意TIME命令返回数组[1]是秒级时间戳。这里仅作演示生产环境应用更复杂的ID生成。 return {1, orderId} -- 成功返回订单ID这个脚本将整个秒杀最核心的“判断-扣减”逻辑原子化彻底杜绝了超卖。返回结构使用Lua table可以携带多种信息。4.3 场景三维护有序的排行榜延迟更新游戏排行榜分数更新频繁且可能涉及多个维度如分数、更新时间。我们利用ZSET和Hash的组合通过脚本原子更新。-- 更新用户分数并刷新排行榜 -- KEYS[1]: 排行榜ZSET键 (按分数排序) -- KEYS[2]: 用户详情Hash键 -- ARGV[1]: 用户ID -- ARGV[2]: 本次新增分数 -- ARGV[3]: 当前时间戳 local zsetKey KEYS[1] local hashKey KEYS[2] local userId ARGV[1] local addScore tonumber(ARGV[2]) local timestamp tonumber(ARGV[3]) -- 1. 获取用户当前总分和上次更新时间 local userData redis.call(‘HMGET‘, hashKey, userId .. ‘:score‘, userId .. ‘:update_time‘) local oldScore tonumber(userData[1]) or 0 local lastUpdate tonumber(userData[2]) or 0 -- 2. 计算新分数这里可以是复杂逻辑比如时间衰减 local newScore oldScore addScore -- 示例简单的分数更新实际可能根据(lastUpdate)做衰减计算 -- 3. 原子更新更新Hash详情并更新ZSET分数 redis.call(‘HMSET‘, hashKey, userId .. ‘:score‘, newScore, userId .. ‘:update_time‘, timestamp) -- ZADD XX: 仅更新已存在成员不添加新成员。分数用newScore。 redis.call(‘ZADD‘, zsetKey, ‘XX‘, newScore, userId) -- 返回更新后的分数和排名 local rank redis.call(‘ZREVRANK‘, zsetKey, userId) -- 降序排名 return {newScore, rank and rank 1 or nil} -- Lua排名从0开始转成1开始这个脚本展示了如何将多个数据结构的更新绑定在一起保证用户详情和排行榜顺序的一致性。5. 生产环境部署、监控与避坑指南脚本写好了如何安全、高效地用到生产环境这里全是经验之谈。5.1 脚本管理策略不要把脚本字符串硬编码在业务代码里。推荐的管理方式独立文件存储将每个.lua脚本文件放在项目的特定目录如/scripts/redis。应用启动时加载在应用初始化阶段Spring的PostConstruct或Node.js的启动脚本读取文件内容通过SCRIPT LOAD命令加载到Redis并将返回的SHA1码缓存在内存如ConcurrentHashMap或一个全局变量中。封装调用客户端封装一个通用的脚本执行工具类。它首先尝试EVALSHA如果收到NOSCRIPT错误说明脚本未加载可能Redis重启了则回退到EVAL并重新SCRIPT LOAD一次更新本地缓存。版本控制在脚本文件名或内容中包含版本号如rate_limiter_v2.lua当脚本逻辑变更时新的SHA1会不同自然淘汰旧版本调用。这比在Redis中手动管理脚本要简单。5.2 脚本超时与SCRIPT KILLRedis配置项lua-time-limit默认5秒定义了脚本执行的最长时间。如果一个脚本运行超过这个限制Redis会开始记录日志但默认不会停止它。其他客户端会开始收到“Busy”错误。此时你需要做出选择SCRIPT KILL如果脚本还没有执行过任何写命令只执行了GET、EXISTS等读命令你可以用此命令安全地终止它。SHUTDOWN NOSAVE如果脚本已经执行了写命令SCRIPT KILL无法终止它。为了恢复服务你只能强制关闭Redis数据可能会丢失。这是最坏的情况。血泪教训务必让你的脚本轻量、快速。避免在脚本中进行任何循环遍历大数据集如ZRANGE 0 -1然后遍历、复杂运算。如果逻辑复杂考虑拆分成多个脚本或用客户端辅助。我曾因为一个脚本里不小心对一个大集合进行了SMEMBERS然后遍历导致线上Redis卡死数秒触发告警。5.3 集群环境下的特殊考量在Redis Cluster中脚本的所有键必须位于同一个哈希槽slot中因为脚本会被发送到持有第一个键的节点上执行。如果你需要操作多个键但它们在集群中可能分布在不同节点你有两个选择使用哈希标签Hash Tag用花括号{}将键的一部分包起来Redis会只根据花括号内的内容计算slot。例如user:{123}:profile和user:{123}:orders会被分配到同一个slot因为它们的{123}部分相同。这需要你在设计键名时就做好规划。将逻辑拆分到客户端如果无法使用哈希标签意味着你的多键操作本质上是跨节点的分布式事务。这时Lua脚本的原子性就失效了。你必须在客户端用更复杂的逻辑如两阶段提交、Saga模式来保证最终一致性这超出了Redis脚本的能力范围。5.4 监控与调试慢日志Redis的慢查询日志(slowlog)也会记录执行时间过长的脚本。通过SLOWLOG GET可以查看帮助你发现性能有问题的脚本。INFO commandstats这个命令可以统计所有命令的调用次数和耗时。频繁被EVAL/EVALSHA调用的脚本会在这里体现出来。日志如前所述在脚本中合理使用redis.log()并在Redis配置中调整合适的日志级别是线上排查问题的有力工具。5.5 常见错误速查表错误现象可能原因解决方案NOSCRIPT错误脚本未通过SCRIPT LOAD加载或Redis重启后脚本缓存丢失。客户端实现EVALSHA失败自动降级到EVAL的逻辑。-ERR Error running script ... user_script: ...: Write commands not allowed after non deterministic commands脚本中在写了RANDOMKEY,TIME,SRANDMEMBER等非确定性命令后又执行了写命令。确保所有写命令在非确定性命令之前执行或避免在脚本中使用非确定性命令。脚本执行超时Redis无响应脚本中有死循环或处理了过大的数据。使用SCRIPT KILL如果脚本未写或紧急重启。优化脚本避免大数据操作。主从数据不一致脚本依赖了外部状态如时间、随机数。确保脚本是纯函数所有动态数据通过ARGV传入。-ERR ‘-XXXX‘ ... calling redis command from Lua script脚本尝试执行Redis不存在的命令或命令参数错误。检查命令拼写和参数格式。在测试环境充分验证。集群模式下脚本执行失败脚本操作的键不在同一个slot。使用哈希标签确保键在同一slot或重新设计数据模型。最后记住Lua脚本是Redis的一把利器但也是一把双刃剑。它用原子性解决了复杂性问题但也引入了脚本本身的管理、性能和可调试性挑战。我的经验是对于简单的多命令序列优先考虑管道pipeline或事务multi对于需要原子性判断和更新的核心业务逻辑再祭出Lua脚本。在编写时时刻想着“轻量、确定、无副作用”这三个原则你就能稳稳地驾驭它让它成为你高并发系统里的定海神针。
