多方案备份与恢复的技术封面

一款出行清单工具走到第六篇,最危险的时刻可能不是保存,而是恢复。用户把旧手机上的一段备份文本粘贴进来,点了“恢复”,屏幕立刻出现另一份装备列表。表面上事情完成了,实际上可能已经丢掉当前的家庭露营方案,甚至把一段不完整 JSON 写进了唯一的本地存储。恢复功能不能只是 JSON.parse() 后覆盖状态;它必须回答三个问题:文本有没有资格成为数据、用户到底会覆盖什么、落盘失败后原数据是否还在。

此前 PackFlow 从 GearItem 单源勾选出发,加入 packflow_prefs 的 Preferences 持久化、分类筛选与编辑冲突保护、批量装箱与撤销,再发展出多份 PackPlan。第五篇把活动方案集中在 PlanBundle:schema: 2、activePlanId、plans,每份方案拥有自己的 items。这一篇不改变这些基本字段,也不声称实现云同步或系统级文件分享,而是完成可以由开发者逐步验收的文本备份—严格预检—二次确认—串行写入—界面替换流程。它适用于 Stage 模型下的 ArkTS 应用,采用可核实的 ArkUI 与 Preferences 接口,示例以 API 11 及以上工程配置讨论。

一、先定义“备份”的语义,再谈导出按钮

备份不是把某个 UI 列表 JSON.stringify 一次。页面上可能正在显示“周末轻徒步”的待装箱项目,实际上 Preferences 中还保存着“家庭露营”以及其他方案。如果只导出当前可见行,筛选条件一变,得到的备份就会缺项。因此本版导出的单位必须是完整 PlanBundle,而不是 gears、visibleGears 或当前卡片数组。activePlanId 也属于备份的一部分,否则还原后用户会发现自己的默认方案变了。

导出时应该使用通过校验的快照,而不是边遍历页面状态边拼接字符串。业务层在读取时先确认 schema === 2;数据校验通过后,对同一份对象生成 JSON 文本。为便于用户人工传输,示例界面提供“生成备份文本”按钮及可选择复制的文本框,读者可以粘贴到自己管理的安全位置。这里刻意不编写未经查证的文件选择器、剪贴板权限或跨设备 API;文本生成不等于自动落地到系统文件,也不代表经过加密。若内容可能包含个人行程信息,应提醒产品在真实交付时设计访问控制与传输途径,而不是默认公开分享。

PackFlow 中的多方案备份预检与确认界面

快照还有一个常被忽略的时间问题:刚勾选一件装备后,页面状态可能已经更新,上一条写入队列却尚未执行 flush()。如果此时从 Preferences 重新读取并导出,用户可能拿到稍旧的状态;如果直接从页面导出,也可能包含尚未成功保存的数据。产品应当明确选择。本文要求先等待现有串行写入队列完成,再从 PlanStore.read() 获取已经确认的存储内容。按钮在等待期间显示“正在准备备份”,绝不把未确认内容标成“已备份”。对低频的人工备份操作,多等一次存储确认比悄悄丢失最后一笔勾选更合理。

二、恢复预检:不能把 JSON 能解析等同于结构可信

下面新增一个不依赖 ArkUI 页面上下文的纯数据模块 BackupGuard.ets。它只负责验证结构、边界与业务身份,不修改当前清单。此前第五篇已有 PackPlan、PlanBundle、GearItem 和 PlanStore;这里沿用这些模型,不重新设计另一套备份格式。校验特别检查 planId 在包内唯一、每个方案内的装备 id 唯一、activePlanId 必须能找到合法方案,以及用户可控的文本长度。版本不符合时明确拒绝,而不是把未知未来格式强制当成当前结构。

// entry/src/main/ets/common/backup/BackupGuard.ets
import { PlanBundle, PackPlan } from '../model/PackPlan';
import { GearItem } from '../model/GearItem';

export interface BackupPreview {
  data: PlanBundle;
  planCount: number;
  itemCount: number;
  activeTitle: string;
}
export class BackupGuard {
  static inspect(text: string): BackupPreview {
    if (text.length === 0 || text.length > 250000) {
      throw new Error('备份文本为空或超过长度上限');
    }
    const bundle: PlanBundle = JSON.parse(text) as PlanBundle;
    if (!bundle || bundle.schema !== 2 ||
        !Array.isArray(bundle.plans) || bundle.plans.length < 1 ||
        bundle.plans.length > 20 || typeof bundle.activePlanId !== 'string') {
      throw new Error('方案版本或顶层结构错误');
    }
    const planIds: Set<string> = new Set<string>();
    let itemCount: number = 0;
    for (const p of bundle.plans) {
      if (!p || typeof p.planId !== 'string' || !p.planId.trim() ||
          typeof p.title !== 'string' || !p.title.trim() ||
          p.title.length > 40 || planIds.has(p.planId) ||
          !Array.isArray(p.items) || p.items.length > 500) {
        throw new Error('方案标识或数据数量不合法');
      }
      planIds.add(p.planId);
      const ids: Set<number> = new Set<number>();
      for (const g of p.items) {
        if (!g || !Number.isSafeInteger(g.id) || g.id <= 0 || ids.has(g.id) ||
            typeof g.name !== 'string' || !g.name.trim() || g.name.length > 30 ||
            typeof g.category !== 'string' || !g.category.trim() ||
            typeof g.packed !== 'boolean') {
          throw new Error('装备记录不合法或标识重复');
        }
        ids.add(g.id);
      }
      itemCount += p.items.length;
    }
    const active: PackPlan | undefined = bundle.plans.find(
      (p: PackPlan): boolean => p.planId === bundle.activePlanId);
    if (!active) { throw new Error('活动方案不存在'); }
    return { data: bundle, planCount: bundle.plans.length,
      itemCount: itemCount, activeTitle: active.title };
  }
}

这些校验并不意味着 JSON 是“安全文件”。它只能拒绝明显不符合 PackFlow 数据约定的内容;业务数据一旦允许自由文本,还要考虑粘贴来源、隐私与异常长度。这里的 25 万字符、20 个方案、单方案 500 件装备,是本示例主动设定的资源边界,而不是 HarmonyOS Preferences 的通用限制。实际项目应按序列化体积、设备性能和真实使用规模修订。若将来增加 createdAt、标签颜色或附件路径,要通过明确的 schema 迁移函数升级,而不能轻率地去掉验证。

对未知对象进行强制类型断言不会让运行时数据自动变得正确,所以上述循环逐字段检查。特别要禁止“无效就清空再恢复默认”。如果用户把一个损坏备份粘贴进来,界面应该停留在“预检失败”,保留原有两套方案,允许用户修正文本文本;默认数据只是首次安装时的起点,不是出错时随手覆盖存储的理由。

三、确认和落盘是两个事务阶段

预检通过后,界面应该显示清晰的影响范围。例如测试数据里有“周末轻徒步”和“家庭露营”两份方案、合计八件装备,当前默认方案为“家庭露营”。页面先展示“预检通过:2 个方案,8 件装备”,并提供“确认覆盖当前数据”按钮。用户看得见将发生什么,才能有意识地承担覆盖动作。还应明确说明:恢复是整个方案包替换,不是把新方案追加到现有列表;不同备份中的同名方案不会自动合并,避免把简单示例伪装成冲突解决系统。

白色 DevEco Studio 中的恢复校验代码与构造预览

恢复写入必须复用 PlanStore.write() 的单一入口,并确保此前页面的保存队列已排空。关键代码只新增一个控制器方法;pending 保存预检时得到的快照,busy 阻止重复点击,revision 识别预检文本在确认前是否被修改。若编辑了输入框,必须先清除旧的 pending,否则页面可能把用户已改动的文本与上一次预检的合法内容混淆。

// entry/src/main/ets/pages/BackupPage.ets(增量成员)
@State importText: string = '';
@State status: string = '等待粘贴备份';
@State planCount: number = 0;
@State itemCount: number = 0;
@State activeTitle: string = '';
@State busy: boolean = false;
private pending: BackupPreview | null = null;
private inputRevision: number = 0;
private validatedRevision: number = -1;
private store: PlanStore | null = null;

private changeText(text: string): void {
  this.importText = text;
  this.inputRevision++;
  this.pending = null;
  this.status = '文本已变更,请重新预检';
}
private inspectText(): void {
  if (this.busy) { return; }
  try {
    const preview: BackupPreview = BackupGuard.inspect(this.importText);
    this.pending = preview;
    this.validatedRevision = this.inputRevision;
    this.planCount = preview.planCount;
    this.itemCount = preview.itemCount;
    this.activeTitle = preview.activeTitle;
    this.status = '预检通过,请核对覆盖范围';
  } catch (_) {
    this.pending = null;
    this.status = '预检失败,当前数据未变更';
  }
}
private async restoreAll(): Promise<void> {
  if (this.busy || this.pending === null || this.store === null ||
      this.validatedRevision !== this.inputRevision) { return; }
  this.busy = true;
  const snapshot: PlanBundle = this.pending.data;
  try {
    await this.store.write(snapshot); // write 内部调用 put 和 flush
    this.bundle = snapshot; // 当前页面复用第五篇的 bundle 状态
    this.clearUndo();      // 旧方案的撤销栈全部失效
    this.status = '恢复完成,全部方案已保存';
    this.pending = null;
  } catch (_) {
    this.status = '写入失败,当前页面数据保留';
  } finally { this.busy = false; }
}

页面渲染不需要把预检结果复制成另一份独立业务模型,只在预检成功时显示摘要。下面的 @Builder 片段由原有清单页调用,文本、计数与按钮状态直接对应前面的成员。成功按钮在没有合法 pending、保存繁忙或文本已经修改时保持不可用;这些条件应由界面和控制器同时检查。

// Index.ets 中组合 BackupPage 增量状态后的 UI 片段
@Builder
private restorePanel() {
  Column({ space: 16 }) {
    Text('备份与恢复').fontSize(24).fontWeight(FontWeight.Bold)
    Text('恢复前先检查,确认后才覆盖').fontSize(17)
    TextArea({ text: this.importText,
      placeholder: '粘贴备份 JSON' })
      .height(150)
      .onChange((value: string) => this.changeText(value))
    Button('预检备份').enabled(!this.busy)
      .onClick(() => this.inspectText())
    Text(this.status)
    Text(`覆盖范围:${this.planCount} 个方案 / ${this.itemCount} 件装备`)
    Text(`恢复后活动方案:${this.activeTitle}`)
    Button('确认覆盖当前数据')
      .enabled(!this.busy && this.pending !== null &&
        this.validatedRevision === this.inputRevision)
      .onClick(() => { this.restoreAll(); })
    Button('返回修改').onClick(() => { this.pending = null; })
  }.width('100%').padding(20)
}

这段是基于第五篇页面成员的增量实现,不是另起一份不相容的应用:bundle、clearUndo()、PlanStore 已在原页面中使用。接入时将 changeText 绑定 TextArea 的 onChange,把 inspectText 与 restoreAll 接到两个按钮,并在进入页面时由 getContext(this) 创建 PlanStore。注意 PlanStore.write() 自己必须负责持久化完成与异常抛出,不能只调用 put() 就向页面承诺落盘成功。

如果第六篇单独打开为新的页面,业务层仍要解决一个跨页面写入的问题:恢复发生时,主清单页面可能还有未结束的旧保存任务。这时仅靠 busy 无法阻止旧任务在恢复之后把旧清单再次写回。工程实现应把恢复和普通保存都提交给同一个应用级串行队列,或者在恢复时先排空旧队列、阻止新编辑、完成写入后再解除锁。锁的范围必须跨页面,而不是只覆盖恢复按钮。本文保留已有的串行存储入口,并把“跨页面保存竞争”列为收官验收的必要条件。

四、验收恢复失败,比验收成功更重要

测试先从一组可核对的数据开始:周末轻徒步与家庭露营,前者四件装备中两件已装箱,后者四件装备中一件已装箱。生成备份后,把原数据中的家庭露营头灯勾选,再使用旧备份预检。界面应准确显示“2 个方案、8 件装备”,确认覆盖后应恢复备份时的状态;取消则不能改变当前勾选。这样能区分“导出了所有方案”和“只是输出当前页面”的差异,也能验证 activePlanId 是否跟随备份恢复。

其次输入三种无效备份:顶层 schema 改成 3、两份方案使用相同的 planId、某个装备 packed 被写成字符串。它们都必须停在预检阶段,不得进入 PlanStore.write()。再测试一次“预检完成后修改文本”,确认按钮必须因为修订号变化而无效;随后重新预检才允许恢复。这覆盖了实际用户粘贴、编辑、反复尝试时最常见的交互时序漏洞。

最后让存储服务在测试替身中抛错,检查 busy 能释放、页面状态仍保留、错误提示出现,并且不会调用清空操作。再从另一个页面构造一个迟到的保存任务,验证恢复串行队列是否能阻止旧数据反写。恢复后立刻退出并重新启动应用,才可以检查是否真的读回完整方案。没有真机或 DevEco 实测记录时,以上是可复现的预期流程,不能写成通过率或毫秒数。

备份预检、确认、串行写入与失败回退的工程流程

六篇连载最终留下的不是又一套无边界的状态变量,而是三条稳定规则:GearItem 的身份在一个方案内部稳定;PlanBundle 是所有方案一次性保存和恢复的基本单位;页面中的筛选、撤销、编辑与恢复不允许绕开同一个持久化入口。当前示例为单设备轻量本地工具,没有自动跨设备同步、账户鉴权或真正的文件导入导出功能。如果未来扩展到协作清单,需要服务端版本号、冲突策略、权限与加密等新的工程设计,而不能在这个文本恢复按钮旁边添加一枚“同步”图标便宣称完成。

官方参考:Preferences 接口;Preferences 数据持久化指导;TextArea 组件。开发时须根据所安装的 SDK 逐一核对签名与工程模块路径,尤其是异步写入失败后的恢复策略。把覆盖范围说清楚、把无效输入拒在写入之前、把真正的落盘与页面成功提示绑定起来,PackFlow 才算完成从便利小工具到可维护离线应用的工程闭环。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐