Redis Lua 脚本如何安全返回多条结果：脚本参数、数组响应与客户端解码

Redis Lua 脚本里写了 return { value, score, status }，服务端看起来执行成功，客户端却拿到空值、少一个字段，甚至把小数分数变成整数。这类问题通常不是 Redis 丢数据，而是 EVAL 的参数分区和 Lua table 到 RESP2 的转换规则没有对齐。

为什么 Redis Lua 的多值返回会少字段

先把问题缩小成一个可复查的脚本。它读取一个哈希字段，再返回值、分数和处理状态：

local value = redis.call('HGET', KEYS[1], ARGV[1])
local score = ARGV[2]
return { value or '', score, 'ok' }

这里有三层边界：KEYS 只放 Redis 键名，ARGV 放字段名和业务参数；返回 table 的数字下标决定数组顺序；客户端连接默认可能仍是 RESP2。任意一层理解错，最终响应都会看起来“不完整”。

EVAL、KEYS 与 ARGV 先按 numkeys 分清楚

EVAL 的标准形态是 EVAL script numkeys [key ...] [arg ...]。例如：

redis-cli HSET user:42 name Alice
redis-cli EVAL "return {redis.call('HGET', KEYS[1], ARGV[1]), ARGV[2]}" 1 user:42 name active

numkeys 是 1，所以 user:42 进入 KEYS[1]，后面的 name 和 active 进入 ARGV[1]、ARGV[2]。如果把 name 也算进键数量，脚本不会得到想要的字段名；在 Redis Cluster 场景，还可能因为脚本声明的键集合不正确而无法路由。

用 redis-cli 把参数分区验一遍

调试时可以把脚本写成一行，直接返回四个稳定字段：

redis-cli EVAL "return {KEYS[1], ARGV[1], ARGV[2], redis.call('HGET', KEYS[1], ARGV[1])}" 1 user:42 name active

预期数组依次是 user:42、name、active 和 Alice。先确认这个顺序，再把业务字段换回去，排查成本最低。

Lua table 返回数组时，nil 是最容易忽略的截断点

Redis 会把连续数字下标的 Lua table 转成 RESP2 数组，但遇到第一个 nil 就停止。图中的 table response 经过 nil truncation 后，RESP2 只能得到前面的连续项。下面的结果不是三项，而是两项：

local value = redis.call('HGET', KEYS[1], 'missing')
return { value, 'not-reached', 'ok' }

不存在的哈希字段会让 HGET 返回 Redis 空值，映射到 Lua 后可能表现为 false，而手工构造 table 时如果真的留下 nil，后续数组项就不会被发给客户端。需要稳定协议时，应该把空值归一化成空字符串、明确状态，或者返回错误表，而不是把“缺失”留在数组中间。

RESP2 下分数和状态应该怎样设计

Lua 只有一种 number 类型。Redis 在 RESP2 下会把 Lua number 转成整数回复，所以 3.3333 返回到客户端会变成 3。需要保留小数时，把它当字符串返回：

local score = redis.call('ZSCORE', KEYS[1], ARGV[1])
return { score or '', 'ok' }

另一个常见误区是把关联字段写成 table 的命名键，例如 { value = 'Alice', status = 'ok' }。在 RESP2 数组转换中，这些命名键不会自动变成对象字段；跨语言客户端通常只会收到数组项。因此更稳妥的做法是约定固定位置：第一个是值，第二个是分数文本，第三个是状态。

客户端解码前先固定响应契约

应用层不要只判断“脚本有没有报错”，还要检查数组长度和状态位。例如约定响应必须有三项：

local result = redis.call('HGET', KEYS[1], ARGV[1])
if not result then
  return { '', '', 'missing' }
end
return { result, ARGV[2], 'ok' }

客户端收到后先验证长度，再根据第三项判断前两项是否可用。若连接使用 RESP3，协议会提供更多类型表达，但脚本仍应明确是否依赖 redis.setresp()；不要让一处连接配置变化悄悄改变业务解码。

上线前的四项检查

• 检查 numkeys 与 KEYS 数量是否一致，业务参数全部放入 ARGV。
• 检查返回 table 的数组项是否连续，尤其不要在中间放 nil。
• 检查 ZSCORE 等小数值是否按字符串传回。
• 让客户端对数组长度、状态位和错误回复做显式校验，并在 redis-cli 中保留一条最小复现命令。

相关问题

Redis Lua 能直接返回 Lua 对象吗

默认不能按客户端对象模型自动返回。RESP2 下应使用连续数组项；命名键不会自动变成对象字段。

为什么数组结果只返回前几项

优先检查中间是否出现 nil。Lua table 转 RESP2 数组会在第一个 nil 处截断。

Redis Lua 返回浮点数为什么变整数

RESP2 下 Lua number 会按整数回复。要保留小数，先把分数作为字符串返回。

KEYS 和 ARGV 可以互换吗

不建议。KEYS 应只承载脚本访问的键，ARGV 承载普通参数；这既是 EVAL 契约，也关系到集群路由。

把多值返回当成一个小型接口

Redis Lua 的返回结果不是“临时打印几项数据”，而是一个由 EVAL 参数、Lua table 和 RESP2/RESP3 共同定义的小型接口。先固定 KEYS、ARGV 和数组位置，再处理缺失值和浮点值，客户端就不会把协议细节误判成业务故障。