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

版本升级怎样自动迁移存档

版本升级怎样自动迁移存档

游戏更新后,新增字段、重命名属性或改变数据结构都可能让旧存档无法直接读取。可靠的做法不是在加载代码里堆满版本判断,而是建立从旧 schema 到新 schema 的单向迁移链,让每一步只负责相邻版本之间的转换,并在迁移完成后再进入正常业务校验。

学习目标

  • 设计从旧 schema 到当前 schema 的有序迁移链
  • 理解为什么迁移应按相邻版本逐步执行,而不是跨版本猜测
  • 实现可验证、可失败退出且不会直接破坏原存档的迁移流程

把版本迁移做成一条链

假设当前存档版本是 3,玩家仍可能持有版本 1 的文件。最稳定的路线不是直接写一个 v1ToV3,而是执行 v1 -> v2 -> v3。这样版本 2 的存档也可以复用后半段迁移逻辑,以后升级到版本 4 时只需新增 v3 -> v4。

存档 schema 有序迁移链

迁移器最好满足三个约束:输入版本明确、输出版本明确、一次只跨一个版本。迁移成功后立即更新 schemaVersion,下一步只根据新的版本继续处理。这样每一步都可以单独测试,也更容易判断失败发生在哪次升级。

用版本号驱动迁移器

下面使用 Java 的 Map<String, Object> 表示已经完成格式解析的存档对象。示例包含两个迁移器:版本 1 把 coins 改名为 gold,版本 2 新增 difficulty,最终升级到版本 3。

java
import java.util.LinkedHashMap;
import java.util.Map;

public class SaveMigrationDemo {
    interface Migrator {
        int fromVersion();
        int toVersion();
        Map<String, Object> migrate(Map<String, Object> save);
    }

    static class V1ToV2 implements Migrator {
        public int fromVersion() { return 1; }
        public int toVersion() { return 2; }

        public Map<String, Object> migrate(Map<String, Object> save) {
            // 字段改名时先复制值,再删除旧字段,避免同时存在两套含义。
            Object coins = save.remove("coins");
            save.put("gold", coins == null ? 0 : coins);
            save.put("schemaVersion", 2);
            return save;
        }
    }

    static class V2ToV3 implements Migrator {
        public int fromVersion() { return 2; }
        public int toVersion() { return 3; }

        public Map<String, Object> migrate(Map<String, Object> save) {
            // 新字段必须给旧存档确定的默认值,而不是留给运行时猜测。
            save.putIfAbsent("difficulty", "NORMAL");
            save.put("schemaVersion", 3);
            return save;
        }
    }

    static Map<String, Object> migrateToLatest(
            Map<String, Object> save,
            Map<Integer, Migrator> migrators,
            int latestVersion) {

        int version = (int) save.get("schemaVersion");
        while (version < latestVersion) {
            Migrator migrator = migrators.get(version);
            if (migrator == null || migrator.toVersion() != version + 1) {
                throw new IllegalStateException("Missing migrator from version " + version);
            }
            save = migrator.migrate(save);
            version = (int) save.get("schemaVersion");
        }
        return save;
    }

    public static void main(String[] args) {
        Map<String, Object> oldSave = new LinkedHashMap<>();
        oldSave.put("schemaVersion", 1);
        oldSave.put("playerName", "Ari");
        oldSave.put("coins", 120);

        Map<Integer, Migrator> migrators = Map.of(
            1, new V1ToV2(),
            2, new V2ToV3()
        );

        Map<String, Object> upgraded = migrateToLatest(oldSave, migrators, 3);
        System.out.println(upgraded);
    }
}

预期输出:

text
{schemaVersion=3, playerName=Ari, gold=120, difficulty=NORMAL}

这里用旧版本号作为迁移器索引,因此读取到版本 1 时只能找到 1 -> 2,完成后才能继续查找 2 -> 3。如果中间某一步缺失,程序立即失败,而不是尝试跳过未知结构。

迁移之后还要重新验证

迁移器只负责把数据结构转换成新 schema,并不能证明数据一定满足当前业务规则。例如旧版本允许金币为负数,而新版本禁止,那么结构升级成功后仍应执行一次当前版本的完整业务校验。

推荐的顺序是:解析原始文件,读取 schemaVersion,确认该版本处于支持范围,复制一份工作数据,依次执行迁移器,按当前 schema 做格式与业务验证,最后再写出升级后的存档。只有所有步骤成功,才替换正式文件。

对于比程序当前版本还新的存档,例如程序只认识版本 3 却读到版本 4,也不要尝试降级解析。那通常表示玩家使用过更新版本的客户端,正确处理是明确返回“不支持的未来版本”。

让迁移可测试也可重复判断

每个迁移器都应准备至少一组真实旧版本样本,并验证三个结果:目标字段是否正确生成、旧字段是否按设计保留或删除、输出的 schemaVersion 是否准确。完整链路还应覆盖从最老受支持版本一路升级到当前版本的测试。

迁移过程中最好不要依赖当前时间、随机数或外部网络,否则同一个旧存档多次迁移可能得到不同结果。确实需要新增值时,优先使用明确的默认值或由旧字段确定性计算。

当版本升级被拆成独立的 vN -> vN+1 迁移器后,读档代码只需要负责选择和串联迁移步骤。新增版本时补上一段新的迁移器即可,不必反复修改所有历史版本的判断逻辑。

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

目录与阅读设置

阅读设置

17

记录一个想法

版本升级怎样自动迁移存档

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

登录哪都通