第 10 期 · M2 角色与游戏接口:游戏里终于能看到皮肤了
· 阅读需 4 分钟
M2 第二部分完成了从"上传"到"在游戏里看见"的最后一段:用户创建角色、给角色穿上衣柜里的皮肤和披风,CustomSkinLoader、UniSkinMod 和只认固定图片地址的客户端都能按角色名拿到皮肤。
本期完成
- 角色(
internal/player):创建(扣积分)、改名、删除(按积分流水退还当时支付的积分)、穿戴。名字由唯一索引判重、不区分大小写;名字规则沿用 BS 的 official / cjk / utf8 / custom,另外在任何规则下都禁止空格和/ \ ? # %。 - UUID:创建时就分配。
v3与离线服算法相同(md5("OfflinePlayer:" + 名字)),改名随之变化;v4随机,改名不变。用 Notch 的离线 UUIDb50ad385-829d-3141-a216-7e7d7539ba7f做了校验。 - 穿戴:只能穿自己衣柜里的材质,皮肤只能是皮肤、披风只能是披风(修 BS C07);材质删除后角色自动脱下。
- 游戏接口:CustomSkinLoader(
/{名字}.json、/csl/)、UniSkinMod(/usm/)、Legacy(/skin/、/cape/),格式逐字段对照 BS 与插件源码;名字不区分大小写、返回库内写法;主人封禁 403;可选的 204;默认缓存 60 秒,支持If-Modified-Since。 - 前端:
/user/player角色页(衣柜选择器、UUID 复制、角色数据链接),材质页的"穿到角色上"。 - 设计记录:ADR 0018 角色、UUID 与游戏皮肤接口。
本地实测(skinloom up --dev)
- 上传纤细皮肤、经典皮肤、披风;在角色页输入
bad name!→ 提示"角色名不符合要求";创建Steve→ 积分 997 → 897,显示带连字符的 UUID。 - 点"选择皮肤",从衣柜选择器里选纤细皮肤,再选披风:卡片上出现预览。
- 用 curl 当游戏客户端:
/steve.json返回{"username":"Steve","skins":{"slim":"…"},"cape":"…"},Cache-Control: public, max-age=60,带Last-Modified;/usm/STEVE.json返回model_preference: ["slim"];/skin/Steve.png、/cape/Steve.png返回图片;/Nobody.json404。 - 在经典皮肤的材质页选择角色并"穿上这个皮肤":
/Steve.json的模型变成default、哈希随之改变。 - 删除角色:积分退回 997。服务端日志没有警告。
测试
- 名字规则(四种规则、长度、禁止字符、数据库上限)、两种 UUID(含 Notch 的已知值、v4 版本位)。
- 角色:创建扣分、大小写不同的重名、积分不足、改名时 v3/v4 的 UUID 行为、改到已被占用的名字、他人的角色、删除退还当时价格、免费角色不退分;四个用户同时用不同大小写抢注同一个名字,只有一个成功、只扣一次分。SQLite 与 PostgreSQL。
- 穿戴:披风当皮肤、皮肤当披风、不在衣柜、不存在的材质、脱下、材质删除后自动脱下;资料查询的大小写、封禁、注销。
- HTTP:角色管理接口全流程;CSL / USM 的逐字节 JSON、空皮肤时的
null、不同大小写、If-Modified-Since返回 304、204 开关、Legacy 返回的就是材质文件、封禁 403、删除后不再出现。汉字名分别用大写与小写十六进制百分号编码请求——去掉解码那一行,小写编码的请求就会失败,测试能抓到。 - 前端:UUID 格式化;类型检查、单元测试、生产构建、
bun audit。 - 全量回归:
go test ./...(含 PostgreSQL 18)、vet、staticcheck、govulncheck;生成代码无差异、迁移无漂移。MySQL 迁移为手写,由 CI 验证。
问题与风险
- 每次请求游戏接口要查三次数据库(角色、皮肤、披风,都走索引);进程内缓存与失效等压测(M5)证明需要时再做。
- 注册时直接用角色名(BS 的
register_with_player_name)与后台角色管理还没有做。
下期计划
M2 第三部分:收藏与取消收藏(积分与上传者奖励)、材质编辑(改名、改类型时重新校验尺寸并处理穿着它的角色、公开↔私有的对称计费)、删除材质(引用计数删除文件、孤儿文件清理)、签到与用户仪表盘。