【口算王15】HarmonyOS ArkTS 本地状态持久化实战让保存、删除和页面返回后的数据即时一致证据边界本文依据 D:/huawei/one16-11 当前可读取源码整理本轮未执行构建、模拟器、真机、进程杀死重启、损坏数据注入、磁盘写入失败或数据迁移测试。改进方案属于建议实现不代表故障恢复已验证。“收藏成功”并不等于“数据已经可靠保存”。用户在练习页收藏一道题后至少会同时期待三件事当前按钮马上变成已收藏返回首页或收藏页时数量立即更新彻底退出应用再打开后记录仍然存在。只完成其中一件都可能出现“页面看起来成功重启后却丢了”或“已经写入磁盘别的页面却仍显示旧数量”的割裂体验。口算王当前采用了两层本地状态Preferences保存跨启动数据AppStorage与StorageLink负责当前进程内的共享和响应式刷新。练习页、首页、收藏页、统计页、我的页面和设置页都消费同一批记录。这个结构已经能完成收藏、笔记、错题、进度、考试历史和设置项的本地闭环但源码中也存在可复核的风险初始化读取由一个总try/catch包围一项 JSON 损坏可能让全部字段回落默认值写入失败被空catch吞掉“清空全部”由六次独立写盘组成并不具备事务原子性。本文基于口算王项目D:\huawei\one16-11的真实源码重点复核EntryAbility.ets、UserDataManager.ets、PracticePage.ets、SettingsPage.ets、HomePage.ets、FavoritePage.ets、MinePage.ets与LearningStatsPage.ets。包名com.jiaweikang.one16是本文草稿核验使用的唯一标记。项目目标和兼容 SDK 均为 HarmonyOS 6.0 系列文中的 Stage 模型、Preferences、AppStorage 和 ArkUI 状态管理方法适用于 HarmonyOS 5.0 及以上版本。本文将回答六个具体问题为什么持久化状态不能只放在 Preferences为什么更新数组后还要重新赋值给StorageLink启动恢复、页面返回和跨页面统计如何串成一条链路当前保存、删除和清空操作各自有什么一致性边界哪些代码是项目现状哪些属于后续增强建议如何用故障注入验证“看起来成功”与“真正保存”的差异。一、先定义“本地状态一致”到底意味着什么本地应用没有服务器并不代表状态问题简单。相反所有事实都落在一个设备里用户会更直接地把界面结果视为最终结果。对于一道被收藏的口算题至少存在四个观察面练习页按钮是否立即改变收藏页是否能马上找到这道题首页、我的页面和统计页的数量是否同步杀掉进程后重新启动记录是否仍能恢复。这四个观察面对应两种生命周期。当前进程里的组件需要响应式状态跨进程重启需要持久化状态。把它们混成一个概念很容易在实现时只顾一头。生命周期用户期望当前项目承担者当前组件内点击后按钮立即变化StorageLink重新赋值当前进程跨页面返回其他页面后数据一致AppStorage共享状态应用重启退出后再次进入仍存在Preferences数据清理页面和磁盘同时归零clear 方法加 StorageLink 回写因此口算王的真实模型不是“用 Preferences 保存数据”而是一个双层事实模型磁盘层负责恢复内存响应层负责广播。二、启动入口先完成水合再加载页面EntryAbility.onCreate()在页面加载前调用UserDataManager.init(this.context)。这一步很关键如果先展示页面再异步补数据首页统计、收藏角标和设置项会先显示默认值再突然跳变。当前实现选择同步读取把持久化值先写进 AppStorage然后页面通过StorageLink取得同一份状态。从源码可复核到的启动顺序是onCreate():void{UserDataManager.init(this.context)AppStorage.setOrCreate(currentTabIndex, 0)AppStorage.setOrCreate(favoriteTabIndex,0)}UserDataManager.init()获取名为daily_math_drill的 Preferences 实例并依次读取收藏、笔记、错题、题库进度、考试历史、章节进度以及三个设置项。数组通过JSON.parse()还原随后调用AppStorage.setOrCreate()建立共享状态。这里的“水合”可以理解为把磁盘快照注入当前运行时PreferencesJSON-解析为强类型数组- AppStorage.setOrCreate-各页面 StorageLink-ArkUI 渲染只要页面统一链接这些键首次渲染就能看到恢复后的结果不需要每个页面重复读取 Preferences。三、Preferences 负责耐久AppStorage 负责传播Preferences 和 AppStorage 的能力并不重复。Preferences 是键值持久化容器当前项目把复杂数组序列化成 JSON 字符串把布尔、数字和字符串设置项直接写入。它解决的是“应用重启后还在不在”。AppStorage 是当前应用进程中的共享状态容器页面通过StorageLink建立双向链接。它解决的是“一个页面改完后其他仍在组件树中的页面能不能观察到”。如果只写 Preferences磁盘是新的内存仍可能是旧的如果只改 AppStorage界面是新的重启后又会回到旧快照。因此一次完整修改至少包含两个动作constnextRecordsUserDataManager.toggleFavorite(this.favoriteRecords,record)this.favoriteRecordsnextRecords第一个动作在服务里生成新数组并持久化第二个动作把新数组赋回StorageLink触发共享状态和界面刷新。两者缺一不可。四、持久化键不是细节而是数据契约UserDataManager中的键定义了应用实际保存的本地数据范围键数据类型业务用途favoriteRecords收藏记录数组收藏题型与题目noteRecords笔记记录数组题目笔记wrongRecords错题记录数组错题复习bankProgress题库进度数组题库完成度examHistory考试历史数组成绩与统计chapterProgress章节进度数组章节维度进度dailyReminderTime字符串每日提醒时间examDurationSec数字考试时长autoNextQuestion布尔值自动进入下一题这份键表也给出了隐私和审核边界当前保存的是学习记录与应用设置没有账号、联系人、位置、相机、麦克风或网络上传逻辑。文章不能据此声称存在云同步、跨设备恢复或账号漫游因为源码中没有这些能力。键名一旦上线就相当于本地数据协议。后续重命名字段、调整记录结构或改变默认值时需要考虑旧版本已经写入的数据。当前代码没有显式 schema 版本因此结构演进仍依赖 JSON 字段兼容性。五、不可变数组是响应式更新的核心UserDataManager的收藏、笔记、错题和进度更新都返回新数组而不是在原数组上原地修改。这一点与 ArkUI 的状态观察机制十分契合。收藏切换的语义可以概括为constexistsrecords.some(itemitem.questionIdrecord.questionId)constnextexists? records.filter(item item.questionId ! record.questionId):[...records,record]persist(FAVORITE_KEY,next)return next新引用带来两个好处调用方能明确拿到本次变更后的值把新数组赋给StorageLink时状态系统能稳定识别变化。如果服务只执行records.push(record)然后仍返回原引用界面是否刷新就会依赖更细粒度的观察规则。对于跨页面共享数组显式创建新引用更容易推理也更适合测试。六、收藏操作如何穿过完整链路练习页持有收藏记录的共享链接。当用户点击收藏按钮时页面把当前题目转换为收藏记录调用toggleFavorite()再把返回数组赋回favoriteRecords。完整链路如下用户在 PracticePage 点击收藏页面构造包含questionId等字段的记录UserDataManager 判断该题是否已存在服务生成过滤后的数组或追加后的新数组服务把 JSON 写入 Preferences 并flushSync()页面把返回值赋给StorageLinkFavoritePage、MinePage、HomePage 等链接同一键的页面观察到新值下次启动时 init 从 Preferences 恢复这份数组。这里还存在一个真实边界当前去重只使用questionId。如果不同题库未来可能生成相同 questionId就可能互相覆盖。项目现状没有复合主键把bankId questionId作为稳定身份属于后续增强不能描述成已经实现。七、笔记使用 upsert但身份规则仍然单一笔记采用 upsert 语义先过滤掉相同questionId的旧记录再追加新记录。它能保证一道题只有一条当前笔记适合编辑覆盖场景。constnextrecords.filter(itemitem.questionId!note.questionId).concat(note)这个实现避免了“编辑一次新增一条”的重复问题但同样依赖 questionId 全局唯一。若题目 ID 只在题库内部唯一后续应把题库标识纳入记录身份。删除笔记则是同样的不可变过滤流程生成新数组、落盘、回写 StorageLink。这样设置页或收藏页中的笔记数量可以立即变化。八、错题不是一次性结果而是持续修正的状态练习页会在答错时调用addWrong()在后续答对或移除时调用removeWrong()。错题集因此不是简单日志而是一个当前待复习集合。addWrong()需要避免同一道题重复堆积removeWrong()通过 questionId 过滤。调用方继续遵循同一契约this.wrongRecordsUserDataManager.addWrong(this.wrongRecords,wrongRecord)根页面Index、首页、收藏页、统计页和我的页面都链接 wrongRecords。只要新数组被写回共享角标、入口数量和错题列表就能在同一进程中保持一致。这也解释了为什么“服务已经写盘”仍不够。如果调用方忘记赋值磁盘记录是新的但Index上的错题角标可能继续显示旧数量直到应用重启重新水合。九、进度更新有两种不同身份题库进度和章节进度看似相似实际索引不同bankProgress按bankId更新chapterProgress按bankId chapterId更新。后者已经体现了复合身份的必要性。章节 ID 离开题库上下文可能不唯一因此同时比较两个字段。它也是收藏、笔记和错题未来调整身份策略时可以复用的思路。练习过程中PracticePage 把更新后的题库进度与章节进度都重新赋给相应 StorageLink。HomePage 的题库卡片、LearningStatsPage 的统计信息和 MinePage 的个人数据因此可以共享同一份进度。十、设置项也有持久层和显示层SettingsPage 链接三个设置项每日提醒时间考试时长秒数自动下一题开关。页面修改设置后一方面调用 UserDataManager 保存标量值另一方面更新 StorageLink。源码中还维护了displayReminderTime、displayExamDurationSec、displayAutoNextQuestion三个显示镜像并通过 revision 字段推动局部刷新。这种写法能解决当前页面显示问题但带来了“双份内存状态”AppStorage 真值displayXxx 页面镜像revision 强制刷新标记只要某个修改分支漏掉其中一步就可能出现开关已保存但标签仍显示旧值。更稳妥的增强方向是让 UI 尽量直接派生自 StorageLink只在弹窗编辑草稿确实需要与已保存值隔离时保留局部状态。十一、返回页面为什么能看到最新值SettingsPage 中的数据入口会先修改主 Tab 或收藏页内部 Tab再调用router.back()。返回后根页面仍然链接同一个 AppStorage 键所以不需要重新从磁盘查询。这个机制的关键不是back()自动刷新而是目标页面一直消费共享状态。返回动作只改变可见页面状态变化已经在之前的 StorageLink 赋值中传播。例如清空错题后返回收藏页clearWrong()-Preferences 写入 []- SettingsPage.wrongRecords []-AppStorage 的 wrongRecords 更新-FavoritePage 已链接的 wrongRecords 变为空- router.back 后直接展示空状态如果目标页在aboutToAppear()中自行读取另一份缓存反而可能覆盖这个新值。当前核心页面统一使用 StorageLink是页面返回后即时一致的基础。十二、清空单项是可预测的清空全部不是事务每种记录都有独立 clear 方法。单项清空的影响范围清楚一个 Preferences 键被写成空数组调用方把同一 StorageLink 设为空数组。SettingsPage 的“清空全部”则按顺序调用六个 clear 方法清空收藏清空笔记清空错题清空题库进度清空考试历史清空章节进度。每个 clear 方法内部都会独立putSync()和flushSync()。因此这个流程不具备数据库事务意义上的原子性。假设前三次成功、第四次因存储异常失败可能出现部分数据已清空、部分数据仍保留的中间状态。源码当前还会吞掉持久化异常页面仍可能把六个 StorageLink 全部设为空造成“当前界面全空重启后部分记录又回来”的问题。这是当前实现最值得优先补强的一致性风险。十三、两次确认保护误操作但不等于保存成功设置页使用pendingClear实现两次点击确认。第一次点击进入待确认状态第二次才执行清空。这对防止误触有效也符合破坏性操作需要明确确认的体验要求。不过交互确认解决的是“用户是否真的想删”不能证明“删除是否全部写盘成功”。完整状态至少应区分待确认正在清理清理成功部分失败或失败可重试。当前页面主要维护确认和完成后的显示计数尚未从 UserDataManager 得到明确的成功或失败结果。后续若增强持久化方法应返回结构化结果而不是用空 catch 隐藏失败。十四、初始化的总 catch 会放大单键损坏当前init()用一个较大的try/catch包住多项读取和 JSON 解析。这样写简洁但故障隔离不足。假设 favoriteRecords 的 JSON 完好noteRecords 的 JSON 因旧版本或意外写入而损坏解析笔记时抛出异常后后续错题、进度、历史和设置项都可能跳到统一兜底。用户看到的不是“笔记损坏”而是多个看似无关的数据同时恢复默认。更合适的增强结构是按键隔离解析functionreadJsonArrayT(key:string,fallback:T[]):T[] {try{const raw prefs.getSync(key, []) as stringconstvalueJSON.parse(raw)returnArray.isArray(value)?valueasT[]:fallback} catch (error) {returnfallback}}这段是工程增强示意不是当前源码已有函数。它的价值在于把损坏范围限制到单个键并为后续日志、修复提示或数据迁移留下入口。十五、空 catch 让调用方无法区分成功与失败persist()当前流程是prefs.putSync(key,JSON.stringify(value))prefs.flushSync()异常被捕获后没有返回值也没有错误状态。调用方因此会继续把新数组赋给 AppStorage。对用户而言按钮和统计都像成功了只有重启后才可能暴露数据没有落盘。建议把持久化结果显式化例如interfacePersistResult {success:booleankey: stringreason?:string}页面可以在失败时保留旧状态、显示可重试提示或至少记录一个非敏感错误码。不要把完整记录内容写入日志尤其当未来笔记中可能包含用户输入文本。十六、同步 flush 的好处与性能代价当前每次修改都调用flushSync()。它的优点是调用返回时写盘动作已经完成语义直接适合数据量较小、修改频率有限的收藏和设置操作。代价是同步 I/O 可能占用 UI 线程。一次收藏通常问题不大但练习过程中频繁更新进度或清空全部连续执行六次 flush就会扩大阻塞窗口。优化时不能简单把所有写入都改成延迟写因为异常退出可能丢失最新进度。可以按数据价值分级数据写入频率建议策略收藏、笔记低操作后立即可靠写入错题中结果确认后写入练习进度较高小窗口合并关键节点强制落盘设置项低用户确认后写入清空全部极低批量提交并统一反馈具体是否采用异步 flush需要结合 HarmonyOS API 行为、页面生命周期和实机性能测试决定。当前项目的真实实现仍是同步写入。十七、统计数字不应成为第二份真值SettingsPage 维护收藏、笔记、错题等 display count并在aboutToAppear()或清理后手动同步。这样能快速控制界面但这些数字本质上都可以从数组长度派生。当真值和镜像并存时新增一个修改入口就必须记得同时更新records 数组displayCountdataRevision最小增强是把计数集中到一个同步方法进一步可以让 Text 直接读取this.favoriteRecords.length等派生值。这样任何页面只要正确回写 StorageLink设置页数量就不会因为漏调同步方法而漂移。十八、用版本号管理未来数据结构当前 JSON 能否成功恢复依赖记录结构长期兼容。随着应用增加题型、来源、难度或多设备字段旧记录可能缺少新字段新代码也可能不再理解旧枚举。可以在 Preferences 中增加轻量 schemaVersioninterfaceStoredEnvelopeT{schemaVersion:numberdata: T}初始化时按版本执行迁移读取版本验证外层结构补齐新增字段丢弃无法识别的单条坏记录而不是清空整个集合写回最新版本再注入 AppStorage。这同样属于增强建议。当前源码保存的是直接 JSON 数组没有 envelope 和显式迁移器。十九、清空全部的改造应先建立快照如果继续使用 Preferences而不引入数据库事务可以把“清空全部”改造成可回滚的批处理先读取六个键的当前快照在内存中构造完整空状态逐键写入但暂不更新页面所有写入成功后统一 flush成功后一次性回写六个 StorageLink任一步失败则恢复快照并向页面返回失败结果。不同 HarmonyOS 版本的 Preferences 批量能力需要以官方 API 为准。即使无法提供严格事务也应确保 UI 不在持久层失败时宣告全部成功。从架构上看还可以把六个数组封装为一个版本化UserLearningSnapshot一次序列化写入单键。这样原子边界更清楚但局部更新会重写更大的 JSON。是否值得需要以真实数据规模和写入频率评估而不是机械追求单键。二十、四层结构让状态职责更清楚基于当前源码可以把职责整理成四层1. Page负责用户动作、短期交互状态、确认弹窗和成功失败提示。页面不应知道 Preferences 键名也不应手写 JSON。2. UserDataManager负责记录身份、不可变更新、序列化、持久化结果和数据迁移。当前项目已经集中管理键和大多数更新逻辑这是良好基础。3. AppStorage负责当前进程的共享状态分发。它不是长期数据库不承担跨启动恢复。4. Consumer Pages首页、收藏页、我的页面、统计页和设置页只消费共享状态并派生 UI。统计数字应尽量从共享数组计算不再维护额外真值。这四层形成一条明确规则页面发起意图服务生成并保存下一状态AppStorage 广播已确认状态消费页面只做渲染。二十一、测试不能只看一次点击本地状态的测试至少要覆盖“当前页面、跨页面、重启、故障”四类场景。正常链路收藏一题按钮立即选中返回收藏页列表出现该题首页和我的页面数量同步增加杀进程重启收藏仍存在再次取消收藏所有页面同步减少。笔记与错题新增笔记后编辑记录数不重复增加删除笔记后返回页面立即消失答错后进入错题集移除错题后角标和统计同步检查不同题库是否可能出现相同 questionId。设置项修改考试时长后进入训练行为使用新值开关自动下一题重启后保持页面返回时显示值与共享值一致快速连续操作不出现镜像和真值分离。清理流程第一次点击只进入确认状态取消确认不修改任何记录清空单项只影响目标类别清空全部后六类数据均为空重启后不会恢复已清空数据模拟中途写入失败页面不能虚假显示全部成功。损坏与迁移单个 JSON 键损坏时其他键仍可恢复字段缺失时使用明确默认值未知记录能被跳过或迁移保存失败时用户得到可理解且可重试的状态。二十二、性能验证要围绕真实写入频率本地数据量不大不代表无需测量。建议在调试构建中只记录非敏感性能指标单次 JSON 序列化耗时单次 flush 耗时清空全部总耗时启动水合总耗时各数组记录数量页面首次可交互时间。不要打印题目笔记正文或完整用户记录。性能日志只需要键名、数量、耗时和结果码。当进度数组增长后还应验证 JSON 序列化是否造成明显主线程卡顿。若实测出现问题再考虑分片、节流、异步持久化或迁移到 RelationalStore。当前数据仍是轻量键值与小型数组Preferences 的选择与现有业务规模匹配。二十三、与多设备能力的边界要说清楚AppStorage 能让同一应用进程的多个页面共享状态Preferences 能让同一设备上的应用重启恢复但它们都不等于跨设备同步。如果手机收藏一道题平板自动出现该记录需要账号身份、分布式数据或云端同步协议还需要冲突合并、隐私声明、网络失败和离线策略。口算王当前源码没有这些实现因此本文只讨论单设备本地一致性。即便后续增加多设备能力本地双层模型仍然有价值云端数据落地后先进入本地仓库再更新 AppStorage离线修改进入待同步队列远端合并结果重新广播。不能直接让页面同时操作云端和本地多个真值。二十四、发布审核前的数据一致性检查对于 HarmonyOS 5.0 及以上应用本地状态还关系到运行稳定性和隐私一致性。发布前应核对应用描述是否准确说明数据仅保存在本地隐私政策是否与实际保存的学习记录和设置一致未声明源码中不存在的云同步能力清空功能是否真的清除持久化数据不需要的网络或敏感权限是否未申请异常 JSON 不会导致启动崩溃存储失败不会让页面永久卡住或无响应深浅色、横竖屏和小窗口下确认操作仍可触达安装、启动、核心练习、退出重启和卸载流程正常。卸载后 Preferences 会随应用数据删除但“卸载即清除”不能替代应用内可见的清理能力。当前设置页已提供分项和全部清理入口下一步重点是让执行结果可验证。二十五、常见问题排查表症状可能原因优先检查点击收藏后按钮不变只持久化没有回写 StorageLink调用方是否赋值返回数组当前页面正常重启后丢失persist 失败但异常被吞掉put/flush 结果与错误反馈返回首页数量不变页面消费了局部副本是否统一使用同一 AppStorage 键清空后重启数据回来部分 flush 失败UI 仍清空清空批处理结果与回滚一项数据损坏后多项归零init 使用总 try/catch改为逐键解析和兜底笔记编辑后出现重复upsert 身份不稳定questionId 是否真正全局唯一设置显示和实际行为不同display 镜像漏同步减少镜像直接派生练习时偶发卡顿高频同步 flush测量频率与耗时后分级优化升级版本后记录无法解析没有 schemaVersion增加版本和迁移器平板没有手机收藏把本地存储误认为跨设备同步明确本地与云同步边界二十六、总结一致性来自一条可验证的状态契约口算王当前的本地数据实现已经具备清楚的主干EntryAbility 启动时从 Preferences 水合UserDataManager 集中管理键和不可变更新页面把服务返回的新数组写回StorageLinkAppStorage 再把变化传播给首页、收藏、统计、我的和设置页面。这个结构让保存、删除、页面返回和重启恢复能够形成闭环。真正需要补强的不是再增加一层缓存而是让现有契约更可靠初始化按键隔离避免单项损坏拖累全部数据persist 返回明确结果不再吞掉失败清空全部建立批处理或回滚边界显示计数从共享数组派生减少镜像状态记录身份按业务范围设计必要时使用复合键增加 schemaVersion为升级迁移留出空间用重启、故障注入和跨页面测试验证真实结果。当磁盘层、响应层和页面层各自只承担一种职责用户看到的“已保存”才不仅是按钮变色而是可以经受页面切换、进程重启和异常场景检验的事实。