Redis Lua 库存扣减接口怎么设计：区分成功、重复请求和库存不足

订单服务发生重试时，库存接口很容易把“已经扣过”的请求误判成“库存不足”，这类问题比少扣一件商品更难排查：调用方根本搞不清当前是该重试补偿，还是直接把订单标记为失败。Redis Lua 库存扣减接口最好在一次原子操作里完成参数校验、幂等判断和库存修改，统一返回一组含义清晰的业务码。

推荐把结果固定为 0（成功）、1（重复请求）、2（库存不足）、3（参数错误），Go 服务端再把它们映射成明确的 HTTP 响应；不要让调用方猜 Redis 返回的字符串。

先把 Redis 库存接口的结果说清楚

一个库存扣减接口至少要对应四种明确状态。成功状态要留下扣减后的剩余数量，重复请求状态要告诉调用方之前已经处理过同一条请求，库存不足的状态不能和系统故障混为一谈，参数错误这类问题最好在进入 Redis 前就直接拦住。

这里的关键不是码值本身，而是码值一旦对外发布就不能随意改动。Redis 返回数组时，第一项放业务码，第二项放剩余库存，第三项放已生成的订单号或空字符串，客户端就能用同一套解析逻辑处理所有四种结果。

Lua 脚本怎样同时检查幂等键和库存键

假设库存键是 stock:sku:10086，幂等键是 stock:req:order-20260727-001。脚本优先校验幂等键，再读取库存数值，最后写入幂等处理结果。两个键必须位于同一个 Redis 实例；如果使用 Redis Cluster，调用时要保证它们落到同一哈希槽，可以把订单号放进花括号做哈希标签，例如 stock:{order-20260727-001}:qty。

local stockKey = KEYS[1]
local requestKey = KEYS[2]
local count = tonumber(ARGV[1])
local orderNo = ARGV[2]

if not count or count 

脚本把幂等记录写在库存扣减操作之后，两个步骤不会被其他 Redis 命令插入打断。如果客户端在响应返回前断网，下一次带相同请求键访问时会得到 1 的返回码，不会再次扣减库存。幂等记录的过期时间要覆盖订单最长重试窗口，不能只按接口超时时间设置。

Go 调用方的参数与错误模型

Go 服务端不要把 Redis 的原始返回数组直接暴露给上游 HTTP 客户端。先校验商品编号、购买量和请求号的合法性，再把四种业务码转成结构稳定的 JSON 响应。HTTP 409 可以用来标识库存不足，重复请求则返回 200 状态并带上 duplicate 标记；这样后端的重试组件不会把已经处理完成的订单推回失败队列。

type StockReply struct {
    Code      int    `json:"code"`
    Remain    int64  `json:"remain"`
    OrderNo   string `json:"order_no,omitempty"`
    Duplicate bool   `json:"duplicate,omitempty"`
}

func mapStockResult(values []interface{}) (StockReply, int) {
    code := int(values[0].(int64))
    reply := StockReply{Code: code}
    if len(values) > 1 { reply.Remain = values[1].(int64) }
    if len(values) > 2 { reply.OrderNo = string(values[2].([]byte)) }
    switch code {
    case 0:
        return reply, 200
    case 1:
        reply.Duplicate = true
        return reply, 200
    case 2:
        return reply, 409
    default:
        return reply, 400
    }
}

实际项目里还要处理 Redis 连接失败、脚本返回类型异常和 JSON 序列化失败这类情况。这些都属于系统内部错误，不能伪装成库存不足的业务状态。日志至少要记录请求号、商品键、购买量、业务码和耗时，不要把完整用户信息直接塞进幂等键。

脚本升级与兼容边界

往返回数组里增加字段，通常比直接修改原有码值更安全。旧客户端只读取前三项内容时，新脚本可以把第四项作为调试信息或版本号使用；不要把原有含义为“库存不足”的 2 改成代表“库存冻结”。升级时先让服务端同时兼容新旧两个脚本的返回结果，再切换到新版本脚本，最后观察线上重复请求率和错误码的分布是否符合预期。

还有两个边界场景很容易被忽略：库存键不存在时要明确返回码是代表库存为 0 还是底层数据异常；幂等键过期后同一订单号再次发起请求，是否允许重新扣减库存。针对普通订单场景，更建议在业务库中给订单号也加上唯一约束，Redis 只负责扛住高并发窗口的扣减请求，不能单独承担最终一致性的全部责任。

常见问题

Redis Lua 返回业务码的情况下，HTTP 状态码还有必要单独设置吗？

有必要。业务码描述库存操作的具体结果，HTTP 状态码能帮助网关、重试器和监控系统做通用的流量处理，两者负责的维度完全不同。

幂等键应该设置多长的过期时间？

至少要覆盖订单服务的最长重试和补偿周期。如果支付回调可能延迟 24 小时，幂等记录肯定不能只保留几分钟就自动删除。

Redis Cluster 可以直接在脚本里使用两个键吗？

只有两个键位于同一个哈希槽时才能在一个脚本里正常处理。给两个键设置相同的 hash tag，并且在压测环境提前验证路由规则是否符合预期。

库存不足能不能直接返回 500 状态码？

不建议。库存不足是可以预期的正常业务结果，返回 409 或者约定好的业务响应即可；Redis 本身的连接故障才应该进入 5xx 状态和对应的告警链路。

结语：稳定的返回语义比少写几行代码重要

Redis Lua 解决的是并发场景下的原子性问题，接口设计解决的是调用方能不能做出正确后续动作的问题。把 0、1、2、3 的含义固定下来，让幂等判断和库存修改处在同一个脚本里执行，再用 Go 层把系统错误和业务结果做明确隔离，库存接口才能真正做到可重试、可监控、可平滑升级。