Redis ZSET 按分数分页 怎样处理

我在给排行榜接口加分页时，最先想到的是给 ZRANGE 传一个 offset 和 count。这个写法很快能看到结果，但一旦排行榜持续写入，下一页可能重复上一页的成员；如果多个成员的 score 相同，单纯记录最后一个 score 又可能直接跳过同分成员。

Redis ZSET 按分数分页的关键不是“把数组切成几段”，而是先确定排序边界：分页是否允许数据变化、是否需要跳页、相同分数是否必须全部保留。Redis 官方地址：https://redis.io/。下面按这几个边界给出可以落地的命令组合。

先分清排名分页和分数范围分页

ZSET 的 member 唯一，每个 member 关联一个 score。score 不同按数值排序；score 相同时，Redis 再按 member 的字典序排列。因此“第 21 到第 30 条”和“score 在 80 到 100 之间”是两种不同的查询。

ZRANGE 在 Redis 6.2 以后可以使用 BYSCORE 和 LIMIT，旧版本则常用 ZRANGEBYSCORE。两者表达的核心都是按分数取范围，而不是先取全量再由应用切片。

ZRANGE BYSCORE 到分页窗口，参数分别代表什么

先准备一组演示数据。下面是命令示例，注释只解释参数目的，不代表本文已经连接某个线上 Redis 实例。

# 写入一个按分数升序排列的排行榜
redis-cli ZADD leaderboard 10 user-a 20 user-b 20 user-c 30 user-d 40 user-e

# 从 score 10 到 40 中取 2 个成员，offset=0 表示第一页
redis-cli ZRANGE leaderboard 10 40 BYSCORE LIMIT 0 2 WITHSCORES

# 第二页从同一分数范围继续，但这是 offset 分页
redis-cli ZRANGE leaderboard 10 40 BYSCORE LIMIT 2 2 WITHSCORES

这里的 10 40 是 score 范围，LIMIT 2 2 才是“跳过两个匹配成员后再取两个”。如果只需要成员，不要 WITHSCORES；如果接口需要返回下一页游标，通常应同时取出 score。

这个方案的优点是实现简单、容易支持页码跳转。缺点也很明确：第一页返回后，如果有新成员插入范围前面，原来的 offset 会指向不同位置；如果成员被删除，后续页也会向前移动。数据持续变化时，不要把 offset 当成稳定游标。

数据变化不大时，offset 分页可以直接用

后台报表、一次性导出或已经冻结的榜单，offset 分页往往足够。落地时我会给接口加三个限制：固定最大 pageSize、禁止过深页码、把排序方向写进请求和缓存键。这样可以避免调用方传入很大的 offset，让 Redis 和应用都做无意义的跳过。

package page

import "strconv"

// NormalizePage 把外部页码限制在可接受范围内，避免深分页拖慢请求。
func NormalizePage(page, size int) (offset, count int) {
	if page < 1 {
		page = 1
	}
	if size < 1 {
		size = 20
	}
	if size > 100 {
		size = 100
	}
	// 生产代码还应结合业务设置最大页码，而不是允许无限跳页。
	return (page - 1) * size, size
}

// CursorForOffset 只把查询条件编码进游标，便于缓存键保持稳定。
func CursorForOffset(offset, count int) string {
	return strconv.Itoa(offset) + ":" + strconv.Itoa(count)
}

这里的重点不是 Go 函数本身，而是把 page、size、score 范围和方向视为同一组查询条件。若调用方在翻页期间改变筛选范围，却继续复用旧 offset，结果自然不可解释。

连续翻页时，用最后一个 score 做开区间游标

当页面只需要“继续向后取”，可以把上一页最后一个 score 作为下一页的起点，并使用开区间。Redis 的分数范围支持用左括号表示不包含该边界：

# 第一页：从最小分数开始取 3 条
# -inf 表示负无穷，LIMIT 保持每页固定大小
redis-cli ZRANGE leaderboard -inf +inf BYSCORE LIMIT 0 3 WITHSCORES

# 假设上一页最后一个 score 是 20，下一页排除 score=20
# 开区间 (20 会避免把上一页末尾的分数再次取回
redis-cli ZRANGE leaderboard \(20 +inf BYSCORE LIMIT 0 3 WITHSCORES

这个写法适合 score 本身具有唯一性，或者业务允许把同一个 score 的成员视为同一批处理。它不能自动解决“同分成员必须逐条分页”的问题，因为 (20 会把所有 score=20 的成员一起排除。

倒序分页时，边界方向也要一起反转。使用 REV BYSCORE 时，应从较大的 score 向较小的 score 取，下一页用小于上一个游标的范围；不要只把 REV 加到原命令后面，却继续发送升序的边界。

重复分数时，为什么需要复合游标

同一个 score 下，Redis 会按 member 的字典序排列。若接口的稳定性要求是“每个 member 只出现一次”，游标至少需要包含 score 和同分时的排序键。只传一个 score 有两个极端：用闭区间会重复同分数据，用开区间会漏掉尚未读完的同分数据。

常见的工程处理有两种：

1. 把业务可接受的唯一序号编码进 score，例如时间戳乘以固定倍率再加序列号，让最终 score 严格递增；要注意浮点精度和最大值边界。
2. 把 score 与 member 一起作为游标，在应用层按“score 更大，或 score 相同且 member 更大”拼出下一次查询；这样需要额外处理同分区间，并保证 member 的比较规则与 Redis 一致。

如果使用复合 score，示例可以先约定分数由毫秒时间和序列号构成，但不要把它写成无边界的浮点拼接。更稳妥的做法是明确倍率、范围和溢出策略，并在写入端和读取端共用同一编码函数。

package cursor

import "fmt"

// EncodeScore 生成单调的复合分数；seq 的范围必须小于 multiplier。
func EncodeScore(timestampMs, seq, multiplier int64) (float64, error) {
	if multiplier <= 0 || seq < 0 || seq >= multiplier {
		return 0, fmt.Errorf("invalid sequence: seq=%d multiplier=%d", seq, multiplier)
	}
	// 真实系统还要评估 float64 对整数精度的限制，必要时改用字符串游标方案。
	return float64(timestampMs*multiplier + seq), nil
}

如果不能接受复合 score 的精度限制，宁可把同分成员分桶，再在桶内用 member 做字典序游标，也不要用一个未经定义的“小数尾巴”碰运气。

性能和稳定性怎么取舍

Redis 官方文档给出的范围查询复杂度是 O(log(N)+M)，其中 M 是返回的成员数；但 offset 很深时，业务上仍会付出跳过大量匹配项的代价。真实接口里我会把下面几项作为基线观察，而不是只看单次命令耗时：

• pageSize 与最大允许 offset，先限制最坏请求；
• 分页期间的新增、删除和 score 更新比例，判断 offset 是否会漂移；
• 重复 score 的占比，决定是否必须引入 member 或复合序号；
• 升序和倒序是否都需要，确保两套游标边界分别设计。

我的选择习惯是：需要页码跳转且数据近似静态，用 offset；只向前滚动且 score 能作为稳定边界，用开区间 score 游标；榜单持续更新、同分很多且不能漏项，则使用复合游标或预先设计的单调排序键。

常见问题

ZRANGE BYSCORE 和 ZRANGEBYSCORE 选哪个？

Redis 6.2 以后优先统一使用 ZRANGE ... BYSCORE，因为它把 rank、score 和 lex 三类范围操作收拢到一个命令。需要兼容较旧 Redis 时，再使用 ZRANGEBYSCORE 的旧写法。

为什么下一页会重复上一页最后一条？

通常是下一次查询使用了闭区间，例如仍从 score=20 开始。若业务允许按 score 分组，应使用 (20；若同分成员也要保留，就必须把同分排序键纳入游标。

能不能用 ZRANK 直接实现稳定分页？

ZRANK 能得到成员的排名，但写入会改变排名。它适合查看当前位置或做排名展示，不等于在高写入场景中提供快照分页。

Redis ZSET 分页真正要固定的是“下一页从哪里开始”，而不是某一个命令的写法。先判断数据是否会变化，再处理重复 score 和方向，最后限制深分页，接口结果才会稳定。