Redis Functions 怎么替代需要重复加载的 Lua 脚本

如果应用每次调用 Redis Lua 逻辑都要重新发送脚本，或者只能依赖 SCRIPT LOAD 后的临时 SHA1 缓存，稳定脚本可以迁移成 Redis Functions。Redis 7.0 起支持把 Lua 函数注册到一个函数库中，由 Redis 保存并在客户端之间复用；应用只需要调用函数名，不再携带整段脚本。

官方文档：https://redis.io/docs/latest/develop/programmability/functions-intro/

先看清 EVALSHA 与 Redis Functions 的差别

EVAL 适合临时执行脚本，EVALSHA 通过 SHA1 减少重复发送脚本，但脚本缓存不是函数库。Redis 重启、脚本缓存被清空或客户端忘记重新加载时，应用仍要处理“脚本不存在”的分支。

Functions 把代码提升为 Redis 中的持久化软件对象：一个库有名字，库内可以注册多个函数，多个客户端都能按函数名调用。它适合订单状态校验、库存扣减、哈希字段联动这类逻辑稳定且需要原子执行的场景；临时调试脚本仍可保留 EVAL。

用 Lua 文件声明函数库和调用契约

下面的例子把“写入订单状态并记录修改时间”封装为 order_ops 库中的 mark_paid 函数。第一个参数是键名，后面的参数只是普通业务值，不能把普通参数误当成键。

#!lua name=order_ops

-- 只操作调用方显式传入的订单键，保证集群路由和调用契约清晰
local function mark_paid(keys, args)
  local order_key = keys[1]
  local paid_at = args[1]

  -- 用一次原子执行同时写状态和时间，避免两个命令之间被插入其他写入
  redis.call('HSET', order_key, 'status', 'paid', 'paid_at', paid_at)
  return redis.call('HGETALL', order_key)
end

-- 注册后的名字用于 FCALL，而不是 Lua 的局部函数名
redis.register_function('mark_paid', mark_paid)

文件开头的 shebang 给出引擎和库名，至少要注册一个入口。函数回调收到两个表：keys 对应键参数，args 对应普通参数。这样比在脚本内拼接键名更容易审查，也满足独立部署和集群路由的要求。

加载一次，再用 FCALL 重复调用

将库文件交给 Redis 后，客户端调用只保留函数名、键数量、键名和业务参数。首次加载或升级可以使用 REPLACE；没有它时，已存在同名库会加载失败。

# 将整个 Lua 函数库作为管理操作加载；-x 从标准输入读取文件内容
cat order_ops.lua | redis-cli -x FUNCTION LOAD REPLACE

# 1 表示后面只有一个键名，order:1001 进入 KEYS[1]
# 2026-09-27T08:00:00Z 是普通参数，进入 ARGV[1]
redis-cli FCALL mark_paid 1 order:1001 2026-09-27T08:00:00Z

# 查看库名和已注册函数，确认部署对象而不是依赖脚本 SHA1
redis-cli FUNCTION LIST

命令返回库名后，可以让应用在启动或发布阶段负责加载，让业务请求只执行 FCALL mark_paid 1 order:1001 ...。生产部署应把 Lua 文件纳入版本库，并记录加载成功与 FUNCTION LIST 的结果。

上线前处理只读、集群和回滚边界

Redis 会把函数执行视为原子操作，但原子不等于可以无限运行：函数执行期间会阻塞其他客户端，所以循环扫描大量数据或调用慢逻辑并不适合直接塞进函数。集群部署时，函数访问的所有键都必须由调用方显式传入，并遵守同一槽位等路由约束。

如果函数确实只读，可以注册 no-writes 标记，再考虑用 FCALL_RO 在只读副本上执行。不要仅因为函数当前分支没有写入就盲目使用只读调用；标记必须和库代码保持一致。升级时采用完整库替换，先在预发布环境加载新库并验证，再切换调用方；出现问题时回滚上一份完整库，而不是尝试只替换单个函数。

常见问题

Redis Functions 能完全替代 EVAL 吗？

不能。稳定且需复用的脚本适合 Functions，临时运维脚本或一次性实验仍可用 EVAL；两者可以并存。

为什么 FCALL 的 numkeys 不能随便写？

它决定哪些参数进入 KEYS，也让 Redis 在集群和只读执行时知道函数会访问哪些键。数量错误会导致参数错位或路由不安全。

FUNCTION LOAD REPLACE 会只更新一个函数吗？

不会。函数属于库，库按整体替换；发布时应把同一版本的全部函数一起加载，并保留上一版库作为回滚对象。