随手备忘录手记 02|HarmonyOS 7.0新特性实验:读盘失败如何快速启动

0 阅读11分钟

02cover.png

1. 前言

站在玄关打开“随手备忘录”,用户想知道钥匙、工牌和雨伞是否已经勾选。上一篇把必要读取放进首个Ability创建前的异步准备:取得当前模板,读出对应清单,发布完整模型,再让后续生命周期继续。

这条路径隐含了一个条件:读取最终能够成功。

如果文件损坏,或者读取一直没有返回,等待就不再帮助用户。页面进不去,重试按钮也无从出现。我们需要给准备过程补上一条失败出口。

“随手备忘录”仍是一个entry模块、一个主UIAbility的手机Stage应用。通勤与运动是两个本地模板,物品图鉴按需打开。本篇继续使用通勤清单:钥匙已勾选,工牌和雨伞未勾选。勾选表达最近一次成功保存的状态,不代表应用识别了包里的实物,也没有每日重置规则。

为了讨论失败,我们向读取边界分别注入损坏记录、Promise拒绝和持续未返回。这些输入对应三种不同问题,不能都转换成空数组。读不到清单,并不能推出用户没有要带的物品。

02D.png

本文关心的“快”,是故障发生后尽早给用户一个明确的恢复入口。恢复页出现与真实清单可用,需要分开判断。

2. 方案

最直接的实现是让错误继续向上传播:

async onAboutToCreateAbilityAsync(): Promise<void> {
  await startup.prepare();
}

这段代码本身没有问题,问题在于 prepare() 的契约。如果它可能拒绝,或者永远不结束,生命周期入口就没有可靠的成功出口。

AbilityStage接口规定,异步准备返回的Promise成功resolve后,后续生命周期才继续,否则将被挂起。不能指望系统替应用把异常转换成恢复页。

另一种选择,是让准备服务承担结果分类:能取得清单,就发布清单;不能取得,就发布原因明确的恢复状态,然后正常结束本轮准备。入口仍然保留上面的形式,变化发生在服务内部。

我倾向于先确定页面需要知道什么,再决定如何捕获异常。

读取结果准备结果页面行为
合法非空清单可用展示保存的物品与勾选状态
合法空清单可用显示正常空态
确认没有保存记录待恢复:首次使用进入模板选择或使用引导
解析失败、字段错误、模板不匹配待恢复:数据异常保留记录,说明问题并提供重试
读取拒绝暂不可用:读取失败提示暂时读不到清单
等待预算耗尽暂不可用:等待超时结束加载提示,提供重试

三个结果类别都是应用自己的语言。首次使用放在“待恢复”中,表示需要引导才能继续,不表示存储损坏。

这里最重要的区别是证据:只有成功读到合法空数据,才能显示正常空清单。权限错误、解析失败都不能被适配器悄悄转换成“没有保存记录”。空清单也不应显示“全部带齐”,因为空集合不足以支持这句生活判断。

02A.png

等待还需要一个预算。它覆盖读取模板标识、读取清单及必要校验的整个过程,而不是只包住最后一次IO。预算由应用配置,并根据目标设备上的读取分布和恢复体验调整,不是系统规定的固定秒数。

两种方案的对照应保留同一读取器、数据源和页面逻辑,只改变失败策略。恢复流程默认保留原文件;进入恢复页或点击重试,都不能顺手用默认模板覆盖已有记录。

3. 实现

onAboutToCreateAbilityAsync(): Promise<void>从26.0.0开始提供。应用快启基础机制及同步准备回调始于API24。我们继续使用异步入口,不引入Beta接口,也不把同步、异步双实现当作回退方案:同时实现时,只有异步版本生效。

上一篇的业务模型保持不变。物品仍有 id、label、checked,SavedChecklist保存模板标识和物品,ReadyModel供页面消费。

需要调整的是数据交接。原来的 StartupState只保存成功模型;现在它还必须表达为何没有模型。下面用TypeScript形式展示应用内部的核心类型和控制逻辑,存储读取仍由原有适配器承担。

enum ResultKind {
  Ready,
  Recovery,
  Unavailable
}

enum Reason {
  None,
  FirstUse,
  InvalidData,
  ReadFailed,
  Timeout
}

class PreparationResult {
  constructor(
    readonly kind: ResultKind,
    readonly reason: Reason,
    readonly model?: ReadyModel
  ) {}
}

只有 Ready 携带模型。准备中的加载提示属于交互状态,不是第四种最终结果;它更不能借用空清单表达。

然后把读取和发布分开。读取函数只产生候选结果,不再直接修改共享状态。

async function readCandidate(
  reader: ChecklistReader
): Promise<PreparationResult> {
  const templateId = await reader.readCurrentTemplateId();
  const saved = await reader.readChecklist(templateId);

  if (saved === undefined) {
    return new PreparationResult(
      ResultKind.Recovery, Reason.FirstUse
    );
  }
  if (saved.templateId !== templateId) {
    return new PreparationResult(
      ResultKind.Recovery, Reason.InvalidData
    );
  }
  return new PreparationResult(
    ResultKind.Ready, Reason.None,
    { templateId, items: saved.items }
  );
}

适配器负责解析及字段校验,并把相应失败归为应用定义的 InvalidRecordError;其他读取拒绝归为读取失败。undefined只表示明确没有保存记录。首次安装时模板标识的默认选择,也必须由适配器契约规定,不能把所有模板读取异常都解释成首次使用。

02E.png

这个拆分使我们能够在一个位置控制提交。它比单纯给读取外面套一个 Promise.race 更关键。

设想第一次读取超时,恢复页出现。用户点击重试,第二次读取成功,然后把工牌勾上并保存。此时第一次读取才返回。如果旧读取仍能直接发布,它就可能把页面改回工牌未勾选的状态。

因此,每次准备需要一个尝试标识,每轮还需要一个“已经结案”的标记。前者区分新旧操作,后者阻止同一轮反复提交。

下面的协调逻辑采用计时器与读取回调竞争同一个完成入口。state.publish()约定为同步更新应用状态,页面通过既有绑定消费结果;提交检查与状态更新之间不插入异步操作。

class StartupService {
  private generation: number = 0;

  constructor(
    private reader: ChecklistReader,
    private state: StartupState,
    private budgetMs: number
  ) {}

  prepare(): Promise<void> {
    const attempt = ++this.generation;
    return new Promise<void>((resolve) => {
      let closed = false;
      let timer: number | undefined = undefined;

      const finish = (result: PreparationResult): void => {
        if (closed) {
          console.info(`prepare.late attempt=${attempt}`);
          return;
        }
        closed = true;
        if (timer !== undefined) {
          clearTimeout(timer);
        }

        if (attempt === this.generation) {
          this.state.publish(attempt, result);
        } else {
          console.info(`prepare.stale attempt=${attempt}`);
        }
        resolve();
      };

      timer = setTimeout(() => {
        finish(new PreparationResult(
          ResultKind.Unavailable, Reason.Timeout
        ));
      }, this.budgetMs);

      readCandidate(this.reader).then(
        (result: PreparationResult) => finish(result),
        (error: Error) => {
          console.error(
            `prepare.failed attempt=${attempt}: ${error.message}`
          );
          const invalid = error instanceof InvalidRecordError;
          finish(new PreparationResult(
            invalid ? ResultKind.Recovery : ResultKind.Unavailable,
            invalid ? Reason.InvalidData : Reason.ReadFailed
          ));
        }
      );
    });
  }
}

StartupService、StartupState与InvalidRecordError都是应用代码中的职责划分,不是SDK提供的恢复机制。构造服务时应校验预算为有限正数;状态发布路径保持简单,不在其中执行IO或调用可能抛错的外部订阅者。

有两个细节值得单独看。

第一,超时之后,即使用户没有重试,旧读取也不能重新提交。此时尝试标识仍然相同,只有 closed 能挡住它。第二,旧轮结束时只能清理自己的计时器,不能修改新一轮的加载提示。局部保存计时器和结案标记,让这种归属关系直接体现在代码里。

所有结果在同一执行上下文串行提交。若底层读取放在线程任务中,应先把结果送回状态所属上下文,不能让多个线程直接执行这段检查与发布。

02B.png

计时器触发后,底层IO仍可能继续。代码中的拒绝处理也仍然存在,因此迟到失败会被记录,而不会成为无人接收的拒绝。我们结束的是等待,并未获得取消底层工作的能力。

预算还有一个物理限制:计时器依赖事件循环调度。同步阻塞的IO或长时间解析会拖延它,Promise包装不能让这些工作自动变成可中断任务。因此预算表示应用策略,不能承诺页面在某个精确毫秒数出现。

准备结果发布后,生命周期回调正常完成,主UIAbility消费结果。恢复页中的重试再次调用同一个服务,通过状态绑定更新当前页面,无须手动调用生命周期方法或再创建一个Ability。重试期间禁用按钮,结束后再开放;没有可信模型时,不触发清单保存。

这里也不需要引入AppStartup。timeoutMs是它的启动任务配置,不能借来充当异步生命周期的系统超时。

4. 检验

一个恢复设计是否成立,主要看事件以不利顺序发生时,它还能否保持数据含义。

先备份通勤记录,每轮恢复“钥匙已勾选、工牌和雨伞未勾选”。在 ChecklistReader 边界注入故障,分别覆盖模板标识读取和清单读取。损坏文件只修改实验副本,结束后移除注入配置。

正常读取、正常空清单和首次无数据是三条独立基线。之后再覆盖预算内慢读、读取拒绝、记录损坏与持续pending。检查的目标不仅是页面出现,还包括原文件未被修改、错误没有伪装成空清单。

迟到场景需要控制完成顺序。可以使用一个由测试代码主动释放的Promise,而不是依赖偶然的磁盘抖动:

let releaseOld:
  ((value: SavedChecklist | undefined) => void) | undefined;

const oldRead = new Promise<SavedChecklist | undefined>(
  (resolve) => { releaseOld = resolve; }
);

// 注入读取器:首次 readChecklist 返回 oldRead;
// 重试读取返回基准记录,恢复成功后再释放首次读取。

最有价值的回归脚本是:等待首次超时,进入恢复页,重试成功,勾选工牌并保存,最后释放首次读取。验收时同时检查屏幕、内存模型和存储记录,工牌都不能被旧读取改回。

02C.png

还应保留几个容易漏掉的排列:

操作顺序需要保持的约束
超时,未重试,旧读取成功本轮只能提交一次,恢复页不被改写
超时,重试成功,旧读取拒绝新状态保持,迟到错误得到记录
重试再次失败或超时继续提供恢复入口,不清空存储
读取完成接近预算到期只接受一个结果
连续点击重试禁用期间不重复发起准备

直接抛错的对照构建应隔离运行,并设置观察窗口,结束时主动停止。它用于核对生命周期行为,不应留在日常入口中。人工延迟同样只验证顺序,不能拿来证明启动提速。

日志至少记录实验ID、尝试标识、读取步骤、预算、结果发布或丢弃原因,以及 UIAbility.onCreate、页面绑定和保存事件。恢复入口是否可见、是否能点击,则需要同轮录屏支持。绑定完成不等于上屏,恢复页可见也不等于清单可用。

记录表应保留预期、实际与证据位置。设备、SDK、OS构建、签名及启动条件保持一致;普通启动和有证据确认的快启分开归类,开关设置成功不能证明命中。日志与视频时间未经对齐,不直接相减。

5. 结尾

异步准备需要一个比“读取成功”更完整的完成条件:准备层已经给出了可供页面消费的明确结果。这个结果可能是清单,也可能是首次使用引导或恢复入口。

读取器负责产生候选数据,协调层负责决定谁可以提交,页面负责解释结果。职责分开后,等待预算、错误分类和重试便能围绕同一契约工作。失败决策表、有界等待逻辑和迟到回归脚本,也就成为这份契约的三个检查面。

仍有一个问题留在边界之外:合法数据未必是最新数据。本篇的尝试标识只能防止旧操作覆盖新操作,不能证明读取内容来自最近一次成功保存,更不是系统快照ID。

下一篇继续沿用这份清单,追踪持久化记录、内存模型与初始化复用结果之间的关系:页面能够打开之后,还要确认它展示的是哪一份数据。