登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  数据库 >  Redis

Redis Lua 脚本怎样返回结构化结果给客户端

来源:17golang原创

时间:2026-11-16 19:20:10 342浏览 收藏

Redis Lua 脚本想把多个字段交给客户端时,不能把 Lua 表直接理解成 JSON 对象。脚本执行完后,Redis 会依据协议把返回值转换成客户端能识别的回复:字符串、整数、索引数组、状态回复或错误回复,客户端再按自己的类型系统解码。

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

return 最稳定的做法是先约定返回契约:列表用连续整数索引,状态用单独的 ok 字段,错误用 err 字段;不要把 Lua 的关联字段当成 JSON 键值对象,也不要在数组中间放 nil。
  • Lua 字符串通常转换为 bulk string,数字按整数回复处理。
  • 连续索引的 Lua table 转换成数组;第一个 nil 会让数组转换提前结束。
  • 只有带单个 ok 或 err 字段的表才表达状态或错误回复。

Lua 类型怎样映射成客户端回复

Redis Lua API 的关键是“Lua 值到 Redis 协议类型”的双向转换。默认脚本执行上下文使用 RESP2;客户端如果选择了其他协议,最终解析方式也会随协议改变。下面这张关系图只表达类型之间的对应关系,不是运行截图。

Redis Lua 返回值从 Lua 类型映射到 RESP2 客户端回复的静态关系图
图1:Redis Lua 返回值类型关系图,Lua 值经过协议转换后由客户端按回复类型读取。
Lua 返回值RESP2 中的表现设计提示
字符串bulk string适合返回单个标识、文本或序列化内容
数字integer replyLua 没有独立整数/浮点类型,浮点要按字符串返回
连续索引表array reply用于多个字段或嵌套列表,避免中间出现 nil
{ok = value}status reply表达成功状态或简单字符串
{err = value}error reply表达错误,并保留客户端的异常分支

用连续索引表返回多个字段

如果客户端需要一次拿到状态、任务编号和计数,可以返回一个连续的索引表。Redis 会把它转换成数组,数组中的每个位置就是一个字段;客户端应在接口文档中固定位置含义。

-- 用连续索引返回固定顺序的三个字段
local state = 'ready'
local task_id = ARGV[1]
local retry_count = 2

-- 数组位置要保持稳定,客户端按 1、2、3 读取
return { state, task_id, retry_count }

这个返回值适合字段数量固定的内部接口。如果字段会频繁增加,建议把返回结构版本化,或者返回一段由应用层约定的 JSON 字符串;不要直接写成 {state = state, task_id = task_id} 并期待客户端收到同名键。

嵌套数组可以表达层级结果

索引表可以嵌套,Redis 会把内层 table 继续转换成数组。它适合返回“任务状态 + 成员列表”这类层级结构,但必须保持每层都是连续索引。

-- 外层保存状态,内层保存 member-score 对
local members = {
  { 'job-A', 10 },
  { 'job-B', 20 }
}

-- 内层仍是连续数组,客户端可按固定位置解析
return { 'ok', members }

还有两个容易忽略的规则:Lua 数组遇到第一个 nil 就会在该位置截断;关联表里的其他键不会出现在 RESP2 数组中。因此,下面的写法不适合作为稳定返回契约:

-- 不要在数组中间放 nil,后面的字段可能无法进入回复
return { 'ok', nil, 'job-A' }

-- 不要把关联字段当成 JSON 对象返回
return { state = 'ok', task_id = 'job-A' }

redis.call 和 redis.pcall 怎样决定错误形态

redis.call 在 Redis 命令执行出错时会把运行时异常直接抛给调用方;redis.pcall 则始终返回一个回复,发生异常时用带 err 字段的表表示。两者不是“是否检查错误”的语法差别,而是客户端看到的错误契约不同。

Redis Lua redis.call redis.pcall 与客户端解析之间的静态关系图
图2:redis.call 与 redis.pcall 的返回结构示意图,正常回复、err 字段和嵌套数组都由客户端协议继续表达。
-- redis.call 出错时会把 Redis 命令异常抛给客户端
local value = redis.call('GET', KEYS[1])

-- redis.pcall 把错误变成带 err 字段的 Lua 表,便于脚本统一返回
local reply = redis.pcall('HGET', KEYS[1], ARGV[1])
if reply.err ~= nil then
  return { 'failed', reply.err }
end

-- 正常分支继续返回固定位置的状态和数据
return { 'ok', value, reply }

如果业务需要把不同失败原因交给客户端统一处理,pcall 更容易形成固定格式;如果错误必须立即中断当前脚本并交给客户端的异常机制,call 更直接。无论选择哪种方式,都不要在同一个接口里一会儿抛异常、一会儿返回数组错误,除非客户端明确支持两套分支。

用 ok 和 err 表达状态与业务错误

Redis 为状态和错误回复提供了两个辅助函数。redis.status_reply 返回带 ok 字段的表,redis.error_reply 返回带 err 字段的表。也可以直接构造相同形态的表,但使用辅助函数更能让意图清楚。

-- 用 status_reply 返回客户端可以识别的简单状态
if redis.call('EXISTS', KEYS[1]) == 1 then
  return redis.status_reply('FOUND')
end

-- 用 error_reply 保留错误码前缀,客户端可以按 ERR 分类处理
return redis.error_reply('ERR task_not_found')

Redis 官方建议错误文本的第一个单词作为错误码,例如 ERR task_not_found。客户端可以先判断回复类型,再读取错误码和说明;不要只比较一整段自然语言文本。

RESP2、RESP3 和空值该怎样留给客户端

Lua 脚本默认按 RESP2 规则处理命令回复,也可以使用 redis.setresp(3) 切换脚本内部读取 redis.call 或 redis.pcall 回复的协议版本。这个切换会改变类型转换,不能只改脚本而不调整客户端解析器。

-- 只有明确需要 RESP3 类型语义时才切换协议版本
redis.setresp(3)

-- 返回值仍需遵守客户端约定,不能把协议切换当成 JSON 序列化
return { 'ok', redis.call('GET', KEYS[1]) }

在 RESP2 下,Lua 的 false 会转成 null bulk reply;空的命令结果因此可能在客户端表现为 nil 或 null。消费代码要把它当成“没有值”处理,而不是把空值强行当成空字符串。Lua 数字也只有一种数值类型,返回时按整数回复转换;需要保留小数时应先格式化为字符串。

把返回契约写成客户端可维护的接口

一个实用的约定可以是:成功时返回 { 'ok', payload },可预期业务失败时返回 { 'err', code, message },底层 Redis 命令无法继续执行时让 redis.call 抛出异常。这样客户端能区分业务结果、业务错误和脚本运行时异常。

场景脚本返回方式客户端动作
固定字段成功结果连续索引表按版本化位置读取并检查数量
成功状态redis.status_reply读取 ok 内容
可预期业务错误redis.error_reply 或 err 表按首个错误码分支
底层命令参数或权限异常redis.call 抛错进入异常处理和告警路径
没有数据false 或空数组区分 null 与“有数据但数量为零”

常见问题

Redis Lua 能像 JSON 一样返回带键名的对象吗?

RESP2 的 Lua table 主要按索引数组转换,关联字段不会作为 JSON 键名返回。需要键名时,可以返回固定位置数组,或在脚本外由客户端/应用层组装 JSON。

为什么数组后面的字段没有返回?

Lua table 在转换数组时遇到第一个 nil 就会截断。把可选字段放到末尾,或用明确的占位字符串/状态字段表达缺失。

redis.pcall 返回的 err 是异常还是普通字段?

在脚本里它是带 err 字段的 Lua 表;转换给客户端后会表现为 Redis 错误回复。客户端仍应把它作为错误分支处理。

为什么返回小数后客户端看到的是整数?

Lua 只有一种 number 类型,Lua 到 RESP2 时数字会按整数回复转换。需要保留小数时,先格式化为字符串再返回。

应该返回数组还是 status_reply?

固定多字段结果用连续数组,单个成功状态用 status_reply;两者不要在同一个成功分支里无规则混用,先把接口契约写清楚。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>