《游戏引擎实现原理》17.3 版本化与迁移

{ "$type": "SaveSlot", "$v": 1, "hp": 80, "name": "Isla", "gold": 12 }

// file: src/core/migration.ts
// tier: L1
// verify: npx vitest run src/core/migration.test.ts
//
// helio 内核：schema 版本迁移。
// 存档里带 $v，加载时沿迁移链逐级升到当前版本。

import type { TypeRegistry } from './registry.ts';
import { JSON_TYPE_KEY, JSON_VERSION_KEY } from './json-serde.ts';

export type MigrationStep = {
  readonly from: number;
  readonly to: number;
  readonly apply: (raw: Record<string, unknown>) => Record<string, unknown>;
};

export class MigrationRegistry {
  #steps = new Map<number, MigrationStep>();

  add(step: MigrationStep): void {
    if (this.#steps.has(step.from)) {
      throw new Error(`Duplicate migration from v${step.from}`);
    }
    this.#steps.set(step.from, step);
  }

  get(from: number): MigrationStep | undefined {
    return this.#steps.get(from);
  }
}

export type MigrationResult = {
  data: Record<string, unknown>;
  from: number;
  to: number;
  /** 实际走过的迁移链，如 ["1->2", "2->3"]。 */
  applied: string[];
};

/** 沿迁移链把 raw 升到 targetVersion；缺环即抛错，绝不静默降级。 */
export function migrate(
  mig: MigrationRegistry,
  raw: Record<string, unknown>,
  targetVersion: number,
): MigrationResult {
  const name = raw[JSON_TYPE_KEY];
  const from = raw[JSON_VERSION_KEY];
  if (typeof name !== 'string' || typeof from !== 'number') {
    throw new Error('Invalid save: missing $type/$v');
  }
  let version = from;
  let data = { ...raw };
  const applied: string[] = [];
  while (version < targetVersion) {
    const step = mig.get(version);
    if (!step) throw new Error(`No migration from v${version} for ${name}`);
    data = step.apply(data);
    applied.push(`${step.from}->${step.to}`);
    version = step.to;
  }
  data[JSON_VERSION_KEY] = version;
  return { data, from, to: version, applied };
}

/** 迁移后校验：描述符里每个字段都必须在数据里出现，缺一即抛错。 */
export function validateAgainst(
  reg: TypeRegistry,
  typeName: string,
  data: Record<string, unknown>,
): void {
  const desc = reg.require(typeName);
  for (const f of desc.fields) {
    if (!(f.name in data)) {
      throw new Error(`Migrated data missing field: ${f.name} (${typeName})`);
    }
  }
}

// file: src/core/save-migrations.ts
// tier: L1
// verify: npx vitest run src/core/migration.test.ts
//
// 《微光岛》存档槽 SaveSlot 的迁移函数表：v1 → v2 → v3。

import { MigrationRegistry } from './migration.ts';

export function buildSaveMigrations(): MigrationRegistry {
  const mig = new MigrationRegistry();

  // v1 → v2：hp 改名 health；新增 mana，默认 50。
  mig.add({
    from: 1,
    to: 2,
    apply: (raw) => ({
      $type: raw.$type,
      $v: 2,
      health: raw.hp,
      name: raw.name,
      gold: raw.gold,
      mana: 50,
    }),
  });

  // v2 → v3：移除 gold；新增 level，默认 1。
  mig.add({
    from: 2,
    to: 3,
    apply: (raw) => ({
      $type: raw.$type,
      $v: 3,
      health: raw.health,
      name: raw.name,
      mana: raw.mana,
      level: 1,
    }),
  });

  return mig;
}

// file: src/core/migration-demo.ts
// tier: L1
// verify: node src/core/migration-demo.ts
//
// 加载一份 v1 存档，迁移到 v3，打印迁移前后的字段差异。

import { migrate } from './migration.ts';
import { buildSaveMigrations } from './save-migrations.ts';

const mig = buildSaveMigrations();

const v1Save = { $type: 'SaveSlot', $v: 1, hp: 80, name: 'Isla', gold: 12 };
console.log('loaded (v1):', JSON.stringify(v1Save));

const result = migrate(mig, v1Save, 3);
console.log('applied    :', result.applied.join(' -> '));
console.log('migrated   :', JSON.stringify(result.data));

loaded (v1): {"$type":"SaveSlot","$v":1,"hp":80,"name":"Isla","gold":12}
applied    : 1->2 -> 2->3
migrated   : {"$type":"SaveSlot","$v":3,"health":80,"name":"Isla","mana":50,"level":1}

// snippet: 存档加载入口——解析、迁移、校验、解码
const CURRENT_VERSION = 3;
const raw = JSON.parse(saveText) as Record<string, unknown>; // { $type, $v, ... }
const { data, applied } = migrate(mig, raw, CURRENT_VERSION);
validateAgainst(reg, raw.$type as string, data);
const slot = deserializeFromJson(reg, data); // 17.1 的解码器
if (applied.length > 0) log.info(`save migrated: ${applied.join(' -> ')}`);

// snippet: 迁移的边界用例——缺环、缺字段都必须抛错
it('缺少迁移环时抛错，绝不静默降级', () => {
  const mig = new MigrationRegistry();
  mig.add({ from: 1, to: 2, apply: (raw) => ({ ...raw, $v: 2 }) });
  expect(() => migrate(mig, v1Save, 3)).toThrow(/No migration from v2/);
});

it('缺字段的迁移结果无法通过校验', () => {
  expect(() => validateAgainst(reg, 'SaveSlot', { health: 1, name: 'x' }))
    .toThrow(/missing field: mana/);
});