Redis Lua 脚本里的 tonumber 返回 nil：ARGV 类型转换、空值分支与线上验收

库存扣减脚本上线后，最难排查的一类报错往往不是 Redis 连接失败，而是 Lua 里一个看似普通的数字转换操作：tonumber(ARGV[2]) 得到 nil。调用方以为自己传了数值3，实际可能传了空字符串、写错了参数位置，或者把带单位的文本塞进了数量参数里。

不要直接把 tonumber 的返回值拿来做运算，提前校验转换结果再走后续逻辑，绝大多数线上这类隐式转换故障都能提前拦住。

tonumber 为什么会在 Redis Lua 里返回 nil

Redis 的脚本调用把键放在 KEYS，把业务参数放在 ARGV。Lua 脚本收到的参数本质上是字符串，ARGV[2] 只有在内容能被正常解析为数字时，tonumber(ARGV[2]) 才会得到有效数值。

下面几种输入都会让转换结果不适合直接参与运算：

最小库存扣减逻辑：先转型，再校验

假设 KEYS[1] 是库存 key，ARGV[1] 是扣减数量，ARGV[2] 是请求幂等号。不要把转型和扣减逻辑写成一行，先把输入边界的判断写清楚，后续脚本才容易做分支验收。

local stockKey = KEYS[1]
local amountText = ARGV[1]
local requestId = ARGV[2]

if not stockKey or stockKey == '' then
    return {0, 'missing_key'}
end

local amount = tonumber(amountText)
if not amount then
    return {0, 'invalid_amount'}
end
if amount 

这里的关键不在于 tonumber 本身，而在于它后面紧跟着 if not amount。Lua 中 nil 参与后续比较或减法会失去明确语义；提前返回业务错误，调用方才能清晰区分“参数错误”和“库存不足”两种不同场景。

参数顺序错了，脚本也可能表现出类似转换失败的现象

调用端如果把请求号放在第一个参数位置，脚本仍然会正常收到字符串，只是 ARGV[1] 不再代表扣减数量。这个问题很容易被误判成 Redis 或 Lua 的底层类型问题。

redis-cli --ldb-payload deduct.lua 1 stock:item:42 3 req-20260809-001
# 通过客户端脚本接口提交：1 个 key，随后才是 amount=3、requestId=req-20260809-001

验收时提前固定参数契约：第一个 key 是库存键，第一项参数是整数数量，第二项参数是非空请求号。不要让业务代码依赖“某个 SDK 恰好会自动转型”这类不确定特性。

返回数组要覆盖成功、坏参数和库存不足三类场景

脚本执行成功不等于业务逻辑执行成功。建议把返回值设计成稳定的数组：第一个元素是 0/1 状态位，第二个元素是机器可直接判断的短码，后面再放剩余库存或请求号等诊断字段。

redis-cli SET stock:item:42 10
redis-cli --ldb-payload deduct.lua 1 stock:item:42 3 req-20260809-001
# 1) (integer) 1
# 2) "deducted"
# 3) (integer) 7

redis-cli --ldb-payload deduct.lua 1 stock:item:42 '' req-20260809-002
# 1) (integer) 0
# 2) "invalid_amount"

redis-cli --ldb-payload deduct.lua 1 stock:item:42 99 req-20260809-003
# 1) (integer) 0
# 2) "not_enough_stock"

三次调用分别验证输入校验、正常扣减和库存不足三个分支。每次调用后再执行一次 GET stock:item:42，确认坏参数与库存不足分支都没有修改库存的实际值。

生产边界：数字转换通过，也不代表可以直接扣减

• 数量必须是正整数；金额、比例等小数场景不要复用库存脚本的整数校验规则。
• 库存 key 读取为空时要有明确处理策略。示例按 0 处理，但库存初始化缺失的场景也可以单独返回 missing_stock。
• 幂等号只有被记录或实际参与去重才真正有效；仅把它原样返回并不能防止重复扣减。
• 脚本只应操作传入的 key，调用方不要把用户输入直接拼进 Lua 源码。

常见问题

ARGV 里的数字需要在客户端先转成整数吗？

客户端可以先做参数校验，但 Lua 端仍应再次用 tonumber 检查，因为脚本边界不能默认所有调用方都遵守类型约定。

tonumber 返回 nil 时能不能当成 0 处理？

库存扣减场景不建议这样做。把坏参数静默变成 0 会掩盖调用错误，应该返回明确的 invalid_amount。

为什么库存不足后还要复查 GET？

因为返回码只说明脚本走到了对应分支，复查 key 才能确认失败路径没有产生意外副作用，特别适合上线验收和故障回放场景。

把验收标准固定下来

Redis Lua 里的 tonumber 是输入边界校验点，不是容错魔法。先检查参数是否存在，再确认转换结果、整数范围和业务状态，最后用返回码与实际 key 值双重核对。这样即使调用方传入空字符串或参数顺序错位，问题也会停在可读的业务错误上，而不是变成一条难以定位的 Lua 类型异常。