Redis Lua 脚本返回数组与 RESP 类型映射

Redis Lua 脚本返回数组时，关键不是“Lua 表看起来像数组”，而是它会按照当前连接的 RESP 协议把表转换成 Redis 回复。默认情况下，连续的数字索引会变成 RESP2 数组；第一个 nil 会截断后面的元素，关联字段不会出现在数组里，Lua 数字也会按 RESP2 规则变成整数。

官方地址：https://redis.io/docs/latest/develop/programmability/lua-api/

这篇只讨论 Lua 脚本的返回值映射，不展开脚本缓存、事务或客户端库的 API 包装。先记住下面三点：

• 脚本内部的 redis.call 默认按 RESP2 把 Redis 回复转换成 Lua 类型。
• return { ... } 中连续的索引项才会组成数组，关联键和值不会自动变成对象。
• 客户端是否使用 RESP3，还取决于连接端是否通过 HELLO 3 选择了 RESP3。

先把两个协议边界分开

Redis 文档里的“RESP2 转 Lua”和“Lua 转 RESP2”是两个方向。脚本调用 redis.call('HGETALL', ...) 时，Redis 先把命令回复变成 Lua 值；脚本最后执行 return 时，又把 Lua 值编码成客户端能够读取的 Redis 回复。

默认脚本执行使用 RESP2。整数会进入 Lua 数字，字符串进入 Lua 字符串，RESP 数组进入 Lua 表，空 bulk 或空 multi-bulk 在脚本内部通常表现为 false。因此，下面的脚本返回的是“数组中的两个元素”，不是带有 name 和 count 字段的 JSON 对象：

-- 只使用连续数字索引，确保返回值能稳定映射为 RESP2 数组
local name = ARGV[1]
local count = tonumber(ARGV[2]) or 0

return {name, count}

如果客户端以 RESP2 读取，逻辑上会看到一个字符串和一个整数。应用层要么约定位置，要么在 Lua 中提前编码成 JSON 字符串；不要把“Lua 表的键”误当作客户端一定能收到的对象字段。

按索引返回数组：连续项才是数组内容

最容易排查的方式是先只返回数字索引项，再逐项增加嵌套数组。Lua 的数组部分从索引 1 开始，Redis 会将它映射成 RESP 数组；嵌套表会继续转换为嵌套数组。

-- 外层数组放置固定顺序；内层数组表达一组标签
local result = {
    ARGV[1],
    tonumber(ARGV[2]) or 0,
    {"cache", "lua"},
}

return result

这种返回方式适合字段数量固定、客户端已经约定位置的场景。例如第 1 项是名称，第 2 项是数量，第 3 项是标签数组。若需要让调用方按字段名读取，建议直接返回 JSON 字符串，或者在客户端和服务端都明确采用 RESP3 map，而不是把关联键偷偷塞进同一张 Lua 表。

出现 nil、浮点数和布尔值时逐层排查

当返回结果“少了一项”或“类型不对”，优先检查下面三种情况。

1. 第一个 nil 会让数组提前结束

Lua 表不能像 JSON 数组那样可靠地保留中间空洞。Redis 把 Lua 表转换为 RESP 数组时，遇到第一个 nil 就停止，后面的值不会继续输出。

-- nil 会截断数组；后面的 ready 不会出现在 RESP2 回复中
return {"id-7", nil, "ready"}

如果业务需要表达“第二项为空但第三项仍存在”，可把空值改成约定字符串，或返回 JSON 文本；不要依赖 Lua 表中的空洞。

2. RESP2 下 Lua 数字会作为整数回复

Lua 只有一种 number 类型。按 RESP2 返回时，3.75 这类数字会去掉小数部分并变成整数回复。如果必须保留小数，先用字符串返回，并在客户端按业务精度解析。

-- RESP2 不保留 Lua number 的小数部分；需要精度时显式返回字符串
return {3.75, "3.75"}

3. true 和 false 不能按 JSON 布尔值理解

在 RESP2 的 Lua 到 Redis 转换中，true 会变成整数 1，false 会变成空 bulk reply。若客户端看到 1 或 null，不要先怀疑客户端数组解析；先确认脚本是否直接返回了布尔值。

需要 map 或 double 时切换 RESP3

RESP3 能表达 map、set、double、true/false 和 null 等更丰富的类型，但要区分两个动作：redis.setresp(3) 控制脚本调用 redis.call 或 redis.pcall 时收到的回复协议；客户端连接则要用 HELLO 3 选择 RESP3。只改脚本内部协议，不代表客户端一定按 RESP3 解析。

-- 让脚本内部的 redis.call 使用 RESP3 回复，并返回一个可识别的 map
redis.setresp(3)

return {
    map = {
        name = ARGV[1],
        count = tonumber(ARGV[2]) or 0,
    },
}

在 RESP3 客户端中，这种结构可以表达为 map；如果连接仍是 RESP2，Redis 会按协议做兼容转换，map 会退化为交替的字段名和值组成的数组。也就是说，服务端脚本和客户端协议必须一起纳入返回契约。

# 连接时选择 RESP3，再执行脚本；脚本文件只作为示例输入
redis-cli HELLO 3
redis-cli --eval return-map.lua , order-17 4

这里的第二条命令只说明调用形态：生产环境应由客户端统一管理连接与脚本参数，并确保调用方知道返回的是 map 还是兼容后的数组。

最后用返回契约固定解析方式

把脚本交给业务使用前，可以按这份清单做排查：

1. 返回数组是否全部使用连续的数字索引，是否误把关联字段混在数组表中？
2. 数组中是否存在 nil，导致后续元素被截断？
3. 浮点数是否需要保留小数，是否应该改成字符串？
4. 空值是要表示 RESP2 的 null，还是要用 JSON 显式表达？
5. 脚本中的 redis.setresp 与客户端的 HELLO 是否使用了同一套协议约定？

如果字段固定且追求简单，RESP2 数组配合位置契约最省事；如果需要字段名、布尔值、空值和小数都保持类型，优先让客户端明确使用 RESP3。最重要的是不要仅凭 Lua 表的视觉形状猜测网络返回值，而要从“Lua 类型—脚本协议—客户端协议”三层同时确认。

常见问题

Redis Lua 返回的关联字段为什么消失了？

RESP2 的 Lua 表只有连续索引部分会转换成数组，关联键值不会出现在数组回复中。需要字段名时使用 RESP3 map，或在脚本中用 cjson.encode 编码为 JSON 字符串。

只调用 redis.setresp(3) 就能让客户端收到 RESP3 吗？

不能。它主要改变脚本调用 Redis 命令时接收回复的协议；客户端仍要通过 HELLO 3 选择 RESP3，最终返回类型才按客户端协议呈现。