如何在 HarmonyOS Next 中实现自定义 BackupExtensionAbility

本文旨在深入探讨华为鸿蒙HarmonyOS Next系统（截止目前API12）的技术细节，基于实际开发实践进行总结。
主要作为技术分享与交流载体，难免错漏，欢迎各位同仁提出宝贵意见和问题，以便共同进步。
本文为原创内容，任何形式的转载必须注明出处及原作者。

---

BackupExtensionAbility 是 HarmonyOS Next 系统中用于实现应用数据备份恢复的核心组件。通过自定义 BackupExtensionAbility 类并实现 onBackup 和 onRestore 方法，开发者可以定义应用在数据备份和恢复过程中需要执行的操作。本文将详细介绍如何在 HarmonyOS Next 中注册和配置 BackupExtensionAbility，并展示其自定义实现的基本流程。

---

一、BackupExtensionAbility 的注册与配置文件说明

在开发应用的备份和恢复功能之前，需先在配置文件中注册 BackupExtensionAbility，使应用能够正确地接入 HarmonyOS Next 的备份恢复框架。

1. 配置 module.json5 文件

在 module.json5 配置文件中，通过配置 extensionAbilities 字段来注册 BackupExtensionAbility，使系统识别该类为备份恢复组件。具体配置项如下：

• type：设置为 "backup" 表示该扩展组件为备份恢复类型。
• metadata：添加 "ohos.extension.backup" 项目来指定备份相关的资源。
• srcEntry：指定 BackupExtensionAbility 类文件的路径。

{
  "extensionAbilities": [
    {
      "description": "$string:BackupExtensionAbilityDesc",
      "icon": "$media:app_icon",
      "name": "BackupExtensionAbility",
      "type": "backup",
      "exported": false,
      "metadata": [
        {
          "name": "ohos.extension.backup",
          "resource": "$profile:backup_config"
        }
      ],
      "srcEntry": "./ets/backupExtension/BackupExtension.ets"
    }
  ]
}

2. 配置备份资源文件

在 resources/base/profile 文件夹中，添加与 module.json5 中 metadata.resource 字段一致的资源文件。此文件用于定义哪些应用数据和资源需要备份、是否允许恢复等配置。

以下为资源配置文件 backup_config.json 的示例：

{
  "allowToBackupRestore": true,
  "includes": [
    "/data/storage/el2/base/files/"
  ],
  "excludes": [
    "/data/storage/el2/base/files/cache/"
  ],
  "fullBackupOnly": false
}

该文件中的关键字段解释如下：

• allowToBackupRestore：是否允许备份和恢复。
• includes：需要备份的文件或文件夹列表。
• excludes：无需备份的文件或文件夹列表。
• fullBackupOnly：是否进行全量备份。

---

二、自定义 BackupExtensionAbility 类

配置完成后，接下来创建并自定义 BackupExtensionAbility 类，主要通过重写 onBackup 和 onRestore 方法来定义具体的备份和恢复逻辑。

1. onBackup：该方法用于实现数据备份逻辑。可在此方法中指定备份的文件路径、数据格式等。
2. onRestore：该方法用于实现数据恢复逻辑。在设备升级或应用重装后，系统会自动调用此方法，将备份目录中的数据还原到应用的沙箱目录。

以下是一个基础的 BackupExtensionAbility 类实现：

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

const TAG = `BackupExtensionAbility`;

// 自定义 BackupExtensionAbility 类export default class BackupExtension extends BackupExtensionAbility {
    // 数据备份方法
    onBackup() {
        console.log(TAG, `onBackup started, performing data backup...`);
        // 在此处编写数据备份逻辑，如指定备份路径和格式
    }

    // 数据恢复方法
    async onRestore(bundleVersion: BundleVersion): Promise<void> {
        console.log(TAG, `onRestore invoked with bundle version: ${JSON.stringify(bundleVersion)}`);
        if (bundleVersion.name.startsWith("0.0.0.0")) {
            console.log(TAG, `Performing data migration from HarmonyOS to HarmonyOS NEXT`);
            // 数据迁移处理逻辑
        } else {
            console.log(TAG, `Performing data restoration for other versions`);
        }
    }
}

---

三、备份和恢复数据的映射与控制

在 HarmonyOS Next 中，应用的数据通常存放于应用沙箱目录，而备份恢复框架会将这些数据迁移至备份目录。通过配置 includes 和 excludes 字段，开发者可灵活控制哪些数据需要备份，以及备份的数据恢复路径。

1. 数据目录映射

在应用数据备份中，以下几种常见目录的映射关系为：

应用数据目录	备份恢复目录	获取方式
/data/user_de/{userId}/{包名}/	/data/storage/el1/base/.backup/restore/{包名}/de/	contextConstant.AreaMode.EL1
/data/user/{userId}/{包名}/	/data/storage/el2/base/.backup/restore/{包名}/ce/	contextConstant.AreaMode.EL2
/data/media/{userId}/Android/data/{包名}/	/data/storage/el2/base/.backup/restore/{包名}/A/data/	contextConstant.AreaMode.EL2

2. 数据存储与还原路径控制

通过 BackupExtensionAbility 的上下文对象 this.context，可以直接获取备份和恢复目录。开发者在实现 onBackup 和 onRestore 时，可以使用以下代码来读取和还原备份数据：

const deSourcePath = `${this.context.backupDir}restore/{包名}/de/`;
const ceSourcePath = `${this.context.backupDir}restore/{包名}/ce/`;

---

四、示例代码：onBackup 与 onRestore 的实现

以下代码示例展示了如何在 onBackup 和 onRestore 方法中实现数据备份和恢复逻辑。此示例演示了备份指定文件夹的数据，并在数据恢复过程中对不同系统版本执行特定的恢复操作。

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

const TAG = `FileBackupExtensionAbility`;

// BackupExtensionAbility 自定义实现export default class BackupExtension extends BackupExtensionAbility {
    // 数据备份逻辑
    async onBackup(): Promise<void> {
        hilog.info(0x0000, TAG, `onBackup invoked, starting data backup process...`);
        
        // 获取备份目录
        const backupPath = this.context.backupDir + "files/";
        try {
            // 执行备份逻辑
            hilog.info(0x0000, TAG, `Backing up data to path: ${backupPath}`);
            // 假设备份数据至指定目录，开发者可在此实现文件复制、打包等操作
        } catch (error) {
            hilog.error(0x0000, TAG, `Error during backup: ${error.message}`);
        }
    }

    // 数据恢复逻辑
    async onRestore(bundleVersion: BundleVersion): Promise<void> {
        hilog.info(0x0000, TAG, `onRestore invoked for bundle version: ${JSON.stringify(bundleVersion)}`);

        if (bundleVersion.name.startsWith("0.0.0.0")) {
            hilog.info(0x0000, TAG, `HarmonyOS to HarmonyOS NEXT upgrade detected, handling data migration.`);
            // 实现数据迁移逻辑
            const restorePath = `${this.context.backupDir}restore/{包名}/de/`;
            hilog.info(0x0000, TAG, `Restoring data from path: ${restorePath}`);
            // 从恢复目录中加载数据至沙箱目录
        } else {
            hilog.info(0x0000, TAG, `Standard restore for other versions.`);
        }
    }
}

在上述代码中：

• onBackup 方法中定义了备份路径，并将应用数据存储到备份目录中。
• onRestore 方法根据 bundleVersion 执行恢复逻辑，支持从 HarmonyOS 旧版本到 HarmonyOS NEXT 的数据迁移。

---

总结

通过自定义 BackupExtensionAbility 类，HarmonyOS Next 的备份恢复框架可以灵活处理应用数据的备份与恢复。咱们可以根据业务需求设置数据的备份路径、过滤条件，并在数据恢复阶段执行自定义的数据迁移策略。