200 views
owned this note
# Leaderboard方案
### leaderboard在console的配置
| 配置项名称 | 配置项含义 |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| ID (key) (由console生成) | 每个排行榜配置的唯一标识 |
| 名称 (name) (必填) | 排行榜名称 |
| 指标 (key) (必填) | 指标名称 （exp：kill）增加与pigat联动，可以是pigat中的数值，例如player.level |
| 大小 (size) （必填） | 排行榜大小 (榜单名次外的对象不参与排名) |
| 顺序 (order) （必填） | 正序（ASC）还是倒序（DESC) |
| 是否为周期榜 (is_cycle) (必填) | 如果为false，则表示此榜单为起止时间内的一次性榜单，如果为true，则需要提供具体周期 |
| 周期单位 (cycle_unit) | 提供三个单位描述周期，最大精度到小时，最小精度到月，h=小时，d=天，m=月 |
| 周期长度 (cycle_length) | 描述所选周期单位的长度 |
| 起始时间 (start_time) (必填) | 2020101700 描述精度到小时 |
| 终止时间 (end_time) | 2020111700 描述精度到小时 (对于一直要维持的榜单可以没有终止时间) |
------
leaderboard与pigat联动后的console相关变更：
<span style="color:green">新增id</span>
<span style="color:green">新增key</span>
<span style="color:orange">拆分cycle为cycle_length与cycle_unit</span>
<span style="color:orange">name的意义改变</span>
<span style="color:red">移除keep</span>
<span style="color:red">移除GMT</span>
--------
### 约定项
1. leaderboard模块本身只接受全量数据的排名
2. 提供的全量指标数据不会为负
3. 查询特定目标在榜单上的排名时，如果目标的排名超过榜单的大小，则目标的排名返回值为-1。
### redis内存占用计算
按照1000组数据为一个排行榜大小的标准，浮动的dataset占用约~1mb。
而以减少redis操作为标准，当排行榜达到约定大小的两倍才会进行清理（2x1000），则一个标准榜单占用约为~2mb。
### redis key设计
leaderboard模块使用room作为存储，key类型为zset。
redis key的格式为
`app_id:leaderboard:{leaderboard_id:leaderboard_interval}:data`
### 01 POST 传入榜单数据
**server to server:** {bp_server}/bp/server/user/{user_id}/leaderboard/data
| Required Headers |
| ---------------------- |
| X-BytePower-Auth-Token |
**client to server:** {bp_server}/bp/leaderboard/data
| Required Headers |
| ------------------------- |
| X-BytePower-Sign |
| X-BytePower-Session-Token |
| 参数 | 类型 | 示例 | 说明 |
| ---- | ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| key | float64 | "kill": 12 | 对应console上的配置，例如配置了一个击杀排行榜，其key为"kill"，对应的数值为12，则传入{"kill":12}，支持一次传入多个key的变动。 |
输入示例：
```json=
{
"kill":12,
"assist":15,
"death":5,
"kda":5.4
}
```
返回示例：
code:200
```json=
{
"updated_leaderboards":[
{
"name":"击杀日榜",
"interval":"2021120800:2021120900"
},{
"name":"击杀月榜",
"interval":"2021120100:2022010100"
},{
"name":"击杀总榜",
"interval":"2021120100:-"
}
]
}
```
> 注： 如果传入key的数值没有对应配置的榜单追踪记录数据，则会直接跳过。例如如果只配置了击杀（key:kill）的相关榜单，则传入的其他数值作为无效数据被忽略。
### 02 POST 查询榜单
**server to server:** {bp_server}/bp/server/user/{user_id}/leaderboard
| Required Headers |
| ---------------------- |
| X-BytePower-Auth-Token |
**client to server:** {bp_server}/bp/leaderboard
| Required Headers |
| ------------------------- |
| X-BytePower-Sign |
| X-BytePower-Session-Token |
| 参数 | 类型 | 示例 | 说明 |
| ---------------- | ------ | ---------- | ----------------------------------------------------------------------------- |
| leaderboard_name | string | "击杀日榜" | 排行榜的名称 |
| x_backwards | int | 3 | 查看距今第3个历史榜单 |
| top | int | 50 | 查看榜单的top多少 |
| member | string | "user_123" | 查看榜单上user_123的排名 |
| around | int | 5 | 与member一起使用，查看member上下5名，加上member自己，总计最多11名的排名数据。 |
输入示例：
```json=
{
"queries":[
{
"leaderboard_name":"击杀日榜",
"top":100
},{
"leaderboard_name":"击杀日榜",
"x_backwards":3,
"top":100
},{
"leaderboard_name":"击杀日榜",
"member":"user_123"
},{
"leaderboard_name":"击杀日榜",
"member":"user_123",
"around":5
},{
"leadeboard_name":"击杀日榜",
"x_backwards":3,
"member":"user_123",
"around":5
}
]
}
```
返回示例：
code:200
```json=
{
"results":[
{
"leaderboard_name":"击杀日榜",
"top":[
{
"member":"user1",
"score":1000,
"rank":1
},
{
"member":"user2",
"score":999,
"rank":2
},
{
"member":"user3",
"score":980,
"rank":3
},
...
],
"order":"DESC",
"period":"2021120800:2021120900",
"request_time":"",
},
...
]
}
```