Redis ZRANGE BYSCORE 分页为什么会漏数据：同分值排序、边界游标与复查

订单时间线、排行榜和延迟队列这类场景，大家经常用Redis有序集合存数据，做分页时把时间戳设为score，再用 ZRANGE ... BYSCORE 做查询，看起来比关系型数据库的游标写法简单不少。真的上线跑流量之后，问题往往出在同一秒写入多条记录的场景：要么上一页最后一条和下一页第一条重复，要么为了避重直接把整个同分值区间排除，结果平白漏掉一批数据。

稳定的做法是把score和member一起拼成游标：先用score定位分页走向，再用member处理同分值的边界情况；不要直接套用普通数据库的page+offset逻辑，也不要把下一页的边界设成两头都包含的重复区间。

线上触发信号：页码显示正常，统计记录数却少了

最容易误判的场景是接口一直返回200状态码，前端翻页看起来完全正常，但导出全量数据的时候，总条数比后台按时间范围筛选出来的数量少很多。最常见的错误请求写法大概是这样：

ZRANGE orders:timeline 1719800000 +inf BYSCORE LIMIT 0 20 WITHSCORES

服务端把最后一条记录的score存下来，下一页查询直接改成：

ZRANGE orders:timeline 1719800123 +inf BYSCORE LIMIT 0 20 WITHSCORES

如果你的score是秒级时间戳，同一秒写入的订单可能有几十条。第二条命令直接从新的score开始拉取，上一页同分值里还没读够的那些记录直接就被跳过了。反过来如果两页都用闭区间写边界，上一页最后一条数据又会在下一页头部重复出现。

快速判断：先确认有序集合的真实排序规则

Redis的排序逻辑不是“只按score排”。分数完全相同的member会按字典序排列，所以member本身必须是稳定、全局唯一的，最好直接用订单ID或者自带顺序属性的可比较值。

ZADD orders:timeline 1719800123 order:1001
ZADD orders:timeline 1719800123 order:1002
ZADD orders:timeline 1719800123 order:1003
ZRANGE orders:timeline 1719800123 1719800123 BYSCORE WITHSCORES

这组测试数据里三个订单的score完全相同，最终返回顺序由member的字典序决定。先用 ZRANGE ... WITHSCORES 查一遍真实返回顺序，再检查应用代码是不是只把score当成了唯一的分页锚点。这时候别急着把单页拉取条数 LIMIT 调大，那只是临时掩盖边界错误，没有从根上解决问题。

处理步骤：用独占score收口，再补上同分值的后续成员

如果业务允许按时间分段消费，最小的临时修复是让下一页直接排除上一页已经读完的score：

ZRANGE orders:timeline (1719800123 +inf BYSCORE LIMIT 0 20 WITHSCORES

但这个写法会把同一个score里还没读过的成员全部排除，所以它只适用于“同一个score的所有成员已经全部消费完成”的场景。一般的订单列表场景很难满足这个前提，必须把同分值区间再拆一层做细分。

一个非常实用的游标方案是把时间精度提高到毫秒级，member只负责做稳定去重：

type Cursor struct {
    LastScore  int64  `json:"last_score"`
    LastMember string `json:"last_member"`
}

// 首页：按分数从新到旧取一小段
ZRANGE orders:timeline +inf -inf BYSCORE REV LIMIT 0 20 WITHSCORES

// 后续页：至少排除已处理的 score 区间，再用 member 做同分值补查
ZRANGE orders:timeline (1719800123000 +inf BYSCORE LIMIT 0 20 WITHSCORES

如果必须严谨处理大量同分值的场景，推荐把可排序的时间和唯一ID都编进member字段，或者先把同一个score下的所有成员取到服务端，再按member的排序找到上一页的结束位置。核心不是把SQL里的offset逻辑原样搬到Redis，而是让“最后一条读到了哪条记录”变成非常明确的状态。

返回给客户端的游标至少要包含三个字段：

• last_score：最后一条记录的原始score，不能从前端展示的时间重新反向计算生成。
• last_member：最后一条记录的唯一member值，专门用来处理同分值的边界场景。
• snapshot_at：如果列表需要相对稳定，保存本次查询的上界时间戳。

回滚路径：先切回旧分页逻辑，再慢慢修正写入精度

改分页游标的时候不要同时调整前端展示排序和数据清理策略。线上已经出现重复或者漏数据的问题，可以先把新接口切回旧版本兼容逻辑，但要保留原始 last_score 和 last_member 的解析能力，避免用户正在翻页的时候遇到新旧游标格式不兼容的问题。

如果根因是score只用了秒级精度，后续新写入的数据可以改成毫秒级，或者用“时间戳加序列号”的方式生成整数分数。旧数据没必要立即全量重建：先让读取逻辑兼容旧的精度格式，确认新写入的同分值记录数量明显下降之后，再挑业务低峰期安排重建和校验即可。

不要直接删除整个 orders:timeline 再重新建集合。列表可能还有大量正在使用的存量游标，直接删除会把漏数据的问题变成空列表，甚至引发大面积回源风暴。

校验确认：用三组测试数据验证分页不会再漏

修复完成后准备一组固定测试数据，特意往里面塞多个相同score的member，做连续多页翻页测试。每页重点核对三个指标：

• 返回数量是否等于请求的page size，最后一页的条数是否自然小于page size。
• 相邻两页的member集合交集是否为空，所有页数据合并之后的去重总数量是否和预期总数一致。
• 游标对应的score是否单调变化，遇到同分值的时候member是否按预期向后推进。

# 检查一个时间段内的完整集合
ZRANGE orders:timeline 1719800123 1719800123 BYSCORE WITHSCORES

# 检查某个 member 的分数，确认应用保存的游标没有漂移
ZSCORE orders:timeline order:1002

如果分页期间允许写入新数据，固定数据测试通过也不代表线上结果一定是稳定快照。对实时浏览类列表，接口文档可以明确说明“翻页期间新产生的记录只会出现在后续查询结果里，不会插入已翻过的页面前面”；如果是导出、对账这类需要稳定结果的场景，就要提前把 snapshot_at 固定住，把查询的上界锁死。

复盘项：把排序契约写进接口文档和单元测试

后续可以把有序集合的排序契约写进代码注释和接口文档里：score代表什么含义、member是否全局唯一、同分值按什么规则排序、游标是否附带快照上界。测试用例不要只放3条不同分数的简单数据，至少要覆盖同分值分页、游标对应成员被删除、分页过程插入新成员、最后一页条数不足四种场景。

当数据量持续变大的时候，也要留意 LIMIT offset count 的offset成本。深分页会先跳过offset个匹配的成员，页数越深查询速度越慢；游标分页能减少很多无意义的遍历跳过，但仍然需要控制单页返回大小和整体查询范围。

常见问题

ZRANGE BYSCORE 的边界默认包含吗？

普通数字边界默认是闭区间，写成 (1719800123 才表示排除这个score本身。分页的时候要根据“这个分数的所有数据是不是已经处理完了”来决定要不要用独占边界。

同一个score下Redis按什么顺序返回？

同分值成员按字典序排列。如果应用只保存score的值，根本没法知道同分值区间里已经读到了第几条，必须额外保存对应的member或者用精度足够细的分数。

分页期间插入新数据会不会出现重复？

实时列表场景下数据位置可能发生变化。需要稳定结果的时候给第一次查询就设置好时间上界，后续所有翻页查询都复用同一个上界；不然就直接把接口定义成实时浏览的语义即可。

为什么不用 LIMIT 100000, 20 这种深分页写法？

很大的offset需要先遍历完前面所有匹配的成员，页数越深性能越差。连续翻页、导出、对账这类场景更适合用游标分页方案。

小结

Redis有序集合分页的坑根本不在命令难记，而是排序的隐性契约没说清楚。把score当成主排序键、把member当成同分值的次排序键，再明确每个边界是否是独占区间，分页结果就能从“看起来差不多”变成完全可复查的连续数据。上线前用带多组同分值的固定测试数据跑一遍相邻页交集校验，往往比盯着前端列表反复测试更快发现问题。