Redis SCAN 为什么不能保证一次返回全部键

如果你执行一次 SCAN 0，发现返回的键并不全，这通常不是 Redis 丢数据，而是把 SCAN 当成了一次性查询。Redis SCAN 使用游标做增量遍历：每次只返回一批键和下一次要使用的 cursor，只有继续请求直到 cursor 回到 0，才算完成一轮迭代。

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

SCAN 不能保证一次返回全部键，是因为它的接口契约就是“分批迭代”。判断遍历完成看下一次 cursor 是否为 0，不看某一批返回了多少键，也不把 COUNT 当成精确条数。

• 一次调用的复杂度是 O(1)，完整迭代需要多次调用。
• 返回的数组可能为空，但只要 cursor 还不是 0，就必须继续。
• MATCH 负责过滤，COUNT 只是工作量提示，二者都不能替代结束判断。

问题：SCAN 返回不全，先看懂 cursor

SCAN 的基本形式是 SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]。第一次从 0 开始，Redis 返回一个新的游标和本批键名；下一次把这个新游标传回去。不断重复，直到返回的游标再次变成 0。

因此，下面这种写法只完成了第一批读取，不能代表全库扫描：

# 只取第一批键名，返回的 cursor 不是结束标记时不能停止
redis-cli SCAN 0 COUNT 100

即使这次返回了很多键，也只能说明这一批的结果，不代表数据库剩余部分已经被遍历。

最小配方：把返回 cursor 继续传回去

实际代码要保存两个返回值：新的 cursor 和本批 key 列表。下面的 Go 示例使用 go-redis 的客户端接口表达循环逻辑，重点是“先处理本批，再用新 cursor 继续”，而不是假设一次请求完成任务。

ctx := context.Background()
var cursor uint64

for {
	keys, next, err := rdb.Scan(ctx, cursor, "user:*", 100).Result()
	if err != nil {
		// 网络或服务端错误要退出本轮，避免把不完整结果当成全量结果
		return err
	}

	for _, key := range keys {
		// 业务处理应保持幂等，因为遍历期间可能出现重复键
		if err := handleKey(ctx, rdb, key); err != nil {
			return err
		}
	}

	cursor = next
	if cursor == 0 {
		// 只有返回游标为 0，才结束这一轮迭代
		break
	}
}

如果只想观察命令形态，可以用下面的伪循环理解调用关系；它不是让 shell 自动解析 Redis 返回值，而是强调每次请求都要替换 cursor：

# 第一次从 0 开始
redis-cli SCAN 0 COUNT 100
# 把上一次返回的 cursor 替换到下一次命令中，直到 cursor 为 0
redis-cli SCAN  COUNT 100

关键参数：MATCH 和 COUNT 不能替代结束判断

MATCH 是服务端过滤条件，例如 MATCH user:* 只保留符合模式的键；它可能让某一批看起来为空，但只要 cursor 非 0，就仍然要继续扫描。COUNT 是每次调用的工作量提示，不是“严格返回 100 个键”的分页大小，也不是完整结果数量。

变体与兼容坑：空批、重复和数据变化

空数组不一定意味着结束，要看同一响应里的 cursor 是否为 0。SCAN 也不是事务快照：遍历期间新增或删除键，业务不能把这一轮结果理解成某个时间点的严格全量副本。处理动作应具备幂等性，例如按业务主键记录已处理状态，或把任务设计成可安全重试。

完整选择：SCAN、KEYS 和业务索引

在线请求中的精确查询优先设计业务索引；后台逐步处理使用 SCAN，并让任务可重试、可暂停。只有在数据规模和执行窗口都可控时，才考虑 KEYS。

常见问题

COUNT 设成数据库键总数能一次返回吗？

不能。COUNT 是工作量提示，Redis 仍然按游标迭代返回，不能把它当成精确分页大小或全量开关。

怎样避免 SCAN 结果重复造成重复处理？

让处理动作具备幂等性，并允许任务安全重试；不要依赖“每个键只会出现一次”这一假设。