python-leaderboard（Redis 排行榜）

项目简介

python-leaderboard 是一个用 Python 编写的排行榜库，底层依托 Redis 的有序集合（Sorted Set）来存储和计算排名。它把「加分、查名次、取区间榜单」这类常见需求封装成简单接口，适合在游戏、社区、活动等场景中快速接入排行榜能力。

⚠️ 重要提示：该仓库已迁移，后续开发在 leaderboard-python 进行，原仓库计划在约 60 天内删除。新项目请直接使用迁移后的仓库。

核心思路

排行榜的本质是「按分数排序并支持快速定位名次」。Redis 的 ZSET 天然满足这一需求：

• 成员（member）对应排行榜中的用户或条目
• 分值（score）对应积分、热度等排序依据
• Redis 提供按分值区间、按名次区间取数据的原语

库在这一层之上封装了更贴近业务的 API，例如为某个成员增减分数、查询其当前排名、获取前 N 名或某一段名次的数据。

典型用法示意

from leaderboard import Leaderboard
from redis import Redis

redis = Redis(host='localhost', port=6379)
board = Leaderboard(redis, 'game_score')

# 为成员加分
board.rank_member('player_1', 100)
board.rank_member('player_2', 250)

# 查询名次与分数
rank = board.rank_for('player_1')
score = board.score_for('player_1')

# 获取前 10 名
leaders = board.leaders(1, 10)

以上为常见用法的示意，具体方法名与参数请以实际安装版本和迁移后仓库的文档为准。

适用场景

• 游戏内积分榜、赛季段位排名
• 社区内容的点赞榜、热度榜
• 运营活动的实时打榜与榜单展示
• 需要按分数区间或名次区间查询的业务

使用建议

1. 优先使用迁移后的 leaderboard-python 仓库，避免依赖即将删除的代码。
2. 为 Redis 配置持久化与监控，排行榜数据通常对业务较重要。
3. 若排名规则复杂（如多维度加权、同分并列规则），需要在库之上自行扩展。
4. 高并发写入场景下注意热点 key 与批量操作带来的压力。