034-数据模型Versioning与迁移

春卷同学

20人浏览 · 2026-07-17 23:28:37

春卷同学 · 2026-07-17 23:28:37 发布

数据模型 Versioning 与迁移 — 应对应用升级的数据兼容性

一、引言

随着应用功能迭代，数据库表结构不可避免需要变更——新增字段、修改字段类型、拆分表结构等。如果直接修改表结构而不考虑数据兼容性，用户升级应用后将面临数据丢失或应用崩溃的风险。鸿蒙 RDB 提供了数据库版本管理和迁移机制，允许开发者在版本升级时执行有序的数据迁移。MoneyTrack 在从个人记账到家庭记账的演进过程中，通过合理的版本迁移策略实现了数据模型的无缝扩展。

二、核心知识点

2.1 数据库版本升级

RDB 数据库通过 version 属性管理数据库版本号。每次创建或打开数据库时，系统会比较当前版本号和期望版本号，如果不一致则触发迁移流程：

const STORE_CONFIG: StoreConfig = {
  name: 'moneytrack.db',
  securityLevel: SecurityLevel.S1,
  version: 3  // 当前版本号
}

版本号从 1 开始递增，每次表结构变更时将版本号加 1。版本号是正整数且只能增大，不能回退。

2.2 版本升级迁移流程

2.3 完整的多版本迁移代码

onUpgrade 回调中，每个版本的迁移代码使用 if (oldVersion < N) 的条件判断结构，确保从任意旧版本升级到最新版本：

const STORE_CONFIG: StoreConfig = {
  name: 'moneytrack.db',
  securityLevel: SecurityLevel.S1,
  version: 3,
  onUpgrade: (store, oldVersion, newVersion) => {
    console.log(`数据库升级: ${oldVersion} → ${newVersion}`)

    // 版本 1 → 2：新增 member_id 字段和 members 表
    if (oldVersion < 2) {
      store.executeSql(
        'ALTER TABLE transactions ADD COLUMN member_id TEXT DEFAULT \'\''
      )
      store.executeSql(
        'ALTER TABLE transactions ADD COLUMN owner_id TEXT DEFAULT \'\''
      )
      store.executeSql(`
        CREATE TABLE IF NOT EXISTS members (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          name TEXT NOT NULL,
          avatar TEXT,
          role INTEGER DEFAULT 0
        )
      `)
      console.log('迁移 v1→v2 完成：新增 member 相关字段和表')
    }

    // 版本 2 → 3：新增 attachments 附件表和 budget 预算表
    if (oldVersion < 3) {
      store.executeSql(`
        CREATE TABLE IF NOT EXISTS attachments (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          transaction_id INTEGER NOT NULL,
          file_path TEXT NOT NULL,
          created_at TEXT DEFAULT (datetime('now')),
          FOREIGN KEY (transaction_id) REFERENCES transactions(id)
        )
      `)
      store.executeSql(`
        CREATE TABLE IF NOT EXISTS budgets (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          month TEXT NOT NULL,
          amount REAL NOT NULL,
          category_id INTEGER,
          FOREIGN KEY (category_id) REFERENCES categories(id)
        )
      `)
      console.log('迁移 v2→v3 完成：新增附件表和预算表')
    }
  }
}

2.4 降级处理说明

数据库版本号不能回退——如果将 StoreConfig 的 version 设为一个比当前数据库文件版本更小的值，系统会触发 onDowngrade 回调或直接报错：

// ⚠️ 错误做法：将已升级到版本 3 的数据库降回版本 2
const STORE_CONFIG: StoreConfig = {
  version: 2,  // 当前数据库实际是版本 3，会触发降级错误
}

降级场景的处理策略：

鸿蒙 RDB 默认不支持自动降级，降级时会抛出异常
如需"降级"，正确做法是：备份用户数据 → 删除旧数据库文件 → 重新创建新版本数据库 → 导入数据
在开发测试阶段，可通过卸载应用清除数据库文件来重置版本

三、数据迁移策略详述

3.1 各类表结构变更的操作

变更类型	SQL 操作	是否影响存量数据
新增字段	`ALTER TABLE ADD COLUMN`	否（新增字段可设默认值）
新增表	`CREATE TABLE IF NOT EXISTS`	否
修改字段类型	创建新表 → 复制数据 → 删除旧表	需要数据迁移
删除字段	创建新表（不含该字段）→ 复制数据 → 删除旧表	会丢失该字段数据
重命名表	`ALTER TABLE RENAME TO`	否（但需更新引用）

3.2 迁移失败的处理

迁移过程中的任何失败都可能导致数据库处于不一致状态。正确的做法是使用事务保证迁移的原子性：

// 使用事务包裹迁移逻辑
onUpgrade: (store, oldVersion, newVersion) => {
  try {
    store.beginTransaction()

    if (oldVersion < 2) {
      store.executeSql('ALTER TABLE ...')
    }
    if (oldVersion < 3) {
      store.executeSql('CREATE TABLE ...')
    }

    store.commit()
  } catch (err) {
    store.rollback()
    console.error('数据库迁移失败，已回滚:', err)
    // 提示用户重新安装或联系技术支持
    // 鸿蒙 RDB 迁移失败后，数据库文件可能无法正常使用
  }
}

迁移失败后的处理建议：

记录详细的错误日志，包括 oldVersion、newVersion 和错误堆栈
如果迁移失败，建议提示用户：应用数据需要重置，请备份后重试
在生产环境中，重大迁移前应先备份数据库文件
测试阶段应覆盖所有可能的版本升级路径

3.3 字段兼容性扩展

良好的前向兼容设计允许旧版本应用在新版数据库上正常运行（至多丢失部分新功能）。常见做法包括：

新字段设置默认值（DEFAULT）
使用 IF NOT EXISTS / IF EXISTS 安全操作表结构
查询时使用 COALESCE 处理可能不存在的字段

// 兼容性查询：COALESCE 处理新版本新增的字段
const sql = `
  SELECT *, COALESCE(member_id, '') as member_id
  FROM transactions
`

四、项目代码案例

4.1 从个人记账到家庭记账的数据模型扩展

MoneyTrack 在演进过程中经历了从个人记账到家庭记账的数据模型扩展：

版本 1 → 版本 2（个人 → 家庭）：

transactions 表新增 member_id 字段（TEXT，默认空字符串）
transactions 表新增 owner_id 字段（标识账单创建者）
新增 members 表（家庭成员信息）

版本 2 → 版本 3（功能增强）：

新增 attachments 表（账单附件）
新增 budgets 表（月度预算）

4.2 迁移脚本的幂等性

迁移脚本应具备幂等性——多次执行不会产生副作用：

使用 IF NOT EXISTS 创建表
使用 ALTER TABLE ... ADD COLUMN 前检查列是否存在（通过 PRAGMA table_info）
版本条件判断确保每段迁移代码只执行一次

4.3 测试迁移的最佳实践

// 单元测试：遍历所有版本升级路径
async function testMigration(context: Context) {
  const testVersions = [1, 2, 3]

  for (const fromVersion of testVersions) {
    for (const toVersion of testVersions) {
      if (fromVersion >= toVersion) continue

      console.log(`测试迁移路径: v${fromVersion} → v${toVersion}`)
      const config: StoreConfig = {
        name: `test_${fromVersion}_to_${toVersion}.db`,
        version: toVersion,
        onUpgrade: /* 生产环境的迁移逻辑 */
      }
      // 验证迁移后表结构正确
      // 验证数据未丢失
      // 清理测试数据库
    }
  }
}