Redis Functions 和 Lua 脚本升级时如何保持调用名

我在把一段长期用 EVALSHA 调用的 Lua 逻辑迁到 Redis Functions 时，最先遇到的不是语法问题，而是名称混在了一起：业务代码里的调用名、Functions 的库名，以及脚本缓存返回的 SHA1 根本不是同一层。升级时真正要保持的是公开的 function name；库可以整体替换，脚本则要单独处理缓存命中。

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

先把库名、调用名和 SHA1 分开

Redis Functions 的库代码必须以类似 #!lua name=order_lib 的 shebang 开头，库里再用 redis.register_function('order_total', callback) 注册入口。客户端调用的是 FCALL order_total，不是 FCALL order_lib。库名主要服务于加载、列举和删除；function name 才是业务 API。

旧式 Lua 脚本则走另一条路径：SCRIPT LOAD 返回脚本文本的 SHA1，客户端把它交给 EVALSHA。只要脚本内容改了，SHA1 就可能改变；Redis 也可能因为重启、故障转移或 SCRIPT FLUSH 丢失脚本缓存。因此迁移清单应至少有三列：业务调用名、Functions function name、脚本 SHA1，不能只记一个“脚本名”。

用整库替换保持 FCALL 调用名

Functions 的库内容按整体更新，不能只替换库中的某一个函数。升级时把新实现放回原来的注册名，例如继续注册 order_total，然后加载完整库：

# 新库必须保留业务侧依赖的注册名，再一次性替换同名库
redis-cli --raw FUNCTION LOAD REPLACE "$(cat order_lib_v2.lua)"

# 先列出库和函数，确认管理名与调用名没有写反
redis-cli FUNCTION LIST

# 用固定测试键验证公开 function name 仍可调用
redis-cli FCALL order_total 1 order:demo

REPLACE 只对同名 library 生效；如果新代码把 order_total 注册到另一个库，而旧库仍存在，可能遇到跨库函数重名错误。这个错误不能靠换一个库名掩盖，应该先确定哪个库是正式归属，再一次性发布完整实现。

给旧 Lua 调用留出兼容窗口

如果业务还没有全部切到 FCALL，不要在同一个发布动作里顺便假设旧脚本 SHA1 永远有效。脚本内容不变时，可以继续使用原 SHA1；内容变更后先加载新脚本，并让客户端在 NOSCRIPT 时重新加载再重试：

# 脚本内容发生变化时，先得到新版本的 SHA1
NEW_SHA=$(redis-cli SCRIPT LOAD "$(cat order_legacy.lua)")

# 只检查脚本缓存是否命中，不把它当成 Functions 库状态
redis-cli SCRIPT EXISTS "$NEW_SHA"

# 命中后仍由 EVALSHA 执行，调用名与 FCALL 的 function name 是两套 API
redis-cli EVALSHA "$NEW_SHA" 1 order:demo

迁移期可以让客户端同时认识 FCALL order_total 与旧的 EVALSHA，但两条路径必须使用同一套参数约定和测试键。先灰度 Functions，再下线旧脚本，回滚时也只回滚实现版本，不要随意改公开调用名。

升级后的检查表要看四个结果

这里最值得保留的是名称映射表，而不是某一次发布命令。Redis 官方文档说明 Functions 属于数据库并按库整体更新，而脚本缓存是临时的；把两者分开记录，升级和故障恢复都会更容易。

常见问题

改了 library name，FCALL 名称会一起改变吗？

不会自动改变。FCALL 使用注册的 function name；但改库名会影响加载、列举和删除，且新旧库并存时要重新处理函数归属。

Functions 能像 Lua 脚本一样用 SHA1 调用吗？

不能把两套机制等同。Functions 用注册名配合 FCALL，SHA1 是 SCRIPT LOAD/EVALSHA 脚本缓存的标识。

为什么 FUNCTION LOAD REPLACE 仍然报函数重名？

REPLACE 替换同名 library，不允许新库中的函数名与其他库已有函数冲突。检查全部库的注册入口后再决定库归属。

升级时怎样降低回滚风险？

保持 function name 和参数契约不变，先做固定键灰度，对照返回值与错误类型；旧脚本保留兼容窗口，确认新库稳定后再清理。