pppy/osu-beatmap-difficulty-lookup-cache

osu-beatmap-difficulty-lookup-cache

概述

osu-beatmap-difficulty-lookup-cache 是一个基于内存的缓存层，专为查询无法轻易存储到数据库的谱面难度数据而设计，主要提供谱面星级（star rating）和属性（attributes）的快速查询服务。

版本说明

该项目是用于生产环境部署的系列项目之一，部署版本对生成正确结果至关重要。master 分支跟踪持续开发进度。若需使用与生产环境值匹配的正确版本，请参考 https://github.com/ppy/osu-infrastructure/wiki/Star-Rating-and-Performance-Points 获取最新信息。

核心功能与特性

• 基于内存缓存：高效存储和检索谱面难度数据，减少重复计算开销
• 多接口支持：提供谱面属性查询、星级查询和缓存清除功能
• 灵活参数：支持可选的规则集 ID（ruleset_id）和 mods 参数，适应不同查询需求

使用场景

适用于 osu! 相关应用或服务中，需要快速获取谱面难度信息（星级、属性）的场景，尤其适合对查询响应速度有较高要求的生产环境。

API 接口说明

1. 属性查询（Attributes）

请求说明

• 请求方式：POST
• 请求地址：http://localhost:80/attributes
• Content-Type：application/json
• 请求体参数：
  • beatmap_id（必填）：谱面 ID
  • ruleset_id（可选）：规则集 ID
  • mods（可选）： mods 列表，每个 mod 包含 acronym 字段（如 "DT"）

请求示例

bash
curl -X POST -H "Content-Type: application/json" \
    -d '{ "beatmap_id": 129891, "ruleset_id": 0, "mods": [ { "acronym": "DT" } ] }' \
    http://localhost:80/attributes

响应示例

json
{
  "aimStrain": 4.578457906273151,
  "speedStrain": 6.196480875019435,
  "approachRate": 10.333333333333332,
  "overallDifficulty": 9.777777777777779,
  "hitCircleCount": 1646,
  "spinnerCount": 2,
  "mods": [
    {
      "acronym": "DT",
      "speedChange": 1.5,
      "settingDescription": "",
      "ranked": false
    }
  ],
  "skills": [{}, {}],
  "starRating": 11.474577136820706,
  "maxCombo": 2385
}

2. 星级查询（Star Rating）

请求说明

• 请求方式：POST
• 请求地址：http://localhost:80/rating
• Content-Type：application/json
• 请求体参数：
  • beatmap_id（必填）：谱面 ID
  • ruleset_id（可选）：规则集 ID
  • mods（可选）： mods 列表，每个 mod 包含 acronym 字段

请求示例

bash
curl -X POST -H "Content-Type: application/json" \
    -d '{ "beatmap_id": 129891, "ruleset_id": 0, "mods": [ { "acronym": "DT" } ] }' \
    http://localhost:80/rating

响应示例

11.474577136820706

3. 缓存清除（Purge）

请求说明

• 请求方式：DELETE
• 请求地址：http://localhost:80/cache
• 查询参数：beatmap_id（必填）：需清除缓存的谱面 ID

请求示例

bash
curl -X DELETE \
    http://localhost:80/cache?beatmap_id=129891

使用方法

1. 部署镜像并启动服务，默认监听 80 端口
2. 通过上述 API 接口进行谱面难度数据查询或缓存管理
3. 根据需求传入可选参数 ruleset_id 和 mods 以获取特定条件下的难度数据

注意：ruleset_id 和 mods 参数在所有查询接口中均为可选，不提供时将使用默认值。