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

迁移脚本如何保证重复执行安全

迁移脚本如何保证重复执行安全

存档迁移最危险的不是“迁一次失败”,而是迁到一半后再次启动:同一字段可能被重复改名、数组被重复追加,或版本号先更新导致后续步骤被跳过。本节给出一套可重入的迁移方式,让中断、重试和跨多个历史版本都能安全处理。

学习目标

  • 理解迁移脚本为什么必须满足可重入和幂等要求
  • 能按版本顺序执行多个迁移步骤,并让重复执行得到一致结果
  • 能用原子提交避免“数据已改、版本号没改”或相反的半迁移状态

为什么重复执行会出问题

迁移脚本通常会修改字段名、补默认值或重组结构。如果脚本把“追加奖励”“删除旧字段”这类操作直接作用在持久化文件上,一旦进程在中途崩溃,下一次启动无法确定哪些操作已经完成。

真正需要保证的不是“脚本永远只跑一次”,而是脚本跑很多次也不会把数据越改越错。常见原则有两个:迁移步骤本身不要依赖副作用次数;数据变更与版本号更新要作为一个整体提交。

存档迁移的安全执行流程

把迁移设计成可重入流水线

每个迁移步骤只负责“从版本 N 转成 N+1”,并使用“目标字段不存在才补”“已有新字段则保留”等规则,避免重复追加或重复转换。读档时从存档记录的版本开始,一直执行到当前版本,因此从 1 直接跳到 4 也不需要单独写跨版本脚本。

迁移函数最好先在内存副本上完成全部转换和校验,再一次性写回。文件存档可使用临时文件加原子重命名;数据库存档则应把数据修改和版本号更新放在同一事务中。

主示例:顺序迁移并一次提交

下面的 Node.js 示例把版本 1 依次迁移到版本 4。每一步都会保留已经存在的目标字段,因此同一份输入重复运行,结果不会继续变化。

js
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));

预期输出:

text
{"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 快捷路径,否则两套逻辑很容易在默认值、字段清理或校验规则上产生分叉。

迁移脚本的可靠性来自可重入步骤、连续版本链和原子提交三者同时成立。做到这一点后,失败重试不再是特殊情况,而只是再次执行同一套确定性转换。

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

目录与阅读设置

阅读设置

17

记录一个想法

迁移脚本如何保证重复执行安全

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

登录哪都通