Redis ZSET 分页为什么会漏数据：游标边界与同分值排序

线上排行榜接口偶尔会出现“第二页少了一条”的情况，查 Redis 里记录却都还在。Redis ZSET 本身通常没有漏数据，真正容易出错的是应用把分页游标只记成一个 score：当多个成员分数相同，下一页无法知道应该从哪个 member 继续；如果翻页期间还有写入，重复和遗漏会一起出现。

稳定的 ZSET 游标至少要包含最后一条记录的 (score, member)，并按同一套排序规则取下一页。只保存 score，遇到同分值成员就不够用了。

先复现：为什么第二页会少一条

先用最小数据集复现，不要一上来怀疑 Redis。下面四个成员里，u:102 和 u:103 的分数相同：

DEL ranking
ZADD ranking 10 u:101 20 u:102 20 u:103 30 u:104
ZRANGE ranking 0 1 WITHSCORES
ZRANGE ranking 2 3 WITHSCORES

第一条命令返回 u:101、u:102，第二条返回 u:103、u:104。应用若把第一页末尾只编码成 lastScore=20，下一次用 score > 20 过滤，就会把 u:103 一起跳过去。问题发生在游标表达能力，不是排序集合丢了成员。

同分值时，真正的分页边界是什么

Redis ZSET 的排序先比较 score，再比较 member 的字典序。分页游标可以定义成两个字段：lastScore 和 lastMember。取下一页时保留两种情况：

• 新记录的 score 大于 lastScore；
• score 相同，但 member 的字典序大于 lastMember。

如果接口使用正序榜单，可以先取一个足够宽的范围，再在应用层按这个条件过滤；也可以用 ZRANGEBYLEX 处理固定 score 的区间。关键不是某一个命令，而是“写入游标”和“读取下一页”的比较器必须完全相同。

cursor = { score: 20, member: "u:102" }
next item is valid when:
  item.score > 20
  OR (item.score == 20 AND item.member > "u:102")

接口返回的下一页游标也要取该页最后一条实际返回记录，而不是取本页最大分数。否则一页末尾刚好落在同分值中间时，下一页仍会漏项。

翻页期间有写入，为什么还会重复或漂移

即使游标设计正确，分页结果也不一定是静态快照。第一页返回后，如果插入了一条分数更靠前的新成员，后续按排名位置分页会把旧成员向后挤；如果删除或更新了成员，用户也可能看到页间空洞。

这里先别急着加锁。排行榜、热度榜这类列表通常允许结果随时间变化，更重要的是保证单次请求内不重复、同一个游标能继续向后走。如果业务要求导出一份固定名单，则应把参与集合冻结到一个版本号或时间窗口，而不是把实时 ZSET 当数据库快照。

代码接口该怎么设计

游标不要只传一个数字。推荐把最后一条记录的 score、member 和排序方向一起编码；对外可以使用 Base64URL，但内部仍保持可审计的 JSON 字段：

{
  "score": 20,
  "member": "u:102",
  "direction": "asc"
}

查询层要固定排序方向、页大小上限和成员格式。若 member 不是稳定唯一值，例如直接使用可变昵称，改名就会改变字典序，游标可能失效；应使用不可变用户 ID，把昵称作为展示字段。

上线前用四组数据验收

测试不要只准备不同分数的样本。至少覆盖四组：全部分数相同、只有一组同分、翻页中插入新成员、翻页中更新或删除成员。对每组数据，把所有页合并后检查三个条件：

• 同一个 member 不出现两次；
• 全量扫描与分页合并后的 member 集合一致；
• 相邻页之间的游标严格向前，不因同分值停住或跳跃。

当列表允许实时漂移时，第二个条件应改成“在同一版本或时间窗口内一致”。把语义写进接口文档，前端就不会把一次实时榜单误解成可复现的快照。

相关问题

为什么不用 offset 直接分页？

offset 适合小数据集和静态结果。ZSET 在中间插入或删除成员后，offset 代表的位置会移动，重复和遗漏更难解释；游标能把边界绑定到实际成员。

member 一定要参与排序吗？

只要允许同一个 score 下存在多个成员，就必须有稳定的第二排序键。Redis 默认使用 member 字典序，应用也可以在结果层实现同样的比较规则。

更新 score 后旧游标还能用吗？

不能保证。更新会改变成员在集合中的位置；如果接口需要可复现结果，应使用版本化快照或固定时间窗口，并把版本写入游标。

小结

Redis ZSET 分页的核心不是把页码换成一串编码，而是把排序边界保存完整。以 (score, member) 作为正序游标，配合同一套比较器和明确的实时/快照语义，才能把同分值漏项、翻页重复和数据漂移分别控制住。