Go 中使用 go-redis 执行 Lua 实现原子操作

在 Go 中使用 go-redis 执行 Lua 脚本实现原子操作看似简单，实则暗藏诸多易踩坑点：从 Eval 调用时 keys/args 类型错配、Lua 下标越界、table 误传导致脚本崩溃，到 JSON 复杂结构序列化不当、返回值解包 panic，再到性能瓶颈与调试低效——本文直击核心痛点，手把手教你如何安全传参（严格分离 KEYS/ARGV、JSON 封装、显式类型接收）、高效复用（Script 封装自动管理 EVALSHA 与容错重载），以及快速本地调试（redis-cli --eval + redis.log），助你写出健壮、可维护、高性能的 Redis 原子逻辑。

为什么直接用 Eval 容易出错

Go 中通过 go-redis 执行 Lua 脚本最常踩的坑是：把脚本内容拼接进 Eval 调用里，导致参数未正确序列化、类型丢失或被 Redis 当作字符串字面量处理。Redis 的 Lua 环境不支持 Go 的 struct、map 等原生类型，所有传入值必须是 Redis 可识别的类型（string、number、table），且 KEYS 和 ARGV 是严格分离的。

常见错误现象：ERR Error running script (call to f_...): @user_script:1: attempt to concatenate a table value —— 本质是把 Go 的 slice 当成 Lua table 直接用了，没用 unpack() 或遍历。

• KEYS 只能传 key 名（字符串），不能传值；ARGV 传所有非 key 参数，包括数字、布尔、JSON 字符串等
• 脚本里访问 KEYS[1] 是合法的，但 KEYS[0] 会越界（Lua 数组下标从 1 开始）
• 如果脚本返回 nil，go-redis 会解包为 Go 的 nil，不是 interface{} 零值，注意判空逻辑

如何安全传参并解析返回值

核心原则：所有动态数据走 ARGV，用 JSON 字符串封装复杂结构；返回值统一用 redis.StringSlice、redis.Int 等显式类型接收，避免用泛型 interface{} 导致 panic。

例如实现「加库存并记录操作日志」原子操作：

const luaScript = `
local stock_key = KEYS[1]
local log_key = KEYS[2]
local delta = tonumber(ARGV[1])
local now = tonumber(ARGV[2])
local log_entry = ARGV[3]

local cur = redis.call("GET", stock_key)
if not cur then
  return {0, "stock_not_found"}
end
local new_stock = tonumber(cur) + delta
if new_stock 
调用时：

• client.Eval(ctx, luaScript, []string{"inventory:123", "log:123"}, -5, time.Now().Unix(), `{"op":"decr","by":5}`)
• 返回值用 redis.Values 接收，再手动 redis.String / redis.Int64 解包，不要依赖自动类型推导
• 注意 time.Now().Unix() 是 int64，传给 tonumber() 安全；但若传 float64，需在 Go 侧转成 int64 或字符串再进 ARGV

怎么复用脚本避免每次传输开销

频繁执行同一脚本时，每次都发完整 Lua 字符串浪费带宽且影响性能。Redis 支持 EVALSHA，先用 SCRIPT LOAD 缓存脚本，后续只传 SHA1 值。

go-redis 提供了 Script 类型封装该流程：

• 定义全局变量：var incrStockScript = redis.NewScript(luaScript)
• 调用：incrStockScript.Run(ctx, client, []string{"inventory:123", "log:123"}, -5, time.Now().Unix(), `...`)
• 首次运行自动 SCRIPT LOAD，后续复用 SHA；若 Redis 重启，第一次会失败并自动重试（内部处理）
• 不要自己拼 sha1.Sum([]byte(luaScript)).Hex() 后调 EvalSha —— Script.Run 已处理容错和重载

本地调试 Lua 脚本的实用技巧

别在 Go 里反复启服务测脚本。直接用 redis-cli --eval 模拟：

redis-cli --eval ./stock.lua inventory:123 log:123 , -5 1717028340 '{"op":"decr","by":5}'

注意逗号前后空格：逗号前是 KEYS，逗号后是 ARGV。调试时可在脚本里加 redis.log(redis.LOG_WARNING, "debug:", ...)，日志输出到 Redis 的 redis-server stdout（需配置 loglevel warning）。

容易被忽略的是：Redis 的 Lua 不支持 os.time() 或 math.random()（禁用系统调用），时间必须由 Go 传入；也不支持 require，所有逻辑必须内联。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~