ZAdd必须显式构造redis.Z结构体,Score须为float64(如95.0),Member推荐ASCII字符串;查榜用ZRevRangeWithScores,索引需int64类型,ZRevRank查不到返回-1需显式判断,累加分数须用ZIncrBy避免竞态。

ZAdd 必须传 redis.Z,否则 panic
Go 里调用 ZAdd 不能直接传分数和 member 字符串,比如 rdb.ZAdd(ctx, "rank", 95, "user:123") 会编译失败或运行时 panic。go-redis 强制要求你显式构造 redis.Z 结构体。
-
Score字段必须是float64类型,哪怕整数也得写成95.0;传95(int)或"95"(string)都会出错 -
Member推荐用纯 ASCII 字符串,如"user:123";避免中文、空格、JSON 或结构体,否则序列化后查不到 - 重复
ZAdd同一个Member是安全的,自动更新分数,不用先ZREM再加
正确写法:
z := redis.Z{Score: 87.5, Member: "user:789"}
err := rdb.ZAdd(ctx, "rank:weekly", z).Err()
ZRevRangeWithScores 才是查前 N 名的正确姿势
立即学习“go语言免费学习笔记(深入)”;
排行榜默认要“高分在前”,但 ZRange 是升序(低分在前),ZRevRange 才是降序。更关键的是:不带 WithScores 的版本只返回成员名,没分数——而前端通常需要一起展示。
- 索引参数类型必须是
int64,0和9表示前 10 名(左闭右闭),不是0和10 - 想取全部数据,第二个参数必须是
int64(-1),不能只写-1(某些环境会被当成大正数) - 如果
ZRevRange没返回数据,先确认是否误用了ZRange,再检查参数类型
推荐封装:
members, err := rdb.ZRevRangeWithScores(ctx, "rank:weekly", 0, 9).Result()
ZRevRank 返回 -1 不代表报错,而是成员不存在
ZRevRank 和 ZRank 都返回 int64,查不到时统一返回 -1,且 err == nil。很多人只判 err 就以为成功了,结果拿到 -1 还当是第 0 名。
- 必须显式判断返回值:
if rank == -1 { /* 用户不在榜上 */ } -
ZRevRank返回的是从 0 开始的索引,展示时要+1才是“第几名” - 如果业务允许“未上榜用户显示为‘未进入前 100’”,那就别 panic,按逻辑兜底
并发累加必须用 ZIncrBy,别在 Go 层读-改-写
点赞、打赏、活跃度加分这类场景,本质是“在原分基础上加 delta”,不是覆盖。若用 ZAdd 先读再算再写,会丢更新、引入竞态,还多一次网络往返。
-
ZIncrBy是 Redis 原子命令,delta参数必须是float64或能转成字符串的值(如5.0或"-2.5") - 增量为 0 时仍执行,但不会创建新 member——这点和
ZAdd一致 - 混用风险:对同一 member 先
ZIncrBy加了 5 分,再ZAdd写入 100 分,最终就是 100,之前加的全白费
最常被忽略的其实是类型隐式转换——int 当 float64 传、-1 当 int64 用、err == nil 就以为 rank 有效,这些地方一错就静默失效,调试起来特别花时间。


















