Redis ZRANK怎样同时读取成员排名和分数

想让 Redis 一次返回有序集合成员的排名和分数，直接在 ZRANK 后追加 WITHSCORE：ZRANK leaderboard alice WITHSCORE。排名从 0 开始，按分数升序排列；同分成员再按成员字符串的字典序排列。这样不需要先查排名、再用 ZSCORE 补一次分数。

最小写法是 ZRANK key member WITHSCORE。存在成员时返回一个包含“零基排名、分数”的结果；不存在的 key 或 member 返回空值。在 go-redis/v9 中优先使用 ZRankWithScore，并把 redis.Nil 当作“没有这个成员”处理。

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

这个查询在排行榜、积分明细和任务优先级表里很常见。真正容易出错的地方不是命令本身，而是把排名的 0 当成不存在、忘记排名是升序，或者在 Go 客户端中忽略空结果和同分排序规则。下面从命令返回值一路讲到服务代码里的处理边界。

ZRANK 的排名从哪里开始

ZRANK 返回成员在有序集合中的索引位置，索引从 0 开始。集合里分数越小，排名越靠前；如果两个成员分数相同，Redis 会按成员字符串的字典序决定先后。因此，分数并不是“名次”，而是排序依据。

例如下面的集合中，alice 和 bob 分数相同，但 alice 的字符串顺序更靠前，所以它的排名更小。

# 清理演示键，避免旧数据改变排名结果
redis-cli DEL leaderboard:demo

# 写入三个成员，其中 alice 和 bob 使用相同分数
redis-cli ZADD leaderboard:demo 80 alice 80 bob 95 carol

# 读取 alice 的零基排名，结果应为 0
redis-cli ZRANK leaderboard:demo alice

# 读取 bob 的零基排名，结果应为 1
redis-cli ZRANK leaderboard:demo bob

因此，判断查询结果时要区分两种情况：返回整数 0 代表成员确实存在且排在第一位；返回空值才代表 key 或 member 不存在。把这两个结果混为一谈，会让排行榜第一名被错误地当成缺失数据。

WITHSCORE 怎样同时返回排名和分数

默认的 ZRANK key member 只返回排名。如果页面同时需要显示“第几名”和“当前分数”，追加 WITHSCORE 即可：

# 追加 WITHSCORE，一次取得排名和分数
redis-cli ZRANK leaderboard:demo alice WITHSCORE

# 查询不存在的成员，Redis 返回空结果而不是一个特殊排名
redis-cli ZRANK leaderboard:demo nobody WITHSCORE

对存在的成员，RESP 返回值可以理解为两个元素：第一个是零基排名，第二个是分数。分数在协议层通常以字符串形式传输，客户端再按自己的数据类型解析。对不存在的 key 或 member，命令返回空值；不要把它当成排名为 -1，也不要用一个自定义数字代替这个边界。

WITHSCORE 适合把一次查询的结果直接交给展示层或缓存层。如果你的业务只需要判断“是否在集合里”，普通的 ZRANK 已经足够；如果还需要分数，就用带选项的命令，避免为了补分数再发一次请求。

Go 中用 ZRankWithScore 读取结果

go-redis/v9 提供了与 Redis 选项对应的 ZRankWithScore 方法。它返回一个包含排名和分数的结果对象，缺少 key 或 member 时返回 redis.Nil。示例中的注释解释了返回结构和错误分支，代码使用的地址是本地示例地址，生产环境应从配置注入。

package main

import (
    "context"
    "errors"
    "fmt"

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

func main() {
    ctx := context.Background()
    client := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
    defer client.Close() // 程序退出时关闭连接池，避免遗留连接资源

    // WITHSCORE 对应客户端的 ZRankWithScore，一次读取排名和分数。
    result, err := client.ZRankWithScore(ctx, "leaderboard:demo", "alice").Result()
    if err != nil {
        if errors.Is(err, redis.Nil) {
            // key 或 member 不存在；这不是 Redis 服务故障。
            fmt.Println("成员不存在")
            return
        }
        // 网络、认证或上下文错误交给上层重试和告警策略。
        panic(err)
    }

    // Rank 是从 0 开始的索引，Score 是该成员的排序分数。
    fmt.Printf("rank=%d score=%v\\n", result.Rank, result.Score)
}

不要只判断 result.Rank == 0 来推断结果是否为空。正确顺序是先判断 err，确认没有错误后再读取 Rank；这样第一名和缺失成员就不会走到同一个业务分支。

同分成员为什么会出现不同排名

有序集合的 score 可以相同，但每个 member 在排序中仍然需要稳定位置。Redis 在 score 相同时比较 member 的字符串值，所以同分并不意味着并列返回同一个排名。

# 清理后写入同分成员，观察字典序如何影响排名
redis-cli DEL leaderboard:tie
redis-cli ZADD leaderboard:tie 100 zed 100 amy 100 bob

# amy、bob、zed 会按字符串顺序占据连续的零基排名
redis-cli ZRANK leaderboard:tie amy WITHSCORE
redis-cli ZRANK leaderboard:tie bob WITHSCORE
redis-cli ZRANK leaderboard:tie zed WITHSCORE

这条规则对分页尤其重要：如果业务把 score 当作唯一游标，遇到同分成员时可能漏读或重复读。若需要稳定分页，应把 member 也纳入游标设计，或者使用能够表达“分数加成员边界”的范围查询，而不是依赖多次 ZRANK 猜测下一页。

高频查询中怎样控制调用边界

Redis 官方文档将 ZRANK 的复杂度标为 O(log(N))。单个成员的排名查询通常很轻，但在高并发排行榜中仍要注意请求数量、连接池和缓存一致性。一次 WITHSCORE 能减少补分数的往返，但不能替代连接池和超时设置。

如果同一个成员的排名和分数必须来自同一时刻，优先让 Redis 一次完成 WITHSCORE 返回，再在应用侧组装响应。把 ZRANK 和 ZSCORE 分成两个请求，会留下中间数据变化的窗口。

常见问题

ZRANK 的第一名是 0 还是 1？ 是 0。它返回的是有序集合中的零基索引，展示为“第 1 名”时需要在界面层加 1。

WITHSCORE 返回的是排名和分数吗？ 是。存在成员时可以按“rank、score”理解返回结果；具体类型由客户端库解析。

不存在的成员会返回 -1 吗？ 不会。Redis 返回空值，go-redis/v9 通常以 redis.Nil 表示，业务层应明确处理。

分数相同的成员算并列排名吗？ ZRANK 仍会为它们返回不同的连续位置，同分时按照 member 的字典序排序。

为什么不直接用 ZSCORE 再查一次？ 如果同时需要排名和分数，WITHSCORE 可以减少一次客户端与 Redis 的往返，也让两个值来自同一个命令结果。

落地时可以记住一条简单规则：只要的是排名就先按零基索引理解；需要分数就追加 WITHSCORE；先处理空结果，再处理排名值。这样 Redis ZRANK 在排行榜和高频查询中的边界就清楚了。