DivingFish/Lxns：风格性差异清理（低优先级） #4

New issue

Open

opened 2026-08-20 09:32:58 +00:00 by KumaAgent · 0 comments

KumaAgent commented

2026-08-20 09:32:58 +00:00

Member

背景

一批不影响功能正确性、纯粹是"跟文档写法不一致"或"文档能力没用满"的差异，优先级低，可以在空闲时顺手清理。来自 DivingFish/Lxns 实现 vs 文档偏移审查。

DivingFish

参考文档：https://maimai.diving-fish.com/manual/docs/developer/zh-api-document
df-backend 源码：https://github.com/Diving-Fish/maimaidx-prober/tree/main/database

Record 模型多出文档字段表未列出的 cid 字段（src/DivingFish/Models/Record.cs）—— 出现在个人接口（/player/records、/player/record）和 Developer 接口（/dev/player/records、/dev/player/record）两条路径，df-backend 的 record_json()（https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/models/maimai.py）实际固定返回 13 个字段，完全没有 cid。目前该属性可空、非 required，通常不会报错；若后端未来真的返回 "cid": null，需要留意反序列化风险。
GetHotSongsAsync/GetVoteResultAsync 调用的端点未出现在文档端点索引中 —— 纯文档遗漏，df-backend 里（https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/routes/maimai.py）/hot_music、/vote_result 都是真实存在、无需鉴权的公开路由。这条严格来说是文档站那边该修的，这里仅记录。
GetSongsAsync 未实现 ETag/If-None-Match 缓存（src/DivingFish/DfResourceClient.cs）—— GET /music_data 服务端真的实现了这套缓存（比较请求头 If-None-Match 与服务端 md5(json.dumps(md_cache))，相等返回 304，不等则返回全量数据并带 ETag/cache-control 响应头），客户端完全没有利用，每次调用 GetSongsAsync 都会拉取全量歌曲数据。

Lxns

参考文档：https://maimai.lxns.net/docs/api/maimai

Player.FriendCode 类型为 long，文档标注为 int（src/Lxns/Models/Player.cs）—— 好友码实际是 15 位数字，远超 Int32 范围，代码用 long 是必要且正确的处理，只是跟文档标注类型不一致。不需要改代码，仅记录以免日后被误"修正"回 int。
收藏品进度接口只实现了 plate 类型 —— 与 #3（Lxns：trophy 收藏品接口与 OIDC 支持）里"玩家收藏品进度 trophy/icon/frame 缺失"是同一件事，实质性跟踪以那张 issue 为准，这里不重复处理。
GetSongAsync 未处理曲目 ID 归一化（src/Lxns/LxnsResourceClient.cs）—— 文档开篇提示大于 10000 的曲目 ID 需要先对 10000 取余；仓库内部（Song.cs）确实存在"非 Standard 谱面用 Id+10000"的编号方案，但 GetSongAsync 把传入 id 原样拼接，没有归一化处理，也没有注释提示。目前尚无实际调用点触发这个组合，暂未造成故障。

## 背景一批不影响功能正确性、纯粹是"跟文档写法不一致"或"文档能力没用满"的差异，优先级低，可以在空闲时顺手清理。来自 DivingFish/Lxns 实现 vs 文档偏移审查。 ### DivingFish 参考文档：https://maimai.diving-fish.com/manual/docs/developer/zh-api-document df-backend 源码：https://github.com/Diving-Fish/maimaidx-prober/tree/main/database 1. **`Record` 模型多出文档字段表未列出的 `cid` 字段**（`src/DivingFish/Models/Record.cs`）—— 出现在个人接口（`/player/records`、`/player/record`）和 Developer 接口（`/dev/player/records`、`/dev/player/record`）两条路径，df-backend 的 `record_json()`（https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/models/maimai.py）实际固定返回 13 个字段，完全没有 `cid`。目前该属性可空、非 required，通常不会报错；若后端未来真的返回 `"cid": null`，需要留意反序列化风险。 2. **`GetHotSongsAsync`/`GetVoteResultAsync` 调用的端点未出现在文档端点索引中** —— 纯文档遗漏，df-backend 里（https://github.com/Diving-Fish/maimaidx-prober/blob/main/database/routes/maimai.py）`/hot_music`、`/vote_result` 都是真实存在、无需鉴权的公开路由。这条严格来说是文档站那边该修的，这里仅记录。 3. **`GetSongsAsync` 未实现 ETag/If-None-Match 缓存**（`src/DivingFish/DfResourceClient.cs`）—— `GET /music_data` 服务端真的实现了这套缓存（比较请求头 `If-None-Match` 与服务端 `md5(json.dumps(md_cache))`，相等返回 304，不等则返回全量数据并带 `ETag`/`cache-control` 响应头），客户端完全没有利用，每次调用 `GetSongsAsync` 都会拉取全量歌曲数据。 ### Lxns 参考文档：https://maimai.lxns.net/docs/api/maimai 4. **`Player.FriendCode` 类型为 `long`，文档标注为 `int`**（`src/Lxns/Models/Player.cs`）—— 好友码实际是 15 位数字，远超 Int32 范围，代码用 `long` 是必要且正确的处理，只是跟文档标注类型不一致。**不需要改代码**，仅记录以免日后被误"修正"回 int。 5. **收藏品进度接口只实现了 `plate` 类型** —— 与 [#3](../issues/3)（Lxns：trophy 收藏品接口与 OIDC 支持）里"玩家收藏品进度 trophy/icon/frame 缺失"是同一件事，实质性跟踪以那张 issue 为准，这里不重复处理。 6. **`GetSongAsync` 未处理曲目 ID 归一化**（`src/Lxns/LxnsResourceClient.cs`）—— 文档开篇提示大于 10000 的曲目 ID 需要先对 10000 取余；仓库内部（`Song.cs`）确实存在"非 Standard 谱面用 Id+10000"的编号方案，但 `GetSongAsync` 把传入 id 原样拼接，没有归一化处理，也没有注释提示。目前尚无实际调用点触发这个组合，暂未造成故障。

KumaAgent added the

状态：待评估

label

2026-08-20 09:33:06 +00:00