Redis SCAN 游标分页避免阻塞主线程的方法

Redis 的键空间较大时，直接用 KEYS pattern 把所有匹配键一次性取回，最容易让主线程在一个长命令上停留过久。更稳妥的做法是使用 SCAN：每次带上上一次返回的游标，只取一小页键名，把游标和结果交给后台任务继续处理。

SCAN 降低的是单次遍历调用的压力，不是让完整遍历变成零成本操作。真正避免请求线程被拖住，还要把轮询放进可取消的后台任务，并在每页处理后保存游标。

• 用 cursor=0 开始一轮扫描，Redis 返回新的游标和当前页键名。
• 用 COUNT 控制期望的页大小，但不要把它当成严格条数保证。
• 只有新游标再次变成 0 才表示这一轮结束；空页不代表结束。
• 后台任务使用独立的 context，让 HTTP 请求结束时不会留下无法停止的扫描。

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

先把“阻塞”拆成三个不同问题

KEYS 是一次性命令，匹配键很多时，服务端需要在一次调用中完成大量工作。SCAN 则以游标迭代键名：每一调用的复杂度是 O(1)，但从游标回到 0 的完整迭代总体仍与键空间规模有关。因此，SCAN 不是让扫描凭空消失，而是把长任务拆成许多可调度的小片段。

还要注意两个容易混淆的点：COUNT 只是工作量提示，返回数量可能少于或多于它；在遍历期间修改键空间时，结果可能出现重复键，也不能把一次返回为空直接当成结束。

用游标、键页和完成标记表达一页结果

如果扫描任务需要被定时器或队列接管，建议把结果定义成显式的分页对象，而不是只返回一个字符串切片。cursor 用于恢复下一页，keys 是本次要处理的候选键，done 只在本次调用后游标为零时为真。

这层协议让扫描和业务处理解耦：当前页处理失败时可以保留游标重试，任务被取消时也能记录最后一个已确认的游标。若业务要求“每个键只处理一次”，还应给处理逻辑增加幂等键或去重设计，不能依赖 SCAN 的返回顺序。

Go 中把 SCAN 放到可取消的后台任务

Redis 官方 Go 客户端文档使用 go-redis/v9 和 context 建立连接。下面的函数每次只取一页，并在处理完当前页后继续游标轮询；真实服务可以把它交给任务队列或独立 worker，而不是在 HTTP handler 中同步跑完整轮。

package main

import (
    "context"
    "fmt"

    "github.com/redis/go-redis/v9"
)

// scanKeys 分页遍历键名；调用方可用 cursor 保存下一次恢复位置。
func scanKeys(ctx context.Context, client *redis.Client, pattern string) error {
    var cursor uint64 // Redis 返回的游标由服务端推进，不能按页码自行加一。
    for {
        keys, next, err := client.Scan(ctx, cursor, pattern, 100).Result()
        if err != nil {
            return fmt.Errorf("scan keys: %w", err) // 保留原错误，交给任务层决定重试。
        }

        for _, key := range keys {
            // 当前页可以投递给幂等处理器，避免在请求线程里做完整遍历。
            fmt.Println(key)
        }

        cursor = next
        if cursor == 0 {
            return nil // 只有游标回到零，才表示本轮迭代结束。
        }
        if err := ctx.Err(); err != nil {
            return err // 任务取消或超时后及时停止，避免后台泄漏。
        }
    }
}

func main() {
    ctx := context.Background()
    client := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
    defer client.Close() // 示例结束时释放连接池资源。

    if err := scanKeys(ctx, client, "order:*"); err != nil {
        panic(err) // 生产代码应写入任务日志并按错误类型决定是否重试。
    }
}

示例中的 100 是一次任务的工作量提示，不是严格的返回条数。若单页处理本身很重，可以把 keys 交给有限并发的 worker，再在任务状态中记录“已取到的游标”和“已完成的业务处理”，避免只保存了扫描进度却丢失处理进度。

空页、重复键和取消信号怎么收口

首先，空页是合法结果：继续使用返回的下一个游标，直到它变为零。其次，SCAN 不提供稳定排序；当键空间变化或任务重试时，同一个键可能再次出现，所以删除、迁移或统计类处理应设计幂等逻辑。若只想减少候选范围，可使用 MATCH order:*，但 MATCH 是过滤条件，不会把全库扫描变成索引查询。

最后，把 context.WithTimeout 或任务取消信号传入每次 Scan。发生网络错误时，保留任务状态并按业务策略重试；发生取消时直接退出，不要无限重启。这样既能避免一次请求承担完整扫描，也能让扫描任务在服务关闭或队列超时后自然收口。

常见问题

COUNT 设置为 100，为什么返回不是 100 个键？

COUNT 是 Redis 的工作量提示，不是分页大小承诺。程序应遍历实际返回的 keys，并使用返回的游标继续。

某一页为空，是不是扫描结束了？

不是。空页仍然可能带有非零游标，只有游标回到 0 才结束当前迭代。

SCAN 能保证每个键只出现一次吗？

不能把它当成业务去重机制。遍历期间修改键空间、任务重试或恢复游标时都应考虑重复处理，并让业务动作保持幂等。