Redis Lua 脚本怎样返回多个状态值

我第一次把 Redis Lua 脚本接进业务代码时，脚本本身执行成功了，客户端却只拿到了一个值。原因不是 Redis 不能返回多个结果，而是 Lua 脚本需要把多个结果组织成一份数组回复：通常写成 return { status, message, value }，客户端再按固定下标读取。

本文只解决一个小任务：一次 EVAL 调用同时返回状态码、提示信息和业务值。示例不把返回格式伪装成某个客户端的专属对象，也不假设下面的输出已经在本机运行过。

官方文档：https://redis.io/docs/latest/develop/programmability/eval-intro/

不要写多个顶层 return 期待得到多个结果；把结果按协议放进一个连续的 Lua 数组表，并提前约定每个位置的含义。

先用 Lua 数组表装下多个结果

Redis 的 EVAL 只接收一个脚本返回值。这个返回值可以是字符串、整数、空值或数组回复。要同时返回多个状态，就把它们放进 Lua 的数组部分：

# 第一个参数是脚本，0 表示后面没有 Redis key；普通参数从 ARGV[1] 开始
# 返回数组的三个位置：1=状态码，2=消息，3=业务值
redis-cli EVAL "return { 1, 'ready', ARGV[1] }" 0 order-1001

这份示例的约定是：第 1 项为整数状态码，第 2 项为消息，第 3 项为业务值。示意回复可以理解为 [1, "ready", "order-1001"]。不同客户端会把它转换成自己的数组类型，但位置关系不变。

关键点在于 return 后面只有一个 Lua table。下面这张图把脚本输入、数组回复和客户端读取关系放在一起，便于先确定协议，而不是先纠结某个客户端的类型名称。

把业务状态和数据放进固定位置

实际脚本往往会先读取一个 key，再根据结果返回不同状态。例如订单状态存在时返回状态码、状态文本和当前值；不存在时也保持三项结构，只把业务值改成约定的字符串。

-- 第 1 项是状态码，第 2 项是说明，第 3 项是业务值；三项始终保持连续
local value = redis.call('GET', KEYS[1])

if value == false then
    -- 用明确的空值文本保持返回协议稳定，避免中间出现 nil
    return { 0, 'not-found', '' }
end

-- 读到数据时返回同样的三项结构，客户端无需猜测分支形状
return { 1, 'found', value }

调用时把真正访问的键放在 KEYS 区域：

# 1 表示后面有一个 key；order:1001 会进入 KEYS[1]
# 业务脚本只读取这个声明过的 key，返回结果仍按三项协议组织
redis-cli EVAL "local value = redis.call('GET', KEYS[1]); if value == false then return {0, 'not-found', ''} end; return {1, 'found', value}" 1 order:1001

这里没有把 key 塞进 ARGV，因为 Redis 会区分 key 名与普通参数；在集群部署中，脚本访问的 key 也应显式列在 KEYS 参数里。返回协议和 key 参数是两件事，但都应在脚本入口处写清楚。

nil、布尔值和错误分支要先定协议

多值返回最容易踩的坑是把 Lua 的 nil 当成普通占位符。Lua table 的数组部分要求连续下标；如果中间出现 nil，Redis 看到的数组边界可能提前结束，后面的值就不再是可靠的返回字段。

-- 不推荐：第二项是 nil，客户端可能看不到后面的业务值
return { 1, nil, 'still-here' }

-- 推荐：用稳定字符串表达“没有消息”，让三个位置始终存在
return { 1, '', 'still-here' }

布尔值也不宜直接作为跨语言协议的核心字段。Redis Lua API 对 Lua 值有自己的转换规则，客户端语言还会再转换一次。更稳妥的做法是使用整数状态码，例如 1 表示成功、0 表示未找到，或使用明确的字符串状态。

错误也要区分两类：如果脚本调用 redis.call() 触发运行时错误，错误会直接返回给调用方；redis.pcall() 会把错误作为脚本上下文中的结果，便于脚本自行组织协议。只有在确实需要把错误纳入业务返回时，才让客户端与脚本共同约定错误对象的位置。

用一份小协议收住 EVAL 的边界

如果脚本要同时修改数据并报告结果，可以把返回协议固定为 [code, message, value]，并把脚本保持在短小范围内：

-- 该脚本只修改 KEYS[1]，并返回固定三项；不在脚本中动态拼接 key
local old = redis.call('GET', KEYS[1])
local nextValue = ARGV[1]

if old == nextValue then
    -- 重复写入仍返回可识别的状态，客户端可以决定是否提示用户
    return { 0, 'unchanged', old or '' }
end

redis.call('SET', KEYS[1], nextValue)
-- Redis Lua 脚本按原子语义执行，但脚本越长，阻塞其他请求的时间越长
return { 1, 'updated', nextValue }

调用方只需要记住三条规则：第一个数字是业务状态，第二项是机器可读或稳定的消息，第三项是业务值；实际 key 通过 KEYS 传入，写入内容通过 ARGV 传入；脚本只做必要的数据操作，不把大量业务流程塞进一次 EVAL。

如果返回结构以后会增加字段，优先在协议中明确版本或追加字段，并让旧客户端仍能读取前三项。不要在中间插入一个偶尔出现的 nil，也不要把不同分支写成完全不同长度的数组。

常见问题

能不能写 return status, message, value？不能把它当成 Redis 的多字段回复协议。应返回一个 table，例如 return { status, message, value }。

为什么返回数组后客户端只看到前两项？优先检查数组中是否插入了 nil，以及客户端是否把 Redis 的空回复转换成了语言自身的空值。

多个结果会让脚本失去原子性吗？返回数组本身不会改变脚本的原子语义；真正需要注意的是 Lua 脚本执行期间会阻塞其他服务器活动，所以脚本应保持短小。

把“返回多个值”当成一个小型响应协议来设计，Redis Lua 就不会再出现客户端拿到结果却不知道每一项含义的情况：连续数组负责形状，状态码负责分支，KEYS/ARGV 负责输入边界。