登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  数据库 >  Redis

Redis Functions 怎样把脚本按库管理并调用

来源:17golang原创

时间:2026-11-16 19:17:02 269浏览 收藏

Redis Functions 把 Lua 代码作为函数库部署到服务端:文件首行声明库名,代码用 redis.register_function 注册入口,部署时执行 FUNCTION LOAD,业务请求用 FCALL 函数名 键数量 ... 调用。更新时通过 FUNCTION LOAD REPLACE 提交整库定义,不能只上传其中一段函数体。

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

先决定哪些逻辑交给函数库

假设多个服务需要按同一规则给一个 Hash 写入标签。将这个小操作做成函数入口,可以把调用协议集中管理;客户端只传键名、字段和值。本文用这一场景说明库文件、加载命令和调用方之间的分工,不把完整业务系统搬入 Redis。

方案适用场景需承担的运维工作
普通 Redis 命令单条命令已经表达完整操作维护调用参数
EVAL / EVALSHA代码随应用管理的脚本维护脚本内容及缓存缺失处理
Functions多个调用方依赖稳定命名入口维护库版本、部署范围及接口兼容

示例的单次 HSET 本身无需 Functions 才能完成;这里增加参数约定,是为了展示可维护的库结构。选型时应先判断统一入口带来的收益是否值得增加发布管理工作,而不是为了使用新能力包装每条命令。

明确库名与函数名的约束

Functions 从 Redis 7 开始提供。库名是部署与替换的单位,对外函数名是调用入口;函数名不能依靠不同库名来区分同名入口。因此建议给函数名加入业务前缀,例如库 demo_labels 注册 demo_labels_put。

在架构上可分成两组:发布资产包括完整 Lua 文件、库名和已注册入口;业务调用包括 FCALL、键列表和普通参数。不要让每个请求都负责加载库,也不要把部署权限混进所有业务服务。

函数库发布资产与业务调用入口的静态结构关系
图1:结构图。库文件、库名和注册入口属于发布资产,FCALL 通过函数名关联入口;连线不表示部署时序。

写一个有输入检查的 Lua 库

保存以下完整内容为 demo_labels.lua。第一行必须是库元数据,中文注释放在下一行。入口接受一个键和两个普通参数;先检查数量,再执行一次写入。

#!lua name=demo_labels
-- 在任何写操作前检查参数,函数入口只接受一个键
local function put_label(keys, args)
    if #keys ~= 1 or #args ~= 2 then
        return redis.error_reply('ERR expected one key and two arguments')
    end
    if args[1] == '' then
        return redis.error_reply('ERR field must not be empty')
    end
    -- 字段和值属于普通参数,键名必须从 keys 显式传入
    return redis.call('HSET', keys[1], args[1], args[2])
end

-- 对外函数名加入业务前缀,库名不充当调用命名空间
redis.register_function('demo_labels_put', put_label)

keys[1] 是目标 Hash 的键名,args[1] 是字段,args[2] 是值。函数访问的键应通过键参数显式提供,不能把真正的键名藏在普通参数中。put_label 是库内 Lua 函数,只有注册后的 demo_labels_put 才作为对外入口。

检查放在写操作前,有助于避免参数问题导致部分操作已经发生。执行期间不会穿插其他客户端命令,不等于运行错误会自动撤销此前写入;如果将来增加多条写操作,应重新审视失败位置与数据约定。

用 FUNCTION LOAD 加载并以 FCALL 调用

# 将上面的完整内容保存为 demo_labels.lua,首行保持 shebang
# 在隔离实例加载;-x 将标准输入作为最后一个命令参数
redis-cli -x FUNCTION LOAD 

这些是供读者在隔离实例使用的命令示例,没有附本机执行记录。加载成功时返回库名;FCALL 的返回值取决于函数,此例直接返回 HSET 的回复。读取演示字段用于确认写入内容,不能单凭一个整数判断所有业务条件都满足。

调用中的 1 是键的数量,不是函数参数总数。紧随它的 demo:labels:article 进入键列表,后面的 category 与 redis 进入普通参数列表。连接错误、权限错误、库尚未部署和函数返回的参数错误,需要分别保留上下文。

FCALL 的函数入口键列表和普通参数对应关系
图2:说明图。键数量界定键列表,字段和值归入普通参数,入口使用两类输入调用 HSET;图示不是终端输出。

加载命令:https://redis.io/docs/latest/commands/function-load/

调用命令:https://redis.io/docs/latest/commands/fcall/

把库替换纳入部署和回退

# 将同一库的完整新定义保存为 demo_labels.lua 后执行替换
redis-cli -x FUNCTION LOAD REPLACE 

REPLACE 以整库为单位,所以新文件必须保留仍被使用的全部注册入口。不能把只含新函数的文件当作补丁,也不能把“加载命令成功”当作客户端参数和返回结构仍然兼容的证明。建议把完整旧文件与新文件作为发布产物保存,并记录各调用方依赖的入口。

对于不兼容接口,可以选择新的库名以及新的函数名前缀并行部署,再迁移调用方;只改库名而继续注册旧函数名不能提供独立命名空间。回退库代码也不会撤销已经发生的业务写入,数据兼容需要单独设计。

Redis Cluster 的库部署范围需要纳入运维计划,不能假设对一个主节点加载就代表所有分片都已部署。全量重建的临时缓存实例,也需要有应用开放流量之前的库恢复安排。函数执行会占用服务端执行时间,入口应保持短小,避免长循环和不受控的大数据遍历。

落地清单与常见问题

落地时先固定入口名、键数量、普通参数顺序和返回语义,再把完整库文件加入发布产物。部署职责与业务调用职责分开;替换前准备兼容方案和旧文件。业务服务启动时应能报告函数未部署这一依赖问题,避免每个请求都尝试修改库。

FCALL 需要写成“库名.函数名”吗?

直接使用注册的函数名即可。示例使用 demo_labels_put 是应用自行规定的前缀,并非 Redis 自动拼接出来的名称。

能只替换一个函数吗?

库更新提交完整定义。把仍在使用的入口从新文件中遗漏,会影响旧调用方,因此应把整库当作部署单位。

调用时还需要传脚本 SHA 吗?

FCALL 按注册名调用,不使用 EVALSHA 的脚本摘要协议。客户端仍需知道函数何时部署、接口是否兼容以及失败如何处理。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>