Redis Functions 怎么用 FCALL 调用版本化逻辑

Redis Functions 的版本化，第一原则不是给 library 名称加版本后就结束，而是先确定 FCALL 最终调用哪个函数名。FCALL 的第一个参数是函数名，不是“库名.函数名”；所以要让两个版本同时可调用，函数名本身也必须不同，例如 cart_quote_v1 与 cart_quote_v2。

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

使用场景：版本究竟要由谁选择

Redis 7.0 起提供 Functions。函数随数据库持久化和复制，应用不必像 EVAL 那样每次发送脚本，但它也意味着函数部署变成数据库侧的发布动作。决定方案前，先回答三个问题：旧版要不要继续在线；调用方能不能修改函数名；回滚是重新加载代码，还是只切一个配置。

还要分清两个命名空间。library 负责打包一组函数，可由 FUNCTION LIST、FUNCTION DELETE 管理；FCALL 却只接收函数名。官方文档也说明，每个函数拥有唯一的用户定义名称，library 不能只更新其中一个函数，而是整体更新。

三种版本切换方案放在一起比较

同名覆盖适合兼容升级。library 头保持 #!lua name=cart_logic，函数仍注册为 cart_quote，发布时执行：

redis-cli -x FUNCTION LOAD REPLACE 

REPLACE 只允许替换同名 library，且整个 library 一起更新。它不是双版本方案；如果新逻辑异常，需要用同样的命令重新加载已留存的旧文件。

版本函数并存适合需要灰度的业务。可把两个版本放进两个 library，但函数名也要区分，因为新 library 如果注册了已存在的函数名，即使使用 REPLACE 也会报冲突。调用方根据配置选择 cart_quote_v1 或 cart_quote_v2。

稳定入口路由适合无法频繁改客户端配置的场景。library 内保留两个 Lua 局部实现，只注册一个公开函数 cart_quote，从普通参数中读取版本标记后调用对应局部函数。它让 API 名称稳定，但部署新路由表仍要整体替换 library。

推荐方案：并行注册 v1 与 v2

下面用购物车报价举例。为了让旧版与新版真正共存，library 名和注册函数名都加版本。示例只访问调用方明确传入的购物车 key，不在函数内部拼接隐藏 key。

#!lua name=cart_v2

local function quote_v2(keys, args)
  local cart_key = keys[1]
  local discount = tonumber(args[1]) or 0
  local subtotal = tonumber(redis.call('HGET', cart_key, 'subtotal') or '0')
  local total = math.max(0, subtotal - discount)
  return { subtotal, discount, total }
end

redis.register_function{
  function_name = 'cart_quote_v2',
  callback = quote_v2,
  description = '购物车报价 v2：返回小计、优惠和合计'
}

加载文件后，用 FUNCTION LIST 确认 library 和函数都存在，再调用 v2：

redis-cli -x FUNCTION LOAD 

numkeys 不是装饰参数。上例的 1 表示后面正好有一个 key，Lua 回调会在 keys[1] 收到它，余下的 20 才进入 args。在 Redis Cluster 中，函数访问的所有 key 都必须显式传入；多 key 调用还要满足同槽要求。

给并行版本划清发布边界

正式切换不要把版本写死在每个业务分支里。更稳妥的做法是让应用配置保存当前函数名：

REDIS_CART_QUOTE_FUNCTION=cart_quote_v2

客户端把这个值放到 FCALL 的 function 参数中。先让少量实例使用 v2，确认返回结构、错误率和数据写入语义，再扩大范围；出现问题时只把配置切回 cart_quote_v1。这里的快速回滚成立有一个前提：v2 没有写入 v1 无法理解的数据。如果数据模型已经变更，函数回滚必须和数据兼容策略一起设计。

上线前至少核对这些静态资产：

• FUNCTION LIST LIBRARYNAME 'cart_v*' 能看到预期 library、函数名和说明。
• v1、v2 的 numkeys 契约一致，所有 key 都由调用方显式提供。
• 返回值结构要么兼容，要么由客户端按版本解析，不能只替换实现却悄悄改变协议。
• 保留旧函数和回滚配置，稳定后再执行 FUNCTION DELETE cart_v1。

什么时候不该选并行版本

如果所有调用方必须同步升级，而且旧函数会写入与新版冲突的数据，并行版本反而扩大风险；这时同名覆盖配合维护窗口更简单。如果版本只差一个小参数，长期保留多份函数会制造重复代码，稳定入口路由更合适。

另外，Functions 的执行是原子的，执行期间会阻塞 Redis 的其他活动。版本化不会改变这一点。不要因为逻辑已经“像服务一样部署”就把耗时循环、无界扫描或外部等待塞进函数；v1 与 v2 都应保持短小，并在发布前确认最坏输入边界。

决策表：按回滚方式选方案

多数需要“版本化逻辑”的团队，我会优先选择版本函数并存：它把版本选择变成显式的 API 决策，回滚不依赖再次上传文件。等新版稳定后，再删除旧 library，避免 Functions 列表无限增长。

常见问题

FCALL 能写成 cart_v2.cart_quote 吗？

不能把 library 名当成命名空间传给 FCALL。命令接收的是已注册函数名；需要并行版本时，应注册不同的函数名。

FUNCTION LOAD REPLACE 能只替换一个函数吗？

不能。Redis Functions 的 library 内容作为整体更新，不能选择性替换其中一个函数。

版本函数可以自己拼接要访问的 key 吗？

不应这样做。所有被函数访问的 key 都应在 FCALL 的 key 参数区显式提供，尤其在 Cluster 中这是正确路由的基础。

v2 稳定后什么时候删除 v1？

在所有调用方都完成切换、回滚窗口结束、数据格式仍可恢复后再删除。删除前先用 FUNCTION LIST 核对 library 名，避免误删当前版本。