游戏客户端架构 / 系统课时
迁移脚本如何保证重复执行安全
迁移脚本如何保证重复执行安全
存档迁移最危险的不是“迁一次失败”,而是迁到一半后再次启动:同一字段可能被重复改名、数组被重复追加,或版本号先更新导致后续步骤被跳过。本节给出一套可重入的迁移方式,让中断、重试和跨多个历史版本都能安全处理。
学习目标
- 理解迁移脚本为什么必须满足可重入和幂等要求
- 能按版本顺序执行多个迁移步骤,并让重复执行得到一致结果
- 能用原子提交避免“数据已改、版本号没改”或相反的半迁移状态
为什么重复执行会出问题
迁移脚本通常会修改字段名、补默认值或重组结构。如果脚本把“追加奖励”“删除旧字段”这类操作直接作用在持久化文件上,一旦进程在中途崩溃,下一次启动无法确定哪些操作已经完成。
真正需要保证的不是“脚本永远只跑一次”,而是脚本跑很多次也不会把数据越改越错。常见原则有两个:迁移步骤本身不要依赖副作用次数;数据变更与版本号更新要作为一个整体提交。

把迁移设计成可重入流水线
每个迁移步骤只负责“从版本 N 转成 N+1”,并使用“目标字段不存在才补”“已有新字段则保留”等规则,避免重复追加或重复转换。读档时从存档记录的版本开始,一直执行到当前版本,因此从 1 直接跳到 4 也不需要单独写跨版本脚本。
迁移函数最好先在内存副本上完成全部转换和校验,再一次性写回。文件存档可使用临时文件加原子重命名;数据库存档则应把数据修改和版本号更新放在同一事务中。
主示例:顺序迁移并一次提交
下面的 Node.js 示例把版本 1 依次迁移到版本 4。每一步都会保留已经存在的目标字段,因此同一份输入重复运行,结果不会继续变化。
const CURRENT_VERSION = 4;
const migrations = {
1: (save) => ({
...save,
player: {
...save.player,
// 新字段已经存在时不覆盖,避免重复迁移改变结果
maxHp: save.player.maxHp ?? save.player.hpLimit ?? 100
},
version: 2
}),
2: (save) => ({
...save,
settings: save.settings ?? { volume: 1 },
version: 3
}),
3: (save) => ({
...save,
inventory: Array.isArray(save.inventory) ? save.inventory : [],
version: 4
})
};
function migrateSave(source) {
// 只修改副本;全部成功后再由持久化层一次性替换旧存档
let next = structuredClone(source);
while (next.version < CURRENT_VERSION) {
const migrate = migrations[next.version];
if (!migrate) {
throw new Error(`Missing migration for version ${next.version}`);
}
next = migrate(next);
}
return next;
}
const oldSave = {
version: 1,
player: { name: "Mira", hpLimit: 120 }
};
const first = migrateSave(oldSave);
const second = migrateSave(first);
console.log(JSON.stringify(first));
console.log(JSON.stringify(second));
console.log(JSON.stringify(first) === JSON.stringify(second));预期输出:
{"version":4,"player":{"name":"Mira","hpLimit":120,"maxHp":120},"settings":{"volume":1},"inventory":[]}
{"version":4,"player":{"name":"Mira","hpLimit":120,"maxHp":120},"settings":{"volume":1},"inventory":[]}
true这里保留 hpLimit 是刻意的:字段清理应放在兼容窗口结束后的专门迁移中,而不是在第一次结构升级时急着删除。
中断、重试和跨版本跳跃
如果进程在内存迁移阶段崩溃,只要正式存档尚未被替换,下次仍会从旧版本重新执行。若要写回文件,应先写临时文件,完成校验和刷盘后再原子替换正式文件;这样不会留下“内容是新版、版本号还是旧版”的半成品。
版本跳跃也应走连续链路。例如版本 1 的存档要升级到版本 4,就执行 1→2、2→3、3→4。不要另写一个 1→4 快捷路径,否则两套逻辑很容易在默认值、字段清理或校验规则上产生分叉。
迁移脚本的可靠性来自可重入步骤、连续版本链和原子提交三者同时成立。做到这一点后,失败重试不再是特殊情况,而只是再次执行同一套确定性转换。