Golang遍历Redis所有键的Scan方法

在生产环境中，Golang开发者必须用Redis的SCAN命令替代危险的KEYS命令——后者因O(N)时间复杂度和单线程阻塞特性极易引发接口超时、监控告警甚至服务熔断，而SCAN通过游标分批迭代、非阻塞设计和context超时控制，实现了安全、可控、低干扰的键遍历；文章不仅详解了go-redis中scanKeys的正确封装范式（含cursor处理、count取值建议、pattern写法），还点明HSCAN/SSCAN/ZSCAN等场景化替代方案，并直击线上高频踩坑点，帮你把“游标、分批、超时”真正刻进开发本能。

SCAN 为什么必须代替 KEYS

因为 KEYS 会阻塞 Redis 单线程，哪怕只查 user:*，只要匹配 key 超过几万，就可能让线上接口超时、监控告警、甚至触发熔断。它时间复杂度是 O(N)，且无法中断或限流——你发一条命令，Redis 就得一口气扫完全部键空间再返回结果。

而 SCAN 是迭代式遍历：每次只查一小批，用游标 cursor 记录进度，不抢主线程资源，天然适配生产环境。

• KEYS 在 Redis 7.0+ 已被标记为“仅限调试”，部分云厂商（如阿里云、腾讯云）默认禁用
• SCAN 的实际耗时接近 KEYS 总和，但拆成了多个小请求，对服务影响几乎不可感知
• 注意：SCAN 不保证一次性返回全部匹配项——它基于哈希表桶遍历，可能漏掉刚写入或正在 rehash 的 key（概率极低，业务上可接受）

go-redis 中 scanKeys 的正确写法

别直接循环调用 rdb.Scan() 然后拼接切片，容易漏 cursor 判断或 panic nil 错误。核心是：游标归零才代表结束，中间任何一次 err 都要透出。

推荐封装成带 context 控制的函数：

func scanKeys(ctx context.Context, rdb *redis.Client, pattern string, count int64) ([]string, error) {
    var keys []string
    var cursor uint64 = 0
    for {
        scanned, nextCursor, err := rdb.Scan(ctx, cursor, pattern, count).Result()
        if err != nil {
            return nil, err
        }
        keys = append(keys, scanned...)
        if nextCursor == 0 {
            break
        }
        cursor = nextCursor
    }
    return keys, nil
}

• count 建议设为 10–100：太小（如 1）会导致 RTT 次数爆炸；太大（如 10000）可能单次响应超 1MB，触发客户端内存抖动
• pattern 为空字符串 "" 等价于 "*"，但显式写 "*" 更易读
• 务必用 context.WithTimeout 包一层，防止某次 SCAN 卡住（比如网络抖动 + 大量 key）

常见错误现象和坑点

线上踩过的典型问题，基本都集中在游标处理和边界条件上：

• 忘记判断 nextCursor == 0，导致死循环（最常见）
• 把 cursor 当成 int 传参，但 go-redis 要求是 uint64，传错会 panic 或返回空结果
• 在 for 循环里重复定义 ctx := context.Background()，导致 timeout 不生效
• 用 rdb.Keys() 调试完没删，上线后直接炸服务（尤其测试环境数据少，看不出问题）
• pattern 写成 user:*:profile 却忘了 key 实际是 user:1001:profile:detail，结果扫不到——通配符不支持递归，* 只能匹配本层

什么时候该用 HSCAN/SSCAN/ZSCAN

如果你要扫的不是 key，而是某个 hash 的所有 field、set 的所有 member、zset 的所有 member-score 对，就别硬套 SCAN——它只能扫 key 空间。

对应场景必须换命令：

• 遍历用户资料 hash：用 rdb.HScan(ctx, "user:1001:profile", 0, "*", 10)
• 扫黑名单 set：用 rdb.SScan(ctx, "blacklist", 0, "*", 50)
• 拉取排行榜前 N 名但不想全量加载：用 rdb.ZScan(ctx, "leaderboard", 0, "*", 100)

它们和 SCAN 共享同一套游标逻辑，参数结构一致，只是命令名和作用对象不同。

真正难的不是写对 SCAN，而是意识到：只要涉及“批量查 key”，第一反应就不该是 KEYS。游标、分批、context 超时——这三样得像 if 判断一样写进肌肉记忆里。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang遍历Redis所有键的Scan方法》文章吧，也可关注golang学习网公众号了解相关技术文章。