Redis FCALL_RO 怎样调用只读函数

Redis 7.0 及以上可以把 Lua 函数注册为只读函数，再用 FCALL_RO 调用。关键不在命令名本身，而在函数注册时明确写入 no-writes 标记，并保证回调只调用不会修改数据的 Redis 命令。这样，函数才有资格被路由到只读副本；如果函数仍被 Redis 视为可能写入，FCALL_RO 会直接拒绝。

官方地址：https://redis.io/docs/latest/

最小做法是：给函数注册项增加 flags = { 'no-writes' }，在回调中只读取 KEYS 指定的键，再用 FCALL_RO 函数名 numkeys ... 调用。numkeys 前面的参数是函数名和键数量，随后恰好 numkeys 个值进入 KEYS，剩余值进入 ARGV。

• FCALL_RO 是 FCALL 的只读变体，Redis 7.0 引入。
• 函数默认按可能写入数据处理，必须用 no-writes 明确声明只读能力。
• 只读函数可以在只读副本上执行，但不能调用会修改数据集的命令。
• 函数仍然是 Redis 内部的原子执行单元，执行时间过长会阻塞其他客户端。

为什么普通函数不能直接用 FCALL_RO

Redis Functions 的安全边界是“先按可能写入处理，再由函数声明缩小权限”。函数注册时如果没有 no-writes 标记，Redis 无法仅凭函数名判断回调是否会修改数据，因此会把它当成可读可写函数。此时用 FCALL_RO 调用，常见结果是类似 ERR Can not execute a function with write flag using fcall_ro. 的拒绝。

这不是 FCALL_RO 的参数顺序问题，也不是只读副本暂时不可用，而是函数本身的声明与调用方式不匹配。先检查注册项，比反复修改客户端命令更有效。

注册一个真正只读的 Redis Function

下面的库注册了一个读取哈希字段的函数。示例只用 redis.call('HGETALL', KEYS[1]) 读取键，并通过命名参数形式声明 no-writes。代码中的注释说明了函数边界和参数来源。

#!lua name=readonly_library

-- 只读取 KEYS[1] 对应的哈希，不在函数中修改数据。
local function read_profile(keys, args)
    -- KEYS 由调用命令的 numkeys 划分，ARGV 保留给可选业务参数。
    return redis.call('HGETALL', keys[1])
end

-- no-writes 让 Redis 知道该函数可以由 FCALL_RO 调用。
redis.register_function{
    function_name = 'read_profile',
    callback = read_profile,
    flags = { 'no-writes' }
}

函数库是 Redis 中的一等对象，先加载后才能被客户端调用。部署时应把库文件当作版本化配置管理，避免只在某一台实例上手工加载。

# 将只读函数库加载到 Redis；部署脚本应记录加载失败并停止后续调用。
redis-cli -h 127.0.0.1 -p 6379 -x FUNCTION LOAD REPLACE 

numkeys 怎样划分 KEYS 和 ARGV

FCALL_RO 的语法是 FCALL_RO function numkeys [key ...] [arg ...]。其中 numkeys 不是函数参数，而是 Redis 用来切分调用参数的边界：紧随其后的前 N 个值成为 KEYS，剩余值成为 ARGV。函数读取哪个键，应该明确放进 KEYS，不要把键名藏在普通参数中。

# numkeys=1：profile:42 进入 KEYS[1]，summary 进入 ARGV[1]。
# 该函数当前没有使用 ARGV，但保留它能让调用契约清楚可扩展。
redis-cli FCALL_RO read_profile 1 profile:42 summary

上面的调用中，函数名是 read_profile，1 表示只有一个键名，profile:42 是 KEYS[1]，summary 是 ARGV[1]。如果把 numkeys 写成 0，函数就不会得到这个键名；如果写得比实际键数量大，后续值会被错误地当作键。

把 FCALL_RO 放到只读副本路由上

只读函数的一个实际用途是把查询逻辑交给只读副本处理。客户端或代理需要具备读写路由能力，并且要明确把这类调用标记成读请求；单独把命令改成 FCALL_RO，不会自动替客户端完成拓扑发现、故障转移和一致性策略。

在主副本上，FCALL_RO 仍然可以执行；在只读副本上，它提供了比普通 FCALL 更明确的只读契约。函数内部仍不能调用 HSET、DEL、INCR 等写命令，也不要把 PUBLISH、SPUBLISH 或 PFCOUNT 当成普通读取命令使用，因为 Redis 文档将它们视为脚本写命令。

读副本可能存在复制延迟，因此只读路由适合允许读取稍旧数据的查询，不适合紧接着写入后必须立刻读到最新值的流程。是否采用副本，应由业务的新鲜度要求决定。

常见拒绝原因和处理边界

函数没有 no-writes 标记

这是最常见的原因。重新加载包含 flags = { 'no-writes' } 的完整函数库，再调用 FCALL_RO。函数库整体替换时，要把所有函数一起纳入部署内容，不要只在客户端假设某个函数已经更新。

回调调用了写命令

no-writes 是约束，不是绕过权限的开关。即使注册项带有该标记，只要回调尝试修改数据，Redis 也会拒绝相应命令并返回错误。需要更新数据时，应改用 FCALL 并把请求路由到可写主副本。

把函数写成慢查询

Redis Function 的执行具备原子性，同时会阻塞服务器上的其他活动。只读并不等于可以无限运行。读取大集合、遍历大量元素或在 Lua 中做长循环，都应该拆小查询、限制输入规模，并把耗时纳入容量评估。

把只读副本当成强一致查询节点

只读副本的价值是分担读取压力，而不是消除复制延迟。登录态、库存扣减、刚完成的写操作等场景通常需要继续访问主副本，或由业务显式设计读后校验。

最后记住这四个判断

相关问题

FCALL_RO 从哪个 Redis 版本开始支持？

Redis 官方命令文档将 FCALL_RO 标记为 Redis 7.0.0 起可用；低于该版本的环境不能按本文方式注册和调用 Redis Functions。

FCALL_RO 能否调用普通 FCALL 注册的函数？

不能把“函数已注册”当成“函数只读”。只有声明 no-writes 且回调没有写入行为的函数，才适合使用 FCALL_RO。

numkeys 为什么必须写对？

它决定 Redis 把哪些调用值放进 KEYS。数量错误会让函数读取错误的键，或者让本来属于 ARGV 的值被当成键名。

FCALL_RO 会自动选择最近的副本吗？

不会。它提供只读调用语义，具体连接到主副本还是只读副本，仍由客户端、代理或服务发现层的路由策略决定。