训时工坊-03:HarmonyOS Preferences 训练记录分层存储【共创稿事节】
在 PulseCraft 的开发过程中,训练历史与分组存储看似只是一个界面需求,真正困难的却是事件到来时怎样决定可以写入哪些数据。训练历史和正在运行的计时状态写入同一个键,重启时把已完成记录又当作进行中任务。它提醒我们:用户看到的结果、应用确认的操作和持久化存下的事实,必须能够逐层对账。
本文把实现范围收束为一个可以逐条验证的闭环:输入和触发动作有名字,状态转换有明确前置条件,副作用只能在校验之后执行。我们使用的核心技术包括 Preferences / @kit.ArkData,但不会因此假定所有系统版本或设备形态行为相同。下文围绕 训练历史与分组存储 给出领域模型、关键代码和回归路径;涉及系统能力时以相应官方文档为准。
先给出本章应维持的关键不变量:已完成记录不可被暂停状态覆盖;运行中草稿与最终记录各用独立存储键。它不是一句抽象口号,而是一条可以通过数据断言检验的工程要求。像“本周 4 次”“核心训练 18 分钟”这样的界面信息只负责呈现,不能替代应用内部的确定性标识和已确认操作。

一、从现象锁定工程边界
把变化拆成两类
FinishedSession 的 sessionId、planId、finishedAt、elapsedSeconds 和 stageSummary,是这次设计需要的最小信息集合。这里的字段应依据是否改变业务事实来分类:用户主动编辑后才能改变的属性属于源数据;可以由其他字段重新计算得到的值,属于派生数据。将两类信息混放,会使恢复逻辑无法区分“应该重放”与“应该重新计算”。
以 PulseCraft 为例,页面可以同时展示“本周 4 次”与“伸展 12 分钟”,但二者可能来自不同阶段的数据。若把这些文本视为最终保存格式,日后修改展示文案就会影响历史解析。更稳妥的方法是由领域层负责字段校验,再由页面的格式化函数决定中文标签、图标、按钮状态与辅助说明。
设计评审时应把 sessionId、finishedAt 和 elapsedSeconds 的含义写在同一处。字段名相似不代表生命周期相同;例如一次选择、一次成功写入、一个实际可继续使用的资源引用,属于三种不同事件。只有边界清楚,测试才有办法发现数据串位和旧事件覆盖。
已完成记录不可被暂停状态覆盖;运行中草稿与最终记录各用独立存储键。因此组件不应偷偷直接修改共享数组中的对象,也不该将展示位置或临时索引当作业务身份。如果未来需要增加排序、筛选、分屏显示,领域函数保持输入输出规则不变,界面只改变如何呈现结果。这个分层决定比先画完整页面更重要。
二、数据模型与最小可执行核心
让核心转换脱离 UI 回调
具体算法是:领域层先生成不可变完成对象,再序列化到有命名空间的 Preferences 项。我们优先把这一段做成独立函数,便于喂入正常输入和非法样本;与平台相关的资源获取、页面通知和持久化操作放在调用者一侧。这样做不是追求所有代码都写成纯函数,而是避免把业务判断埋在不可重复触发的界面事件里。
从调用顺序看,可以按“检查输入→形成下一状态→执行必要副作用→向界面确认”四步推进。用户触发“查看详情”后,如果必要条件尚未满足,应让当前状态保持不变并给出反馈;如果仅完成了请求发送,也不应提前把按钮标成已经成功。这个顺序尤其适合处理重复点击和慢回调。
下面的代码围绕 sessionId 建立最小可复用处理单元。所用类型和函数与页面中的标识一致;读者可以把它放到 entry/src/main/ets/common 下的独立 ArkTS 文件,再由 SessionHistory.ets 调用。只有访问系统能力的部分需要替换为真正的组件上下文或运行环境适配器。
import { preferences } from '@kit.ArkData';
interface FinishedSession {
sessionId: string; planId: string; finishedAt: number; elapsedSeconds: number;
}
async function saveFinished(context: Context, items: FinishedSession[]): Promise<void> {
const store = await preferences.getPreferences(context, 'training_history');
const encoded: string = JSON.stringify(items);
await store.put('sessions_v1', encoded);
await store.flush();
}
async function readFinished(context: Context): Promise<FinishedSession[]> {
const store = await preferences.getPreferences(context, 'training_history');
const raw = await store.get('sessions_v1', '[]');
try { return JSON.parse(String(raw)) as FinishedSession[]; }
catch (_) { return []; }
}
代码的价值在于让前置条件可见。例如“JSON 解析失败、重名记录、写入中断和历史版本字段缺失应独立处理”,就不应该靠 catch 后直接返回空白界面掩盖。需要返回明确的失败原因时,可用区分业务错误与平台错误的结果类型,让调用者选择重试、保留草稿或者回退。界面要做的是忠实显示这个结果,而非另建一套判断。

三、交互事件与状态一致性
按实际交互顺序检查状态
把操作拆成三段:首先进入“训练记录”并观察初始对象,其次触发“查看详情”,最后再进入“按周筛选”或返回原页面。每一步都应记录输入是什么、应有的状态是什么、是否需要等待平台侧确认。把动作写成一条链,可以准确找到重复、撤回与回调晚到会影响哪一个节点。
拿“本周 4 次”和“核心训练 18 分钟”做对照。如果用户在前一个操作尚未完成时发起后一个操作,界面不能一律采用最后到达的结果;它必须核对结果是否仍属于当前业务对象。对于 训练历史与分组存储,可通过操作代号、稳定 id、状态版本或有效期来解决,具体机制应由数据模型而不是视觉效果决定。
这一流程还需要明确一个不常见但代价很高的反例:训练历史和正在运行的计时状态写入同一个键,重启时把已完成记录又当作进行中任务。反例比默认情况下按钮正常更有意义,因为它会暴露多个组件同时维护事实的风险。遇到此类错误时,不要直接清空整个应用;先找出已确认的记录,撤销尚未提交的局部更改,再让用户从可恢复状态继续。
对于需要展示状态的组件,建议只保留一个可追溯的状态源。诸如“伸展 12 分钟”一类标签应根据该状态源派生。尤其在页面重新进入时,不应把之前渲染的静态文本当作新的初始化依据;否则页面即使看上去没变,也可能已经脱离真正的数据。
四、异常恢复与适用条件
失败路径不能藏在日志后面
本章至少要覆盖这些反向输入:JSON 解析失败、重名记录、写入中断和历史版本字段缺失应独立处理。这些条件并不属于同一种故障:有的来自用户输入,有的属于设备和权限环境,有的来自操作时序。把它们统一显示为“网络错误”或“未知失败”,虽然能减少分支,却让下一步恢复无从选择。
错误处理应对用户给出可执行动作,而不是技术术语的堆叠。针对 训练历史与分组存储,可以选择保留当前数据、重新选择对象、重试可重复的步骤、或者回到上一有效页面。必须先判断重试是否会重复写入;如果业务操作不是幂等的,重复按钮点击就可能把一次操作变成两次不可撤销的事实。
实现时也要分清静态代码、平台 SDK 和设备行为。本文围绕 Preferences / @kit.ArkData 的公开使用边界讨论,涉及系统权限、持久化、后台能力的部分必须配合对应应用模块配置。对新版本 API,不能仅凭方法名称相同就认为所有设备均支持;官方的起始版本、模型限制和权限约束比论坛代码片段更可靠。
少量本地记录可由 Preferences 承载;大规模查询、复杂过滤和事务一致性应改用 RDB。把这条限制写进需求验收,并不会削弱文章的实用性,反而能够避免错误地把某个界面效果推导成所有设备上已经完成的运行结果。需要性能比较时,先设好采样环境、样本大小和统计口径,再使用真实工具观察,不能用任意生成的数字证明优化收益。

五、工程回归与进一步演进
用可重放样本验收
本章的主回归步骤是:完成两次同名训练后关闭重开,确认两条 sessionId 不会互相覆盖。建议建立一个最小数据集,包含正常条目、重复身份、无效日期或资源、过期事件以及缺失字段;每一步分别记录起始状态、输入事件、预期变化与恢复入口。这样的样本比“在手机上点几下大致正常”更能支持后续升级。
可以把验证分成纯逻辑检查和设备环境检查两层。纯函数部分用已知输入比较精确输出;ArkUI 交互、存储读写、权限回调、窗口变化则需要在 DevEco Studio 和目标 HarmonyOS 设备上执行。没有取得运行证据时,只给出复现步骤、状态断言与应当出现的界面,不用预测耗时或帧率代替测试结果。
我们还需要做一次逆向演练:假设 sessionId 仍旧指向旧对象,而用户已经触发“按周筛选”,旧回调是否可能覆盖当前选择?如果答案依赖“通常不会这么快点击”,代码就还不具备足够明确的状态边界。可靠设计应不依赖人的点击速度,而是明确判断一条结果属于谁。
这篇实践的有效性,最终要靠三个证据:源数据可以解释页面,异常输入不会篡改已确认事实,用户能够从失败处继续。已完成记录不可被暂停状态覆盖;运行中草稿与最终记录各用独立存储键。当后续增加更多页面或设备形态时,优先保持这条协议,再决定动画、缓存或额外提示的实现方式。另一个值得写入代码审查的细节是“伸展 12 分钟”的展示时机。它可能只代表用户最近一次动作,而不是底层已经完成的事务。实践中应当分别给开始、进行、完成、失败这些阶段指定名称,并在界面上只呈现当前状态允许的控件。无论换成列表页、详情页还是双栏页,同一对象的状态含义不能因为组件拆分而悄悄改变。
对于 PulseCraft 的维护者,测试资料最好保留每个字段的取值例子和不变量的反例。比如让 finishedAt 先处于合法边界,再引入一个明显冲突的输入,观察处理函数是否拒绝变更。这样的测试不仅能发现当前错误,还能防止以后补功能时重启此前已解决的竞态。

最后,尽量避免为了追求少几行代码而把持久化、计算和展示全部塞进 SessionHistory.ets。可维护的最小结构通常只有一个领域模型、一组转换函数和一个边界适配器,三者通过明确参数通信。可见页面调用它们,但不应承担所有事实;这让测试能够独立覆盖没有设备也可推理的逻辑。
参考:HarmonyOS Preferences / @kit.ArkData 官方文档。
更多推荐


所有评论(0)