游戏客户端架构 / 系统课时

给存档加上版本号和元数据

给存档加上版本号和元数据

一个能“存下来”的 JSON 还不算稳定存档。真正可维护的存档需要额外记录格式版本、创建时间、槽位、应用版本等元数据,这些字段不直接描述玩家状态,却决定了后续能否识别旧档、迁移数据、展示槽位信息并安全拒绝不兼容文件。

学习目标

  • 设计一组最小但足够长期使用的存档元数据字段。
  • 区分 schemaVersion 与应用版本,避免把两者混为一谈。
  • 明确元数据在读档、迁移和存档列表中的实际用途。

为什么元数据要和游戏状态分开

玩家金币、任务进度、角色位置属于“业务状态”;版本号、创建时间、槽位名称属于“描述这份存档的信息”。把两类数据放在同一层,会让后续迁移、展示和校验逻辑不断与业务字段耦合。

更稳妥的做法是把存档拆成 meta 与 data 两部分。读档程序可以先只解析 meta,判断这份文件是否可读取,再决定是否继续解析体量更大的业务数据。

json
{
  "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,确认程序能够回答“这是哪个槽位、哪版结构、何时更新、由哪个应用版本写入”。如果这些问题无需解析业务数据就能得到答案,这组元数据已经具备了良好的可维护性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

给存档加上版本号和元数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通