Redis Lua 脚本返回结构化状态码避免业务歧义的实现方法

Redis Lua 脚本最容易留下的隐患，不是命令能不能执行，而是调用方拿到一个 OK、空值或字符串后，无法判断这次操作究竟是“已创建”“已经存在”还是“条件不满足”。更稳妥的做法是把返回值固定为 {状态码, payload}：第一个位置只表达业务结果，第二个位置携带可选的键、原因或提示。

官方地址：https://redis.io/docs/latest/develop/interact/programmability/eval-intro/

先把 Lua 脚本的返回值定成固定契约

以“只在键不存在时写入”为例，脚本需要区分三个业务结果：键已存在、写入成功、条件写入没有成功。它们都不是 Redis 连接故障，所以不应混在客户端的 error 分支里。

-- 统一返回 {状态码, payload}，让调用方只按位置读取业务结果
local exists = redis.call('EXISTS', KEYS[1])
if exists == 1 then
    -- 100 表示目标已经存在，payload 保留可读原因
    return {100, 'already-exists'}
end

local reply = redis.call('SET', KEYS[1], ARGV[1], 'NX', 'EX', ARGV[2])
if reply == 'OK' then
    -- 0 表示本次写入成功
    return {0, 'created'}
end

-- 200 表示条件写入未成立，不能被误判为 Redis 连接错误
return {200, 'not-created'}

这里的关键不是数字取什么，而是数字一旦发布就保持稳定。建议把 0 留给成功，把正数按业务边界分组，例如 100 段表示状态冲突、200 段表示条件未满足、900 段表示脚本内部错误。payload 可以是短字符串，也可以是明确约定的 ID，但不要让同一个位置一会儿返回字符串、一会儿返回数组。

用状态码把业务结果和 Redis 原生回复分开

Redis 脚本的返回值会经过 Lua 与 Redis 协议之间的类型转换。直接返回 redis.call('SET', ...) 时，客户端看到的只是 OK；直接返回 false 或空数组，也很难承载“没抢到”“版本不匹配”“对象已删除”等业务语义。

这张表就是跨语言边界：Lua 负责在 Redis 内原子地决定结果，Go、Java 或 Node 客户端只负责解码契约。这样即使把脚本从 EVAL 迁移到 Redis 7 以后的 Functions，业务层仍可以保留同一组状态码。

用 pcall 收口 Redis 错误与业务结果

redis.call 遇到 Redis 命令运行错误时会让脚本失败；redis.pcall 则把错误作为 error reply 交给脚本继续处理。可以只对确实需要转成业务契约的命令使用 pcall，避免把拼写错误或错误类型静默吞掉。

-- pcall 把可预期的 Redis 命令错误转成统一状态码
local result = redis.pcall('HSET', KEYS[1], ARGV[1], ARGV[2])
if type(result) == 'table' and result.err ~= nil then
    -- 900 表示脚本无法完成底层命令，payload 保持稳定
    return {900, 'command-error'}
end

-- HSET 的整数回复只在脚本内部使用，不暴露为业务状态
return {0, 'field-written'}

不要把所有错误都改成 {0, ...}。业务结果和执行错误的恢复策略不同：前者通常可以展示或按幂等规则继续，后者需要日志、告警或降级。另一个常见坑是 Lua 数组里的 nil 会造成后续元素无法按预期返回，所以 payload 没有值时使用约定字符串，或者明确返回固定长度的占位值。

客户端按类型解析，并把迁移检查写进清单

客户端不要直接把脚本结果断言成某个具体实现细节，而应先检查“是不是长度为 2 的数组”，再检查第一项和第二项。下面以 Go 客户端为例，代码展示解析思路，重点是拒绝破坏契约的回复。

type ScriptResult struct {
    Code    int64
    Payload string
}

func parseScriptResult(raw interface{}) (ScriptResult, error) {
    // 先确认脚本返回的是固定长度数组，避免越界和错误猜测
    items, ok := raw.([]interface{})
    if !ok || len(items) != 2 {
        return ScriptResult{}, fmt.Errorf("invalid lua result shape")
    }

    code, ok := items[0].(int64)
    if !ok {
        return ScriptResult{}, fmt.Errorf("invalid lua status code")
    }
    payload, ok := items[1].(string)
    if !ok {
        return ScriptResult{}, fmt.Errorf("invalid lua payload")
    }

    // 未知状态码不能默认为成功，交给上层决定兼容策略
    return ScriptResult{Code: code, Payload: payload}, nil
}

迁移旧脚本时可以先让客户端同时接受旧的 OK 和新的二元数组，但新脚本不要再返回两种形状。上线前至少检查以下几项：状态码表是否登记；所有分支是否返回两个元素；payload 是否避免 nil；pcall 只包住有明确恢复策略的命令；客户端遇到未知码是否默认失败；EVAL 与 Functions 切换时是否保留相同契约。

常见问题

状态码一定要用数字吗？

不一定，但数字便于跨语言比较和分段管理。若团队更重视可读性，也可以统一返回短字符串；关键是类型和含义不能在分支间变化。

业务失败要不要让 EVAL 返回 Redis error？

通常不要。条件不满足、资源已存在属于业务结果，返回结构化数组更适合幂等处理；只有命令执行异常或契约无法满足时，才进入错误处理路径。

为什么不直接返回 JSON 字符串？

JSON 适合承载复杂对象，但它增加编码、解析和字段兼容成本。只有当 payload 确实包含多层结构时才使用 JSON；简单结果优先保持二元数组契约。