家庭菜单在离线修改后出现“同步成功”提示,但另一台设备仍是旧内容。状态可能是本地保存成功、待上传、服务端确认、冲突待处理,单一成功标识无法表达一致性进度。有时团队会争论先修改还是先采集,真正需要统一的是能否验证改动的依据。这次把问题收敛到“离线同步失败的用户体验诊断”这一具体环节,不用全局重构来掩盖局部诊断能力不足。

本篇 DFX 专题封面

以“家庭菜单”工程为例,入口页面或服务落在 entry/src/main/ets/pages/SyncResult.ets,工程名为 MealShelf。用户看到的是菜单同步状态页,开发侧却至少要同时理解输入、异步任务、UI 状态与系统资源四个维度。DFX 不只服务工程师,也要让用户知道数据在哪个阶段;诊断事件和 UI 状态共享一组可解释的状态。如果只保留一条“失败了”的信息,后续定位无法回答事情是在请求之前、处理中还是状态写回之后发生。

这里不准备把 DFX 扩展成一套冗长报表,目标是让排查尽可能少依赖主观猜测。会把“本地版本号、待同步条目、冲突类别、最终确认状态”作为观察字段,再用可重复的动作确认设计是否有效。排查工具不必同时打开:先用日志与事件确定问题窗口,再决定是否需要 Trace、FaultLog 或 Profiler 深入取证。

一、先分清现象与原因

定位之前可以把信息分为两组:一类是用户可以察觉的表现——家庭菜单在离线修改后出现“同步成功”提示,但另一台设备仍是旧内容;另一类是系统或代码真正触发异常的条件。二者之间还缺少可检验的中间环节。状态可能是本地保存成功、待上传、服务端确认、冲突待处理,单一成功标识无法表达一致性进度。排查顺序不妨按发起、处理、可见结果、退出清理展开;每段保留清晰的身份标记,有助于发现重复调用、丢失终态或前后状态互相覆盖。

讨论往往从网络耗时、资源压力切入;如果缺少起止条件,假设无法形成有效试验。因此建立字段表::本地版本号、待同步条目、冲突类别、最终确认状态,明确哪些是实际记录、哪些只是待验证条件。只有按操作标识过滤过的时间线,才适合用于比较请求与 UI 的先后关系。现场材料还要注明构建版本和设备条件,免得把两个不同缺陷合并。

设计边界需要单独说明:跨设备同步还涉及账户授权和数据边界,不能只根据本机写入事件得出多设备一致结论。讨论的是可定位性,而不是未经采集的性能排名。当工具暂时不可用,排查报告应区分观察事实与后续需要证实的猜测。这样既不会让团队陷入无限等待,也不会因为一个不可靠的假设反复改坏原本正常的业务逻辑。

还可以从调用归属反推设计是否清晰:在 MealShelf 中,将修改路径拆成 localSaved、queued、syncing、confirmed、conflicted,并为每个转换写结果事件。如果同一动作出现第二个入口,应先核实是用户主动重试、页面重建还是内部超时导致的补偿;三种来源对应不同的状态终结方式。本地版本号、待同步条目、冲突类别、最终确认状态不仅要记录出来,还要能够被界面状态或代码调用链解释,不能只因为字段齐全就视为方案闭合。

二、技术证据的分层方式

记录逻辑最好从业务职责的边界开始接入。将修改路径拆成 localSaved、queued、syncing、confirmed、conflicted,并为每个转换写结果事件。集中管理操作身份与状态转换,能够减少各组件自行解释结果的歧义;同时减少诊断实现对具体页面结构的依赖。遇到组件退出或异步操作被中断,一份统一的入口规则可以避免结果事件与用户实际看到的状态不一致。

核心实现位于 SyncResult.ets,重点记录业务状态和诊断结果。记录面向分析所需的最小事实,原始用户数据不作为默认采集项。实践以官方 ArkTS 文档中的能力边界为基础;兼容性取决于工程的 SDK 配置和设备系统能力。自定义行为数据与系统故障字段的权威性并不相同。

家庭菜单 · 菜单同步状态页界面

在 MealShelf 项目里,发起任务的业务代码界定操作的开始与结束,诊断模块如实记录阶段变化。DFX 不只服务工程师,也要让用户知道数据在哪个阶段;诊断事件和 UI 状态共享一组可解释的状态。重试与取消都应明确分类;未能成功的路径仍要留下终结结果。并发任务需要独立身份,避免迟到回调改写已经完成的操作。

三、最小可用的工程实现

理解实现时应由入口走到异常、取消与成功三个出口。本地版本号、待同步条目、冲突类别、最终确认状态。这些字段应该与代码阶段保持同一套定义。诊断层也有性能边界,频繁构建 UI 的路径不适合执行耗时 I/O。不要让业务页面承担长期统计与文件解析任务。

MealShelf 的核心代码

import { hiAppEvent } from '@kit.PerformanceAnalysisKit';
type SyncState = 'localSaved' | 'queued' | 'syncing' | 'confirmed' | 'conflicted';
export class MealSync {
  private state: SyncState = 'localSaved';
  async transition(next: SyncState): Promise<void> {
    const before: SyncState = this.state;
    this.state = next;
    await hiAppEvent.write('menu_sync_transition',
      hiAppEvent.EventType.STATISTIC,
      { from_state: before, to_state: next, schema_version: 1 });
  }
  current(): SyncState { return this.state; }
}
// 事件写入成功与跨设备数据达成一致是两个不同条件。

HiAppEvent 可以写入行为、统计、故障和安全事件,但事件意义要靠业务字段定义。围绕“离线同步失败的用户体验诊断”,建议先约定 domain、name、eventType 和 params,再明确哪些状态可以写终结事件。不要把成功回调和业务确认混为一谈:写入 Promise 完成只是事件记录完成,不是用户动作已经完成。

排查进入复验阶段时,先准备可重复操作。离线编辑、弱网恢复、两台设备同时修改、撤销操作,观察状态机能否恢复且不遗漏终结事件。对照实验坚持一次只变化一个变量:例如网络状态、图片数量、页面是否重新进入或资源是否仍被持有;并记录最终结果是否正确闭合。应按单一变量对照修复效果,而不是同时动多个可能关联的组件。

四、验证路径如何设计

负向用例与成功用例共同决定修复是否可靠。正常流程提供比较基线,有助于发现异常路径额外的重复工作与资源未回收。将修改路径拆成 localSaved、queued、syncing、confirmed、conflicted,并为每个转换写结果事件。可复现步骤必须写明触发顺序与取消条件,复杂问题最好附上设备条件、预期界面和对应证据,而不只保留截图。

离线同步失败的用户体验诊断 · 证据关联技术图解

最终判断不能只依靠某一帧截图或孤立的一条日志。比较结果前应验证两个事件是否属于同一次操作。状态转换遗漏与冲突可见率用于版本比较之前,需要明确分子对应哪类结果、分母包含哪些用户操作、是否排除重试、是否区分版本。口径变了,版本之间的数字就不能直接比较。

对照回归不要只检查最终按钮能否点击。离线编辑、弱网恢复、两台设备同时修改、撤销操作,观察状态机能否恢复且不遗漏终结事件。假如结果与预期不一致,应倒序核对最后一个成功步骤、失败前的资源状态以及是否有旧任务写回;再用相同路径验证修复是否覆盖了所有出口。尤其在菜单同步状态页这样的多状态页面,空白和错误提示也要有各自的进入条件。

反过来看,下面这些做法会妨碍排查:以网络请求返回成功代替合并完成、冲突时偷偷覆盖本地数据、重复点击产生多个终结态。它们可能把外在表现当成因果证据,也可能忽略错误出口的资源清理。修正应先落实操作职责,而不是增加流水文本:谁创建、谁更新、谁释放,以及哪一条证据能够支持这个判断。这些职责要能通过独立用例得到验证。

五、回收复杂度和额外成本

事件治理要考虑 schemaVersion 的迁移:同一名称的字段从字符串变成数字、或从一次操作改为每次重试时,聚合口径就会漂移。对菜单同步状态页,可以同时保留旧字段的过渡期映射,并在验证时检查是否存在重复写入、缺失结果与时间桶越界。

工具层的数据采集同样会消耗资源,应避免无条件地持续运行。跨设备同步还涉及账户授权和数据边界,不能只根据本机写入事件得出多设备一致结论。高频记录需要通过级别、场景和采样率约束规模;隐私字段不应直接出现在可共享的诊断材料中。采集策略应在问题定位效率与运行开销之间保留明确的选择。

如果缺陷没有消失,优先比较前后运行条件和观测覆盖是否一致。遗漏故障触发环境的回归不具备完整证明力。离线编辑、弱网恢复、两台设备同时修改、撤销操作,观察状态机能否恢复且不遗漏终结事件。版本对比还要带上构建配置、SDK 与设备条件。

六、结论与下一步

收尾时建议保留一份明确的处理规范:为操作建立唯一身份、记录重要状态、处理异常出口并按原用例回归。状态转换遗漏与冲突可见率不要为了可视化而可视化,优先使指标与代码路径建立可靠关联。

此类可观测设计同样适合购物清单与文档协作。作为一次项目实践,离线同步失败的用户体验诊断观察设计应让每条关键信息都有明确的工程用途。后续应持续复核字段契约与资源回收规则,而不是依赖一次性的专项排查。

参考文档

Logo

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

更多推荐