游戏客户端架构 / 系统课时
给存档加上版本号和元数据
给存档加上版本号和元数据
一个能“存下来”的 JSON 还不算稳定存档。真正可维护的存档需要额外记录格式版本、创建时间、槽位、应用版本等元数据,这些字段不直接描述玩家状态,却决定了后续能否识别旧档、迁移数据、展示槽位信息并安全拒绝不兼容文件。
学习目标
- 设计一组最小但足够长期使用的存档元数据字段。
- 区分
schemaVersion与应用版本,避免把两者混为一谈。 - 明确元数据在读档、迁移和存档列表中的实际用途。
为什么元数据要和游戏状态分开
玩家金币、任务进度、角色位置属于“业务状态”;版本号、创建时间、槽位名称属于“描述这份存档的信息”。把两类数据放在同一层,会让后续迁移、展示和校验逻辑不断与业务字段耦合。
更稳妥的做法是把存档拆成 meta 与 data 两部分。读档程序可以先只解析 meta,判断这份文件是否可读取,再决定是否继续解析体量更大的业务数据。
{
"meta": {
"schemaVersion": 3,
"createdAt": "2026-10-08T03:20:00Z",
"updatedAt": "2026-10-08T04:10:00Z",
"slotId": "slot-01",
"slotName": "主线进度",
"appVersion": "1.8.0"
},
"data": {
"player": {
"level": 18,
"gold": 2450
}
}
}这不是必须照抄的标准,而是一种职责清晰的基线。实际项目可以增减字段,但应尽量保持字段语义稳定。
schemaVersion 只描述存档结构
schemaVersion 用来回答一个问题:这份存档采用第几版数据结构? 当字段名称、嵌套层级、枚举含义或数据类型发生破坏性变化时,就应该提升它。
例如,版本 1 把玩家坐标写成 x、y,版本 2 改成 position: {x, y},这属于存档结构变化,应提升 schemaVersion。相反,只修复 UI Bug 或调整音量默认值,并不一定需要修改存档版本。
不要直接用 appVersion 代替 schemaVersion。应用可能从 1.8.0 升级到 1.8.1,但存档结构完全没变;也可能在开发阶段连续修改两次存档结构,却仍处于同一个应用版本号中。
时间与槽位信息解决展示问题
createdAt 记录首次创建时间,updatedAt 记录最近一次成功保存时间。建议统一使用带时区含义的 ISO 8601 字符串,并优先保存 UTC,例如 2026-10-08T04:10:00Z。展示时再转换为玩家所在时区。
slotId 应是程序稳定使用的标识,例如 slot-01;slotName 则是给玩家看的名称,例如“主线进度”。二者分开后,即使玩家修改存档名称,底层文件绑定关系也不会变化。
如果游戏支持自动存档和快速存档,也可以增加 slotType,例如 manual、auto、quick。但只有真正存在这些槽位类型时才应加入,避免为了“将来可能用到”堆积无意义字段。
appVersion 用来辅助诊断兼容性
appVersion 表示创建或最后写入这份存档的游戏版本。它非常适合日志和客服排查,例如玩家反馈“升级后无法读取旧档”时,可以快速确认存档最后由哪个版本写入。
但兼容性判断的第一依据仍应是 schemaVersion。常见读取顺序是:先检查格式版本,再决定是否迁移,最后再把 appVersion 作为诊断信息记录下来。
可以把判断规则设计得很明确:当前程序支持版本 2~4;版本 1 先迁移到 2;高于 4 的存档来自更高版本客户端,应停止读档并提示“当前版本无法读取该存档”。
哪些字段值得长期保留
元数据不宜越多越好。一个字段值得进入存档头部,通常至少满足“读档前要判断”“存档列表要展示”或“问题排查要定位”中的一个。
推荐的最小集合是 schemaVersion、createdAt、updatedAt、slotId、appVersion;如果产品允许玩家命名槽位,再加入 slotName。像设备型号、当前帧率、临时调试开关等信息通常不应进入长期存档格式。
设计完成后,可以做一个简单验收:随机取一份存档,只读取 meta,确认程序能够回答“这是哪个槽位、哪版结构、何时更新、由哪个应用版本写入”。如果这些问题无需解析业务数据就能得到答案,这组元数据已经具备了良好的可维护性。