leaderboard（Ruby Redis 排行榜）

项目简介

leaderboard 是一个用 Ruby 编写的排行榜库，底层由 Redis 的有序集合（Sorted Set）驱动。它把「高分榜」这类常见需求封装成简洁的 Ruby API，让你不必自己设计 Redis 数据结构，就能快速实现排名、分页、区间查询等功能。

项目思路源自作者博客中关于「用 Redis 创建高分表」的文章，采用 MIT 协议开源，在 GitHub 上获得约 481 星。

核心能力

• 创建排行榜：一行代码即可创建或挂载一个名为 highscores 的排行榜。
• 成员排名：通过 rank_member 添加或更新成员分数，重复调用会自动更新。
• 查询信息：score_for、rank_for、total_members、total_pages 等快速获取成员与榜单状态。
• 分页与区间：leaders、around_me、members_from_score_range、members_from_rank_range 支持灵活取数。
• 附加成员数据：可为成员存储 JSON 数据（如用户名、头像），并提供读取、更新、删除接口。
• 可配置选项：页大小、升降序、返回字段键名、成员数据是否全局共享等均可调整。

快速上手

安装方式为 RubyGems：

gem install leaderboard

或在 Gemfile 中声明：

gem 'leaderboard'

使用前请确保 Redis 服务已启动。

创建与写入

require 'leaderboard'

highscore_lb = Leaderboard.new('highscores')

1.upto(10) do |index|
  highscore_lb.rank_member("member_#{index}", index)
end

读取榜单

highscore_lb.leaders(1)
# => [{:member=>"member_10", :rank=>1, :score=>10.0}, ...]

highscore_lb.rank_for('member_4')   # => 7
highscore_lb.score_for('member_4')  # => 4.0

附加成员数据

require 'json'
highscore_lb.rank_member('84849292', 1, {'username' => 'member_name'}.to_json)
JSON.parse(highscore_lb.member_data_for('84849292'))
# => {"username"=>"member_name"}

常用选项

Leaderboard::DEFAULT_OPTIONS 中包含以下可配置项：

• :page_size：每页条数，默认 25。
• :reverse：设为 true 时按分数从低到高排序。
• :member_key / :rank_key / :score_key：控制返回哈希中的字段名。
• :member_data_key / :member_data_namespace：成员附加数据的键与命名空间。
• :global_member_data：成员数据是按榜单隔离还是全局共享。

Redis 连接参数可在初始化时通过第三个参数传入，也支持复用已有的 Redis 连接。

适用与注意

该项目适合 Ruby 后端在已有 Redis 的前提下快速接入排行榜功能，例如游戏高分榜、社区贡献榜、活动竞赛排名等。需要注意的是：它只面向 Ruby 生态；批量删除成员（如 remove_members_in_score_range）时，附加成员数据可能不会被同步清理；文档以英文为主，中文资料较少。