鸿蒙HarmonyOS NEXT设备升级应用数据迁移流程

数据迁移是什么

什么是数据迁移，对用户来讲就是本地数据的迁移，终端设备从HarmonyOS 3.1 Release API 9及之前版本（单框架）迁移到HarmonyOS NEXT（双框架）后保证本地数据不丢失。例如，我在某APP上面是登录状态，从单框架升级到双框架打开APP后依旧是登录状态，这就是数据迁移，并不是云端数据的处理，是本地数据的处理。当然，这只是其中一个用户信息，除用户信息外还有一系列开发者用到的设备数据等等，需要迁移。

HarmonyOS NEXT提供了“数据迁移框架”和“备份恢复框架”，为开发者提供应用数据的迁移和转换能力。开发者完成适配，APK应用切换为HarmonyOS应用后，可继承原APK应用中适配HarmonyOS应用的数据。流程大概如下：

数据迁移机制

应用数据迁移任务需要执行的步骤包括：应用安装，数据迁移和数据恢复。

1. 应用安装步骤：
   1. “数据迁移框架”向华为应用市场发送HarmonyOS应用下载和安装请求。
   2. 华为应用市场下载并安装HarmonyOS应用。
2. 数据迁移步骤：

在HarmonyOS应用安装完成之后，“数据迁移框架”将应用沙箱数据从中间目录搬迁到备份恢复目录。

3. 数据恢复步骤：
   1. 在应用数据搬迁到备份恢复目录后，“数据迁移框架”向“备份恢复框架”发送应用数据恢复请求。
   2. “备份恢复框架”拉起应用的“BackupExtensionAbility”独立进程，启动应用数据恢复。
   3. 应用通过“BackupExtensionAbility”从备份恢复目录加载APK应用的数据，处理后保存到HarmonyOS应用沙箱中，完成应用数据恢复。
   4. “备份恢复框架”在应用数据恢复完成后，清空备份恢复目录。

应用适配流程

迁移目录对应关系

开发者需要在HarmonyOS应用的代码中，实现“BackupExtensionAbility”，使应用接入到“备份恢复框架”中，完成应用数据的转换和迁移。后续HarmonyOS应用通过访问HarmonyOS应用沙箱获取应用的数据。

备份恢复目录如下表中所示：

APK应用沙箱目录与备份恢复目录映射关系

代码实现

创建BackupExtensionAbility，APP在BackupExtensionAbility中实现应用的数据转换和迁移逻辑。

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';

const TAG = `BackupExtensionAbility`;

/**
 * serviceExt进程入口
 */
export default class BackupExtension extends  BackupExtensionAbility {
  onBackup () {
    console.log(TAG,`onBackup ok`);
  }

  /**
   * 数据恢复处理接口。接口是同步接口，其内部所有的异步操作请进行同步等待。
   *
   * @param bundleVersion 版本信息
   */
  async onRestore (bundleVersion : BundleVersion): Promise<void> {
    console.log(TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`);
    //bundleVersion.name的前缀为“0.0.0.0”时，表示终端设备从HarmonyOS升级到HarmonyOS NEXT数据迁移场景
    if (bundleVersion.name.startsWith("0.0.0.0")){
      // 在此处实现终端设备从HarmonyOS 4.x升级到HarmonyOS NEXT后，应用数据的转换和迁移
      // 涉及异步操作请进行同步等待
      console.log(TAG, `HarmonyOS to HarmonyOS NEXT scenario`);
    } else {
      // 在此处实现从HarmonyOS NEXT设备迁移到HarmonyOS NEXT设备后，应用数据的处理。无特殊要求，可以空实现
      // 涉及异步操作请进行同步等待
      console.log(TAG, `Other scenario`);
    }
  }
}

module.json5中配置

"extensionAbilities": [
  {
    "description": "DemoBackupExtension",
    "icon": "$media:app_icon",
    "name": "BackupExtensionAbility",
    "srcEntry": "./ets/backupExtension/BackupExtension.ets",  // 对应BackupExtension.ets在代码仓中的位置
    "type": "backup",                                         // 类型需要选择backup
    "exported": false,
    "metadata": [                                             // 对应注册的元数据资源
      {
        "name": "ohos.extension.backup",
        "resource": "$profile:backup_config"
      }
    ]
  }
]

数据迁移结果验证

开发者验证

1、将单架构要迁移数据的APP数据通过Android Studio 按下面对应目录导出zip包，然后放到手机本地，或者登录华为账号放到我的云盘里面方便登录下载。

2、下载手动迁移工具 **MigrateTool ，**选择刚才导出的zip文件，再输入要迁入到的应用签名，点击启动迁移，迁移提示成功之后（注意如果迁移失败，可能是zip数据问题，根据上面目录排查）。打开APP验证即可功能。

)

QA端到端验证

如果是已经上架的应用，可以发布一个内测版本，然后审核通过后指定设备做线上验证。

1. 当前开发者持有的终端设备为HarmonyOS NEXT。开发者在验证升级前，需要将设备从HarmonyOS NEXT回退到HarmonyOS。在应用适配完成并上架到华为应用市场之后，开发者需要联系华为方技术支撑人员提供版本，支持开发者将终端设备从HarmonyOS NEXT回退到HarmonyOS。系统回退的入口为：设置 > 通用 > 开发者模式 > 系统回退。
2. 将终端设备回退到HarmonyOS后，需要预置APK应用的数据。在数据预置完成后，开发者需要联系华为方技术支撑人员提供版本，支持开发者将终端设备从HarmonyOS升级到HarmonyOS NEXT。系统更新的入口为：设置 > 系统和更新 > 软件更新。
3. 终端设备成功从HarmonyOS升级到HarmonyOS NEXT，走过开机向导界面后，开始执行应用数据迁移。开发者请在应用数据迁移结束后，验证应该数据迁移的结果。