Redis ZSET 分页用游标实现稳定范围分页的实现方法

Redis ZSET 分页想要稳定，游标不能只保存最后一条记录的 score。当多个 member 共享同一个 score 时，下一页还必须知道同分值区间已经读到哪个 member。实用做法是把 lastScore 和 lastMember 组成复合游标：先处理同分值中排在游标之后的成员，再读取更高分值的数据。

Redis ZSET 稳定分页的关键是固定排序键

ZSET 的成员唯一，每个成员绑定一个 score。不同 score 先按数值排序；score 相同时，Redis 再按 member 的字节序排列。因此，下面这组数据的稳定顺序不是“谁先写入谁先返回”，而是 (10, article:a)、(10, article:b)、(11, article:c)。

用 score 和 member 组成下一页游标

首页可以从负无穷读到正无穷。读取结果时同时带上分数，把最后一条的两个字段编码进 token。下一页不能把 lastScore 直接当作新的最小值，否则同分值成员会再次出现。

# 首页：按 score 升序取一页，并把 member 与 score 一起返回
ZRANGEBYSCORE feed:zset -inf +inf WITHSCORES LIMIT 0 3

# 游标为 score=42、member=article:1007 时，先定位同分值候选
ZRANGEBYSCORE feed:zset 42 42 WITHSCORES

# 再读取更高分值；左括号表示排除已经读过的 42
ZRANGEBYSCORE feed:zset (42 +inf WITHSCORES LIMIT 0 3

应用层拿到第二条命令的结果后，只保留 member > lastMember 的成员；如果这些成员不足一页，再从第三条命令补足。这样即使一页正好停在同分值中间，也不会把同一个 member 再返回一次。

把同分值尾部和更高分值拆开读取

下面的示意代码使用 go-redis 的底层命令调用，故意把“读取一对 member/score”和“分页决策”拆开。它没有运行本地 Redis，代码用于说明请求边界；生产实现还应按项目的 token 编码方式补充签名或过期时间。

type Cursor struct {
    Score  float64
    Member string
}

func after(c Cursor, z redis.Z) bool {
    // 先比较 score；同分值时再按 member 的字节序比较。
    return z.Score > c.Score || (z.Score == c.Score && z.Member > c.Member)
}

func page(ctx context.Context, rdb *redis.Client, key string, cur *Cursor, size int64) ([]redis.Z, *Cursor, error) {
    var result []redis.Z
    if cur == nil {
        // 首页没有游标，从整个 score 范围取数据。
        result, err := readPairs(ctx, rdb, key, "-inf", "+inf", size)
        if err != nil { return nil, nil, err }
    } else {
        // 同分值候选必须先取出，再用 member 排除已读成员。
        same, err := readPairs(ctx, rdb, key, fmt.Sprintf("%g", cur.Score), fmt.Sprintf("%g", cur.Score), 0)
        if err != nil { return nil, nil, err }
        for _, item := range same {
            if after(*cur, item) { result = append(result, item) }
            if int64(len(result)) == size { break }
        }
        if int64(len(result)) 

这里的 readPairs 只负责执行 ZRANGEBYSCORE ... WITHSCORES 并解析成 []redis.Z。同分值成员很多时，第二次查询可能返回较大的候选集合，应该限制单个 score 的成员数量，或把 score 设计为时间桶与序号的组合，避免一个分值承载不可控的数据量。

并发变更下的边界与检查清单

游标只保证排序边界明确，不等于自动提供数据库快照。如果上一页返回后，某个旧 member 被删除，它自然不会出现在后续页；如果新 member 被插入到游标之前，它也不会回头补进已经翻过的页面。若业务要求“整次导出看到同一批数据”，应在写入侧建立版本快照，或把版本条件放进 key，而不是继续堆叠分页参数。

• 正向分页保存最后一条的原始 score 与 member，不要保存数组下标。
• member 使用稳定、唯一且可比较的值；不要把随机展示标题当作排序 tie-breaker。
• 反向分页要把比较符号和 score 区间方向一起翻转，并单独测试首尾边界。
• token 传给客户端前做签名或加密，防止客户端篡改 key、score 或 member。

常见问题

只用 ZRANGEBYSCORE 的 offset 分页可以吗？

数据不变且数据量小的时候可以工作，但插入、删除或更新 score 后，offset 可能跳过成员或重复返回。需要稳定翻页时优先使用复合游标。

为什么同一个 score 还要保存 member？

因为 score 只确定了一个区间，不能指出同分值组内读到的位置。member 是 ZSET 在同分值下的二级排序键。

大同分值组应该怎么处理？

把业务时间、桶编号或递增序号纳入 score 设计，减少同分值成员；如果必须同分值，则评估一次拉取和应用层过滤的内存上限。