RedisLua分页查询实现技巧

Redis的Lua脚本因无状态特性无法在服务端维护SCAN游标，故不能实现真正的分页模糊查询；唯一可靠方案是客户端驱动SCAN分页（每次传入游标和数量），由Lua脚本仅负责单次扫描结果的模式匹配（支持glob或更灵活的string.find）与结果截取，兼顾原子性、安全性与可控性——既规避了KEYS的阻塞风险，又避免了在Lua中错误模拟分页导致的数据重复、遗漏和性能崩溃，特别适用于key命名含业务标识（如user:123:profile）且模糊规则简单的场景。

Redis Lua 脚本里不能直接用 SCAN 分页模糊查

Redis 的 Lua 环境不支持 SCAN 命令的游标状态维护，脚本执行是原子、无状态的，每次调用都是全新上下文。你没法在 Lua 里“记住上次游标”，也就没法靠 SCAN 实现真正的分页。常见错误是写个循环反复调 SCAN，结果每次从 0 开始扫，数据重复、漏掉、性能爆炸。

实际能走通的路只有一条：把模糊匹配逻辑下推到 Lua，用 KEYS 或 SCAN（由客户端驱动）预捞出候选 key，再在 Lua 里做字符串匹配和切片。但注意：KEYS 阻塞主线程，生产禁用；SCAN 必须由客户端分页调用，Lua 只负责单次结果过滤。

• 适用场景：key 名本身含业务标识（如 user:123:profile），且模糊规则简单（前缀/包含/后缀）
• 不要在 Lua 里尝试模拟分页逻辑，游标管理必须交还客户端
• 如果 value 里存了要模糊查的字段（比如 JSON 字符串），Lua 可以用 string.find 或 string.match 提取，但别指望它比 Redis 模块或外部索引快

用 SCAN + Lua 过滤实现安全分页

客户端控制分页节奏，每次传入游标和 page size，Lua 只做两件事：拉一批 key，按 pattern 过滤，再截取指定数量。这是唯一兼顾安全与可控的方式。

示例脚本（保存为 filter_scan.lua）：

local cursor = tonumber(ARGV[1])
local count = tonumber(ARGV[2])
local pattern = ARGV[3]
local limit = tonumber(ARGV[4])
local keys, new_cursor = redis.call('SCAN', cursor, 'MATCH', pattern, 'COUNT', count)
local result = {}
for _, key in ipairs(keys) do
if string.find(key, pattern, 1, true) then -- 全字面匹配，关闭通配
table.insert(result, key)
if #result >= limit then break end
end
end
return {new_cursor, result}

• SCAN 的 MATCH 是 glob 模式（*、?），不是正则；Lua 里的 string.find 才支持更灵活匹配
• 传入的 pattern 要前后一致：如果 SCAN 用 user:*:info，Lua 里 string.find 就别再加 ^ 或 $，否则失配
• count 不是返回条数，只是 SCAN 每次扫描的槽位上限，设太小会导致多次迭代；建议设为 limit × 2～5

为什么不用 redis.call('GET', key) 查 value 再匹配？

因为性能会断崖下跌。每次 GET 都是 O(1) 但有网络/序列化开销，批量查 N 个 key 就是 N 次操作。而 key 名模糊查，99% 场景只需要 key 本身——value 数据量大、结构深时尤其明显。

• 如果必须查 value，优先考虑在 key 设计阶段冗余信息，比如把用户名塞进 key：user:123:alice:profile
• 实在要解析 value，确保它是紧凑格式（如 msgpack 或短 JSON），并用 cjson.decode（需 Redis 7.0+ 启用 lua-time-limit 和 loadmodule 支持）
• 避免在 Lua 里用 string.match 解析长文本或嵌套 JSON，容易超时或 OOM

分页游标处理最容易被忽略的细节

SCAN 返回的 new_cursor 是字符串，不是数字。虽然多数情况是整数字符串（如 "0"、"12345"），但当遍历结束时，它可能返回 "0" —— 这和起始游标一样。仅靠 new_cursor == "0" 判断结束是错的，必须结合本次是否拿到结果来定。

• 客户端必须保存上一次的 cursor 和本次返回的 new_cursor，即使 new_cursor 是 "0"，只要本次 result 非空，就得继续下一轮
• Redis 官方 SCAN 文档强调：“游标为 0 仅表示‘可能’结束”，真实结束条件是：new_cursor == "0" 且 本次返回 key 数为空
• Lua 脚本里别对游标做算术运算（比如 +1），它本质是内部编码，不是序号

事情说清了就结束。

到这里，我们也就讲完了《RedisLua分页查询实现技巧》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！