Redis SCAN 游标遍历的重复与遗漏边界

Redis SCAN 的正确用法可以先记住一句话：从游标 0 开始，持续使用上一次返回的游标，直到新游标再次变成 0。本轮返回数组为空并不代表结束；键空间在遍历期间变化时，也不能把结果当成一致性快照。

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

本文结论：稳定存在的键可以依赖完整遍历保证；重复返回要靠幂等消费或去重；新增、删除和持续增长的键属于动态边界，需要单独定义业务策略。

Redis SCAN 的结束条件不是“本批有数据”

SCAN 每次返回两个对象：新的游标和本次拿到的键数组。最小循环只看游标，不看数组长度：

redis-cli --scan --pattern 'cache:*' --count 200
# --pattern 只筛选键名；--count 是每轮工作量提示，不是固定返回条数

如果自己封装客户端，状态机应保持“当前游标”和“本批键”分离。服务端允许返回空数组，只要游标还不是 0，就必须继续请求。把空数组当结束条件，会把稀疏匹配误判成扫描完成。

稳定集合与动态集合要分开判断

官方文档给出的保证有一个前提：如果某个键从遍历开始到结束一直存在，完整遍历最终会返回它；如果某个键在遍历前已经删除且期间没有重新加入，则不会返回它。这个保证不等于“对任意时刻的键集合做快照”。

一旦键在遍历期间新增或删除，返回与否就是未定义行为。尤其是持续写入的业务键空间，遍历可能一直追不上增长速度，不能用一次 SCAN 作为严格的全量导出依据。需要稳定结果时，应在业务层提供时间窗、版本标记或独立快照。

重复和遗漏要靠消费策略兜底

同一个键可能被多次返回，所以处理动作应该天然可重放。例如删除缓存、刷新索引、写入带唯一键的任务表，都应把重复执行设计成无害操作。若动作本身不可重复，可以在本轮内维护 seen 集合：

cursor := uint64(0)
seen := map[string]struct{}{}
for {
    keys, next, err := rdb.Scan(ctx, cursor, "cache:*", 200).Result()
    if err != nil {
        return err // 网络错误时保留当前游标，由上层决定重试
    }
    for _, key := range keys {
        if _, ok := seen[key]; ok {
            continue // SCAN 允许重复返回，跳过本轮已消费键
        }
        seen[key] = struct{}{}
        if err := handleKey(ctx, key); err != nil {
            return err // 失败项不要静默丢弃，交给业务重试或补偿
        }
    }
    cursor = next // 下一轮必须使用服务端返回的游标
    if cursor == 0 {
        break // 只有游标归零才结束完整遍历
    }
}

seen 只解决同一轮重复，不解决遍历期间删除后又重建、跨轮重试或多消费者并行的问题。生产任务更适合用业务去重键和幂等处理共同兜底，而不是无限扩大内存中的集合。

MATCH、COUNT 与增长场景的参数边界

MATCH 是服务端按 glob 模式过滤，过滤后本轮可能很少甚至没有键；因此不能因为匹配结果为空而退出。COUNT 只是工作量提示，默认值是 10，实际条数没有固定保证，而且每轮可以调整，但游标必须沿用上一轮返回值。

常见问题

为什么不用 KEYS 直接拿全量键？大键空间上，KEYS 可能长时间阻塞服务端；SCAN 把工作拆成多次调用，更适合在线维护任务，但要接受重复和动态变化边界。

COUNT 设得越大越不会遗漏吗？不会。它影响每次工作的规模，不改变游标语义，也不把动态集合变成快照。

什么时候可以认为扫描完成？只有服务端返回的游标为 0，才完成这一轮从 0 到 0 的完整遍历。

总结：把游标归零作为结束信号，把空批次当作正常状态；对稳定键依赖完整遍历保证，对动态键和重复返回交给幂等、去重与补偿策略。这样才能把 SCAN 用成可控的维护工作流，而不是误当成全量快照接口。