Redis SCAN 怎样避免一次返回过多键

我在处理 Redis 键空间巡检时，最容易误判的一件事是把 COUNT 当成“本次最多返回多少个键”。正确理解是：COUNT 只是 Redis 对每次调用工作量的提示，不能当成严格的返回条数上限。要避免单次结果过大，应使用游标分批消费、按命名空间配合 MATCH，并把真正的限流放在客户端处理层。

Redis 官方命令地址：https://redis.io/docs/latest/commands/scan/

最稳妥的写法是从游标 0 开始，传入合适的 COUNT，处理当前批次后继续使用 Redis 返回的游标，直到游标再次变成 0。批次数量只能作为经验值，不能用来判断遍历是否完成。

先明确 SCAN 的返回模型

SCAN 每次返回两部分：下一次要使用的游标，以及当前找到的一批键。第一次调用的游标必须是 0，后续调用必须沿用上一轮返回的游标；当返回游标再次为 0 时，才表示完成了一次完整遍历。

这里的“分批”是服务端增量遍历与客户端增量处理的组合，不是把所有键先取回本地再切片。只要客户端在内存里积攒一个很大的数组，SCAN 带来的单次压力优势仍可能被抵消。

把 COUNT 当作工作量提示，而不是硬上限

Redis 文档给出的默认 COUNT 是 10。这个数字不是“最多 10 个键”，而是实现每轮工作量的提示。实际返回可能少于提示值，也可能多于提示值；某些情况下甚至可能返回空批次，但游标还没有结束。

因此，COUNT 的选择应该从客户端能承受的处理时间、单批业务操作数量和网络往返成本出发。下面的命令把 200 作为起始提示值，只表达调参意图，不保证每次正好返回 200 个键。

# 只遍历 cache: 命名空间；COUNT 是每轮工作量提示，不是返回条数上限。
redis-cli SCAN 0 MATCH 'cache:*' COUNT 200

# 下一轮必须使用上一条命令返回的游标，不要手写或重置成固定数字。
redis-cli SCAN  MATCH 'cache:*' COUNT 200

如果单批处理还包括网络请求、反序列化或删除操作，先把 COUNT 设得保守一些，再根据客户端耗时和 Redis 延迟调整。不要把“调大 COUNT 以减少往返”误解成“调大 COUNT 就能提高吞吐而没有代价”。

用 MATCH 缩小业务处理范围

MATCH 适合把键空间限定在明确的命名空间，例如 session:* 或 cache:product:*。但它不是一个先缩小物理扫描范围、再固定返回数量的分页器。官方说明中，匹配过滤发生在元素取出之后，所以模式很稀疏时，很多轮可能返回空列表。

# 只关注会话键；匹配不到时也要继续使用返回游标。
redis-cli SCAN 0 MATCH 'session:*' COUNT 100

# 这是业务过滤范围，不代表 Redis 每轮一定返回100个键。
redis-cli SCAN  MATCH 'session:*' COUNT 100

这也是为什么不能写成“返回空批次就结束”。正确结束条件只看游标是否为 0；空批次只是这一轮没有产出符合模式的键。

在客户端做增量消费和必要去重

如果使用 Python，可以通过 redis-py 的 scan_iter() 隐藏游标推进，但仍然要理解它的语义：迭代器是逐个产生键，不代表结果有序，也不代表同一个键绝不会再次出现。对删除、刷新缓存这类可重复执行的动作，可以直接按键处理；对只允许一次的副作用，应在业务层做幂等或去重。

import redis

# decode_responses 让示例直接得到字符串键，实际连接参数按环境配置。
client = redis.Redis(host="localhost", port=6379, decode_responses=True)

# count 只是提示值；scan_iter 会持续推进游标直到完成遍历。
for key in client.scan_iter(match="cache:product:*", count=100):
    # 单键处理，避免把整个键空间一次性装入列表。
    process_one_key(key)

# 任务结束后释放客户端连接；生产项目也可以交给连接池统一管理。
client.close()

如果任务要求严格控制客户端一次处理的数量，可以在消费层再加一个小批缓冲，例如收集 20 个键就提交一次，提交完成后清空缓冲区。这个上限属于你的业务批处理策略，不是 Redis SCAN COUNT 的语义。

为什么不能把 COUNT 当成上限

有两个边界很容易在压测或线上巡检中出现。第一，Redis 的键空间规模和内部结构会影响每轮实际返回量；第二，SCAN 允许返回 0 个元素，只有游标归零才能判断遍历结束。对很小的集合，SCAN 甚至可能一次返回全部键，这并不表示 COUNT 失效，而是说明 COUNT 本来就不是硬限制。

持续增长的键空间要设置业务截止点

SCAN 的完整遍历保证建立在元素在遍历开始到结束期间的存在状态上，但它不是一个带快照的静态分页器。遍历期间新增、删除或反复写入键时，应用仍需按文档语义处理重复和变化。对于持续增长且增长速度高于扫描速度的键空间，完整遍历可能迟迟无法自然结束。

所以，定时巡检、过期清理或缓存统计通常还需要业务截止策略，例如限定单轮最长处理时间、记录本轮开始时间、把游标保存到任务状态，或者把任务拆成更明确的命名空间。这里的截止策略解决的是业务调度问题，不能靠把 COUNT 改成某个大数来替代。

常见问题

COUNT=100 是否保证最多返回100个键？

不保证。它只是每轮工作量提示，返回数量可能少于、等于或多于100，甚至可能为0。

SCAN 返回空列表是不是已经遍历结束？

不是。必须继续使用返回游标；只有游标再次为0，才按完整遍历结束处理。

MATCH 会让 Redis 只扫描匹配的键吗？

不要把它理解成严格的物理范围裁剪。MATCH 过滤发生在元素取出后，稀疏模式可能产生多轮空批次。

怎样从根本上限制客户端一次处理的键数？

在客户端消费层设置自己的缓冲和提交批次，例如每处理固定数量后提交一次；不要把这个业务上限寄托在 SCAN 的 COUNT 参数上。

记住一句话：SCAN 负责用游标把遍历拆开，COUNT 负责提示每轮工作量，MATCH 负责筛选业务命名空间，而真正的单批处理上限要由客户端自己控制。