Redis SCAN遍历大Key空间并避免阻塞的实践

Redis 里想找一批业务 key，第一反应不应该是 KEYS *。当 keyspace 较大时，一次性扫描会把大量工作压在 Redis 主线程上，业务延迟容易出现尖峰。更稳妥的做法是用 SCAN 保存游标，按批取 key，再把每批交给可重复执行的业务处理器。

先把 SCAN 写成可暂停的游标循环

一次完整遍历的边界很简单：请求使用游标 0 开始，Redis 每次返回一个新游标和一批元素，把新游标原样传给下一次调用，直到新游标再次变成 0。不要用“本次返回数量小于 COUNT”判断结束，因为服务端允许返回空批次。

例如只处理订单缓存，可以用 MATCH order:* 缩小候选范围，再用 TYPE string 避免把哈希或列表误交给字符串处理器。MATCH 和 TYPE 都是筛选条件，不会改变游标遍历的基本规则。

# 从游标 0 开始，按业务前缀分批扫描；COUNT 只用于提示单次工作量
redis-cli SCAN 0 MATCH 'order:*' COUNT 200 TYPE string

# 下一次必须使用上一条响应中的游标，不能自行递增或重置
redis-cli SCAN  MATCH 'order:*' COUNT 200 TYPE string

如果用 Go 客户端，循环条件同样只看游标。业务动作放在循环体里，游标推进放在请求结果之后，网络错误则保留当前批次的处理记录，便于重新执行。

// scanKeys 分批读取 key；handler 必须支持重复调用。
func scanKeys(ctx context.Context, rdb *redis.Client, pattern string, handler func(context.Context, []string) error) error {
	var cursor uint64 // 0 表示从当前数据库的新一轮遍历开始
	for {
		keys, next, err := rdb.Scan(ctx, cursor, pattern, 200).Result()
		if err != nil {
			return fmt.Errorf("scan cursor %d: %w", cursor, err) // 保留游标上下文，方便定位失败批次
		}
		if len(keys) > 0 {
			if err := handler(ctx, keys); err != nil {
				return err // 处理失败先停止，避免静默丢失业务动作
			}
		}
		cursor = next // 下一次请求只使用 Redis 返回的游标
		if cursor == 0 {
			return nil // 返回 0 才完成这一轮完整遍历
		}
	}
}

COUNT 不是限流器，批次处理才是压力控制点

COUNT 200 不等于每次一定返回 200 个 key。它更像 Redis 对单次工作量的提示，实际数量会受内部编码和当前数据结构影响。因此应用层要按“收到多少处理多少”，不要为了凑满批次继续发请求。

大 key 空间的风险通常不在某一次 SCAN 调用，而在拿到结果后连续执行大量 GET、序列化或外部写入。更实用的策略是：每批只处理有限数量的 key；达到业务预算后短暂让出；记录批次耗时和 Redis 延迟；当延迟升高时动态降低 COUNT 或暂停任务。

生产处理要把重复和动态变化算进去

SCAN 只保存很少的状态，所以它不会替你提供严格一次语义。一个 key 可能在一轮中返回多次；遍历开始后才新增、又很快删除的 key，是否返回也没有稳定保证。删除缓存、补写索引、发送通知这类动作，应该先问一句：重复执行的结果是否仍然正确？

最省成本的是幂等设计，例如写入使用同一个业务主键、删除前允许目标已不存在、通知带业务事件 ID。确实需要抑制重复时，再考虑给任务加短期去重集合或持久化检查点，但要明确它们会增加内存、过期和恢复逻辑。

在 Redis Cluster 中，还要确认客户端的扫描语义和节点范围。不要把单节点上的一次游标循环误认为覆盖了整个集群；如果业务需要全局遍历，应让支持集群的客户端分别处理节点，并给每个节点的进度、错误和完成状态建立记录。

上线前的检查清单

1. 明确数据库、MATCH 前缀、TYPE 条件和是否需要遍历全部节点。
2. 确认游标以 0 开始，以返回 0 结束，空批次不会提前退出。
3. 将 handler 做成幂等，或记录可恢复的短期去重状态。
4. 记录批次耗时、处理数量、重复数量、失败数量和 Redis 延迟。
5. 为动态 keyspace 约定补偿策略，不把一次 SCAN 当作精确快照。

相关问题

SCAN 会不会完全阻塞 Redis？

它把完整工作拆成多次调用，通常比一次性 KEYS 更适合在线遍历，但每次调用和后续业务处理仍会消耗 Redis 与客户端资源，不能把“增量调用”理解成零成本。

COUNT 越大是不是越快？

不一定。COUNT 增大可能减少往返次数，也可能让单批处理和延迟尖峰变大，应以目标业务的延迟预算和批次耗时做压测。

怎样保证每个 key 只处理一次？

SCAN 本身不保证严格一次。优先把业务动作设计成幂等；若确有必要，再增加有过期时间的去重记录或外部检查点，并接受额外成本。