从HarmonyOS升级到HarmonyOS NEXT-环信SDK数据迁移

2024年6月21日 HarmonyOS NEXT （后续称之为 NEXT） 正式发布，随着 NEXT 稳定版的徐徐临近，各个应用及SDK正在忙于适配 NEXT 体系，同样也面临着体系升级时怎样对数据的迁移适配。本文通过使用环信 SDK 先容怎样从 HarmonyOS 体系升级到 NEXT 体系时，进行应用数据的迁移适配。
   注：
  1、本文章需要在华为官方迁移适配文档基础上进行阅读。
  2、下文中 {userId} 当前固定为100，见华为官方说明。
  一、应用数据迁移步骤

在进行数据迁移之前，我们需要先相识升级到NEXT体系，应用数据迁移需要进行哪些步骤。下图是整个迁移流程：

图中1-4步骤，均是由鸿蒙体系触发完成，开发者需要实现自定义的“BackupExtensionAbility”逻辑，实现自定义的数据恢复及转换逻辑。
1. HarmonyOS APK沙箱数据搬迁到中心目录

在升级的过程中，HarmonyOS体系会按照一定的规则，将应用的沙箱数据放置到四个数据目录中，然后这些数据会被整体压缩后搬迁到中心目录。
开发过程中，应用数据常用到的数据目录为：
   /data/user/{userId}/{APK包名}/
  /data/media/{userId}/Android/data/{APK包名}/
  /data/user/{userId}/{APK包名}/ 对应的路径为 HarmonyOS APK 应用的 data/data/{包名} 路径目录，而 /data/media/{userId}/Android/data/{APK包名}/ 对应的是应用的 sdcard/Android/data/{包名}/ 路径目录。应用进行数据迁移的话，重要是关注这两块的数据迁移。
2. 华为应用市场安装 NEXT 版本的应用

NEXT体系的“数据迁移框架”会从华为应用市场根据开发者账号下载对应的 NEXT 版本的应用。具体关联，请参考文档：HarmonyOS应用关联Android应用。
3. 数据导入

在 NEXT 应用安装完成后，“数据迁移框架”将应用沙箱数据从中心目录搬迁到备份恢复目录。
APK应用沙箱目录与备份恢复目录映射关系见下表中所示：
  APK应用沙箱目录
  备份恢复目录
  备份恢复目录获取方式
  /data/user_de/{userId}/
{APK包名}/
  /data/storage/el1/base/.backup/
restore/{APK包名}/de/
  this.context.area = contextConstant.AreaMode.EL1;
let deSourcePath = this.context.backupDir + "restore/{APK包名}/de/"
  /data/user/{userId}/
{APK包名}/
  /data/storage/el2/base/.backup/
restore/{APK包名}/ce/
  this.context.area = contextConstant.AreaMode.EL2;
let ceSourcePath = this.context.backupDir + "restore/{APK包名}/ce/"
  /data/media/{userId}/
Android/data/{APK包名}/
  /data/storage/el2/base/.backup/
restore/{APK包名}/A/data/
  this.context.area = contextConstant.AreaMode.EL2;
let dataSourcePath = this.context.backupDir + "restore/{APK包名}/A/data/"
  /data/media/{userId}/
Android/obb/{APK包名}/
  /data/storage/el2/base/.backup/
restore/{APK包名}/A/obb/
  this.context.area = contextConstant.AreaMode.EL2;
let obbSourcePath = this.context.backupDir + "restore/{APK包名}/A/obb/"
  4. 数据转换

• 在应用数据搬迁到备份恢复目录后，“数据迁移框架”向“备份恢复框架”发送应用数据恢复请求。
  
• “备份恢复框架”拉起应用的“BackupExtensionAbility”独立历程，启动应用数据恢复。
  

• 在“BackupExtensionAbility”独立历程中，开发者通过重写“onRestore”添加自定义逻辑，将备份恢复目录中的数据处理后保存到 NEXT 应用的沙箱中，完成应用的数据恢复。
  
• “备份恢复框架”在应用数据恢复完成后，会清空备份恢复目录。
  

5. 启动 NEXT 应用，应用读取应用沙箱数据。


下面通过先容环信 SDK 的数据迁移，来先容具体的迁移过程。
二、需要迁移数据分析

以下为环信 SDK需要迁移的数据：

序号	数据名称	路径或者文件	备注
1	SDK 数据库文件夹	data/data/{包名}/files/easemobDB/
2	SDK 数据库相关文件夹	data/data/{包名}/files/easemobDBPW/
3	SDK 配置文件	data/data/{包名}/files/em_ap_config.json data/data/{包名}/files/em_config.json data/data/{包名}/files/server.json
4	SDK 附件	sdcard/Android/data/{包名}/{AppKey}/

• 环信 SDK 已经适配了在 NEXT 应用使用 HarmonyOS APK 数据库的逻辑。1 和 2 部分数据迁移到 NEXT的指定文件夹即可。
  
• 第 3 部分的配置文件直接迁移到NEXT的指定文件夹即可。
  
• SDK 的附件，有如下情况：
  

（1）消息中的本地路径存储的是 Uri 。
这部分是在公共媒体库中，进行体系的升级后，经咨询华为，目前还没有映射关系。目前的处理可以参照如下思绪：

• 判断本地文件不存在后，调用 `ChatManager#downloadAttachment` 或者 ChatManager#downloadThumbnail 方法从服务器下载文件资源后，然后再展示。
  
• 如果服务器文件逾期，需要展示默认图片。
  

（2）消息中的本地路径存储的是第 4 部分的文件路径，则需要对路径进行转换。举比方下：
迁移过来的数据库中存储的附件本地路径为：
   /storage/emulated/0/Android/data/{包名}/{appKey}/files/{receiver id}/{sender id}/f6dc0580-6b68-11ef-bac3-2d7c12bc3033.jpg
  需要转换为:
   /data/storage/el2/base/{appKey}/files/{receiver id}/{sender id}/f6dc0580-6b68-11ef-bac3-2d7c12bc3033.jpg
  

• 建议此步骤在展示附件时进行判断，并更新对应的localPath。
  
• 如果转换后，文件仍不存在，则需要展示默认图片。
  

三、情况准备及工具要求

HarmonyOS NEXT Developer Beta1或之后版本的终端装备一部。
HarmonyOS 体系终端装备一部。
工具要求：
  工具
  版本
  说明
  “迁移调试”工具
  205.0.0.115及之后版本
  模拟验证数据迁移
  DevEco Studio
  DevEco Studio NEXT Developer Beta2及之后版本
  请参考：DevEco Studio使用指南
  Compatible SDK
  5.0.0(12)
  请参考：版本说明
  留意：
   

• “迁移调试”工具需要向华为申请获取。
  
• HarmonyOS NEXT Developer Beta1及之后版本，厂商互助伙伴可通过IssueReporter平台提交工单，向华为方技能支持人员申请“迁移调试”工具，模拟进行数据迁移验证。公共开发者请通过“华为开发者同盟官网”->“支持”，在线提单方式获取。
  
• HarmonyOS NEXT Developer Beta1之前版本，开发者可以通过体系内置“迁移调试”工具，模拟进行数据迁移验证。
  

  四、BackupExtensionAbility实现及配置

官方文档：BackupExtensionAbility的实现
1. 在entry/src/main/ets/目录下，点击 New > Directory 创建backupExtension目录。

2. 点击entry/src/main/ets/backupExtension/目录，点击 New > File 创建BackupExtension.ets文件。

3. 基于迁移环信SDK实现的BackupExtensionAbility示例代码。

1. import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
2. import { contextConstant } from '@kit.AbilityKit';
3. import fs from '@ohos.file.fs';
4. import { JSON } from '@kit.ArkTS';
6. const TAG = `BackupExtensionAbility`;
8. /**
9. * serviceExt进程入口
10. */
11. export default class BackupExtension extends  BackupExtensionAbility {
12.   onBackup () {
13.     console.log(TAG,`onBackup ok`);
14.   }
16.   /**
17.    * 数据恢复处理接口。接口是同步接口，其内部所有的异步操作请进行同步等待。
18.    *
19.    * @param bundleVersion 版本信息
20.    */
21.   async onRestore (bundleVersion : BundleVersion): Promise<void> {
22.     console.log(TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`);
23.     if (bundleVersion.name.startsWith("0.0.0.0")){
24.       this.context.area = contextConstant.AreaMode.EL2;
26.       // 设置要迁移APK包的包名, 需要替换为需要迁移的APK的，下面为示例
27.       let apkPackageName = "com.xxx.xxx";
29.       let ceSourcePath = this.context.backupDir + `restore/${apkPackageName}/ce/`;
30.       let dataSourcePath = this.context.backupDir + `restore/${apkPackageName}/A/data/`;
31.     
32.       // 其中<USERID>当前固定为100, 参考文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/app-sandbox-directory-V5#应用沙箱路径和真实物理路径的对应关系
33.       const userId = 100;
35.       // 定义要迁移的APK沙箱目录
36.       let targetSDKSourcePath = ceSourcePath + "data/user/" + userId + "/" + apkPackageName + "/";
37.       if (fs.accessSync(targetSDKSourcePath)) {
38.         // 设置要迁移的APK files文件夹下的数据库文件夹
39.         const sdkDbDir = "easemobDB/";
40.         // 设置要迁移的APK files文件夹下的数据库附属文件夹
41.         const sdkDbPwdDir = "easemobDBPW/";
42.         // 设置要迁移的APK files文件夹下的SDK配置文件（4.3.0版本后有em_ap_config.json文件，之前版本的请忽略)
43.         const sdkConfigs = ["em_ap_config.json", "em_config.json", "server.json"];
45.         // 迁移 APK 沙箱目录 files 文件夹下的文件及文件夹到目标文件夹
46.         const fileDestDir = this.context.getApplicationContext().filesDir + "/";
47.         console.log(TAG, "fileDestDir: "+fileDestDir);
48.         console.log(TAG, "start to move db folder");
49.         await this.moveDirToTargetDir(targetSDKSourcePath + "files/" +sdkDbDir, fileDestDir + sdkDbDir);
50.         console.log(TAG, "end to move db folder");
51.         console.log(TAG, "start to move db pw folder");
52.         await this.moveDirToTargetDir(targetSDKSourcePath + "files/" +sdkDbPwdDir, fileDestDir + sdkDbPwdDir);
53.         console.log(TAG, "end to move db pw folder");
54.         sdkConfigs.forEach(async file => {
55.           const filePath = targetSDKSourcePath + "files/" + file;
56.           console.log(TAG, filePath + " to " + (fileDestDir+file));
57.           await this.moveFileToTargetPath(filePath, fileDestDir + file);
58.         })
59.       }
60.       let targetSDKDataSourcePath = dataSourcePath + "data/media/" + userId + "/Android/data/" + apkPackageName + "/";
61.       if (fs.accessSync(targetSDKDataSourcePath)) {
62.         // 设置要迁移 SD 卡下的的AppKey文件夹
63.         const sdkAppKeySourceDir = "easemob#easeim/";
64.         // 迁移 AppKey 文件夹到目标文件夹
65.         console.log(TAG, "start to move appkey folder");
66.         // 获取升级到 HarmonyOS NEXT 后SDK的目标文件夹路径
67.         const sdkDestDir = this.getTargetDestDir() + "/";
68.         console.log(TAG, sdkDestDir);
69.         await this.moveDirToTargetDir(targetSDKDataSourcePath + sdkAppKeySourceDir, sdkDestDir + sdkAppKeySourceDir);
70.         console.log(TAG, "end to move appkey folder");
71.       }
72.       // 在此处实现终端设备从HarmonyOS 4.0升级到HarmonyOS NEXT后，应用数据的转换和迁移
73.       // 涉及异步操作请进行同步等待
74.       console.log(TAG, `HarmonyOS to HarmonyOS NEXT scenario`);
75.     } else {
76.       // 在此处实现从HarmonyOS NEXT设备迁移到HarmonyOS NEXT设备后，应用数据的处理。无特殊要求，可以空实现
77.       // 涉及异步操作请进行同步等待
78.       console.log(TAG, `Other scenario`);
79.     }
80.   }
82.   async moveFileToTargetPath(sourcePath: string, destPath: string) {
83.     try {
84.       // 若mode为0，移动位置存在同名文件时，强制移动覆盖。
85.       await fs.moveFile(sourcePath, destPath);
86.     } catch (e) {
87.       console.log(TAG, "moveFileToTargetPath: " + JSON.stringify(e));
88.     }
89.   }
91.   async moveDirToTargetDir(sourceDir: string, destDir: string) {
92.     if (fs.accessSync(sourceDir)) {
93.       if (!fs.accessSync(destDir)) {
94.         fs.mkdirSync(destDir, true);
95.       }
96.     }
97.     try {
98.       // mode为2，文件级别强制覆盖。目标文件夹下存在与源文件夹名冲突的文件夹，若冲突文件夹下存在同名文件，则强制覆盖冲突文件夹下所有同名文件，未冲突文件将继续保留。
99.       console.log(TAG, sourceDir + " to " + destDir);
100.       await fs.moveDir(sourceDir, destDir, 2);
101.     } catch (e) {
102.       console.log(TAG, "moveDirToTargetDir: " + JSON.stringify(e));
103.     }
104.   }
106.   getTargetDestDir(): string {
107.     const filesDir = this.context.getApplicationContext().filesDir;
108.     console.log(TAG, "getTargetDestDir: "+filesDir);
109.     let lastPosition = filesDir.lastIndexOf('/files');
110.     return lastPosition != -1 ? filesDir.substring(0, lastPosition) : filesDir;
111.   }
112. }

复制代码

4. 元数据资源配置

需要在 backup_config.json 文件中设置迁移场景，其他的元数据配置在本场景下不需要配置，示比方下：

1. {
2.   "allowToBackupRestore": true,
3.   "extraInfo": {
4.     "supportScene": [
5.       "hmos2next"
6.     ]
7.   }
8. }

复制代码

5. 在 module.json5 中注册 BackupExtension

需要在 entry 内的module.json5内里进行注册，示例代码如下：

1. "extensionAbilities": [
2.   {
3.     "description": "DemoBackupExtension",
4.     "icon": "$media:app_icon",
5.     "name": "BackupExtensionAbility",
6.     "srcEntry": "./ets/backupExtension/BackupExtension.ets",  // 对应BackupExtension.ets在代码仓中的位置
7.     "type": "backup",                                         // 类型需要选择backup
8.     "exported": false,
9.     "metadata": [                                             // 对应注册的元数据资源
10.       {
11.         "name": "ohos.extension.backup",
12.         "resource": "$profile:backup_config"
13.       }
14.     ]
15.   }
16. ]

复制代码

五、开发者自验证

官方文档：开发者自验证
应用沙箱数据准备

APK 应用文件路径（从Android Studio的Device Explorer中看）与华为要求的准备的 APK 应用沙箱目录的映射关系：

APK 应用文件路径	APK 应用沙箱目录
data/data/{包名}/	/data/user/{userId}/{APK包名}/
sdcard/Android/data/{包名}/	/data/media/{userId}/Android/data/{APK包名}/

应用沙箱数据准备参考华为官方文档即可，以下是需要留意的事项：
     1. 准备好的应用沙箱文件需要整体放入到压缩包的目录下，比方：
/data/user/{userId}/{APK包名}/  放入到 {APK包名}/ce  后，目录路径为：{APK包名}/ce/data/user/{userId}/{APK包名}/
     2. 准备好的压缩包，可以通过 DevEco Studio -> Device File Browser  找到目的装备，找到手机的 Download 文件夹路径（/storage/media/100/local/files/Docs/Download/ ），右击 Download 文件夹，选择 “Upload …” 选中压缩好的压缩包。 
     3. 或者通过 hdc 命令，通过命令 hdc file send localPath/xxx.zip /storage/media/100/local/files/Docs/Download/xxx.zip 将文件从本地发送到手机。
NEXT 装备上模拟验证应用数据迁移

申请“迁移调试”工具
HarmonyOS NEXT Developer Beta1及之后版本，厂商互助伙伴可通过IssueReporter平台提交工单，向华为方技能支持人员申请“迁移调试”工具，模拟进行数据迁移验证。公共开发者请通过“华为开发者同盟官网”->“支持”，在线提单方式获取。
如果接纳在线提单方式获取，可参考如下申请：
选择 `HarmonyOS NEXT -> HarmonyOS NEXT其他` 路径，申请格式为：
   邮箱：
  应用名称：
  申请原因：
  一般提单后，一天左右即可得到“迁移调试”工具的hap下载链接。
测试`BackupExtensionAbility`逻辑
按照华为官方文档进行调试时，点击启用迁移 按钮后，“迁移调试”工具会调起 NEXT 应用的`BackupExtensionAbility`独立历程，在这里会处理自定义的数据恢复操作。可以通过 DevEco Studio 的Log，选择backup历程（{应用包名}:backup）检察迁移日志，可以检察是否迁移成功。
其他

•  在数据迁移这一步，建议使用 mv  命令，文件的迁移服从要高于 copy  命令。
  
•  HarmonyOS应用关联Android应用。
  

六、端到端验证

在完成自验证步骤后，应用需要上架到华为应用市场，开发者需要模拟终端用户将终端装备从HarmonyOS升级到HarmonyOS NEXT的场景，端到端验证应用数据迁移结果。
具体步骤参考官方文档。
七、总结

颠末“应用分析 -> 应用适配（含适配）-> 应用上架 -> 端到端验证”几个步骤最终完成应用数据的迁移，本文重要先容的是 应用分析 和应用适配（含验证） 部分的先容。希望本文可以帮助到正在和即将进行数据迁移的同学们。如果有需要探讨的地方可以在下方留言。
相关文档：

 1. 华为-装备升级应用数据迁移适配指导；
 2. 华为-HarmonyOS应用关联Android应用；
 3. 华为-应用沙箱路径和真实物理路径的对应关系；
 4. 环信-HarmonyOS IM SDK 更新日志;
 5. 环信-HarmonyOS 快速开始;
 6. 环信-HarmonyOS SDK 下载；

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。