【转盘决定吧|12】HarmonyOS ArkTS 6.0.2.130 模型与持久化:Preferences、AppStorage 和版本迁移
一个转盘应用的数据看起来并不复杂:转盘有标题和选项,旋转后产生一条历史,设置页面保存主题、声音与振动开关。真正容易出问题的位置,不是字段数量,而是这些对象要同时经过 ArkTS 类型系统、、JSON.stringify()Preferences、AppStorage 和 ArkUI任何一层把“类型声明”当成“运行时保证”,升级后都可能出现数据能读出来、页面也不崩溃,但标题为空、活动转盘失联或开关值被悄悄改写的情况。
本文基于“转盘吧”1.0.9 的真实源码,versionCode为2000008,targetSdkVersion与一系列compatibleSdkVersionHarmonyOS 6.0.2(22)。核心文件不是孤立的示例,而是当前工程中的Models.ets、、、、、与。文章会先现有物流货运,再给出可以落地的解码、迁移、提交与核验方案。PreferencesStore.etsWheelService.etsHistoryService.etsSettingsService.etsEntryAbility.ets

本文要回答五个具体问题:
Wheel、WheelOption、HistoryRecord各自AppSettings承担什么数据契约。- 为什么
JSON.parse(raw) as T只让编译器接受结果,却不能得出磁盘数据确实符合T。 - Preferences 与 AppStorage 要分工,而不能互相替代。
- 内存先更新、磁盘后提交时,失败和装载写入会造成什么状态差异。
- 带上
_v1关键如何演进真正的可迁移、可恢复、可核验的版本协议。
文中“当前行为”均来自上述源码工程;改进用于说明边界安全,不表示工程已经应用这些。真正可靠的本地数据修改,不是把对象变更JSON.stringify就结束,而是让模型校验、版本迁移、持久化和AppStorage共享同一个可追踪契约。
事实与建议实现的边界源码
本文用“本地模型持久化双写源码”约束事实范围:能够在当前中定位直接的类型、键名、调用顺序和读写行为源码属于事实;解码器、迁移器、队列、错误态与 RDB 方案暗示实现,不能据此推断应用已经具备这些能力。
| 观察项 | 当前事实源码 | 建议实现,尚未代表落地 |
|---|---|---|
| 模型 | Models.ets定义 Wheel、WheelOption、HistoryRecord、AppSettings 等类与联合类型 | 为磁盘数据增加逐字节运行时解码器 |
| 存储封装 | PreferencesStore使用同一个random_picker_store,字符串和 JSON 读取后立即flush() | 初始化失败明显式上抛,并提供可安装错误状态 |
| JSON 读取 | getJson<T>()通过JSON.parse(raw) as T返回泛型结果,语法错误时回退默认值 | 校验类型、字段类型、枚举值和读取队列 |
| 状态镜像 | Wheel、History、Settings 服务把加载结果写入 AppStorage | 只把通过解码的可信快照送入UI |
| 写入顺序 | 大部分业务方法先替换AppStorage,再等待Preferences提交 | 按业务选择“提交后更新UI”或可追踪的后台队列 |
| 键版本 | 当前存在wheels_v1、history_records_v1、app_settings_v1,但没有迁移函数 | 增加幂等迁移、写后校验和旧数据保留周期 |
| 预设转盘 | wheels_v1不存在、不是存储或为空时会重建3个预置转盘 | 使用独立初始化标记区分首次安装与用户主动清空 |
| 验证状态 | 本轮读取真实源码并运行文章硬检查,没有重新构建,也没有执行真机冷启动、故障注入或升级安装 | 文中的HDC与测试表是后续验收方法,不是已通过结果 |
一、先画出当前数据导入
应用在EntryAbility.onCreate()中依次初始化Preferences、设置、历史、转盘和声音服务。Preferences保存跨进程重启仍需保留的数据;每个业务服务把读取结果再写入进AppStorage,页面通过@StorageLink获得响应式更新。用户编辑转盘或产生历史时,服务先替换AppStorage中的内存,然后把整个队列序列化为字符串并flush()到磁盘。

当前可压缩为:
Models.ets
-> Service.load()
-> PreferencesStore.getJson<T>()
-> AppStorage.setOrCreate()
-> @StorageLink 渲染
-> Service.save()/add()/remove()
-> AppStorage 新快照
-> JSON.stringify + Preferences.flush
多层结构的方向是明确的:页面不直接操作首选项,持久化集中在服务层,UI只订阅AppStorage。但“有分层”并不代表数据契约已经闭环,真正的边界在反序列化、提交失败和版本升级三个位置。
二、六个模型覆盖了三类生命周期
Models.ets 定义了 WheelOption、Wheel、PickList、HistoryRecord、AppSettings、FunCategory 与 ReadingArticle。其中真正进入 Preferences 链路的是转盘、历史和设置三组对象。
| 模型 | 关键字段 | 生命周期 | 当前持久化位置 |
|---|---|---|---|
WheelOption | id、text、color | 跟随所属转盘 | wheels_v1 的嵌套数组 |
Wheel | id、title、options、createdAt、updatedAt | 长期业务数据 | wheels_v1 |
HistoryRecord | id、type、title、result、timestamp | 最多保留 500 条 | history_records_v1 |
AppSettings | theme、soundEnabled、vibrationEnabled | 长期轻量设置 | app_settings_v1 |
| 活动转盘 ID | 字符串 | 当前选择 | active_wheel_id |
HistoryType 被限制为 'wheel' | 'pick' | 'coin' | 'dice' | 'fun',ThemeMode 被限制为 'light' | 'dark' | 'auto'。这些联合类型能约束源码中的调用,却无法自动约束从旧版本磁盘文件读出的字符串。运行时的 "purple" 仍然可以被断言成 ThemeMode,这正是持久化层需要显式校验的原因。
三、类实例写入 JSON 后不会自动复活
新建转盘时,工程确实创建了 new Wheel() 和 new WheelOption()。经过 JSON.stringify() 后,磁盘只保留普通对象字段;再次 JSON.parse() 得到的也是普通对象,不是带有原型和方法的类实例。当前模型没有业务方法,因此页面读取字段暂时可用,但这条边界仍必须写清楚。
例如以后给 Wheel 增加方法:
export class Wheel {
id: string = '';
title: string = '';
options: WheelOption[] = [];
canSpin(): boolean {
return this.options.length >= 2;
}
}
从 JSON 读出的对象无法可靠调用 canSpin()。正确做法有两种:要么让持久化模型保持纯数据结构,把业务规则放进 Service;要么在解码阶段显式创建 Wheel 和 WheelOption 实例。对当前项目而言,第一种更简单,也更符合“数据对象只描述状态”的职责。
四、泛型 getJson<T> 不是运行时校验器
当前 PreferencesStore.getJson<T>() 的核心是:
static getJson<T>(key: string, def: T): T {
const raw = PreferencesStore.getString(key, '');
if (!raw) return def;
try {
return JSON.parse(raw) as T;
} catch (e) {
hilog.warn(0, TAG, 'parse json failed key=%{public}s', key);
return def;
}
}
这里能处理 JSON 语法损坏,却处理不了“语法正确、结构错误”的数据。{"theme":123}、[{"id":"","options":"火锅"}] 都能成功解析;as T 不会生成任何运行时代码。WheelService 只再检查了一次 Array.isArray(list),HistoryService 也只确认顶层是数组,嵌套对象仍可能缺字段或字段类型错误。
因此持久化 API 更适合返回 Object | Array<Object> | null 一类未知结构,再交给每个领域解码器。ArkTS 强类型的价值不在于多写一个断言,而在于让“不可信磁盘数据到可信领域对象”的转换路径明确可见。
五、为 Wheel 建立逐层解码器
转盘有嵌套选项,是最需要结构校验的对象。解码时至少确认:转盘 ID 与标题为非空字符串;选项是数组;每个选项都有稳定 ID、非空文本和合法颜色;时间戳为有限正数。坏掉的一条转盘不应拖垮整个列表,也不应悄悄变成空白卡片。
下面的写法展示边界,具体颜色白名单可以复用 Palette.WHEEL_COLORS:
interface WheelDTO {
id: string;
title: string;
options: WheelOptionDTO[];
createdAt: number;
updatedAt: number;
}
interface WheelOptionDTO {
id: string;
text: string;
color: string;
}
function isText(value: Object): boolean {
return typeof value === 'string' && value.trim().length > 0;
}
ArkTS 对动态对象访问限制更严格,实际工程可以把 JSON.parse() 的输出先映射到显式 DTO,再由 decodeWheel() 创建可信值。不要在页面里重复 obj['id']、obj['title'] 的临时判断;解码只属于存储边界。
六、Preferences 适合轻量键值,不等于适合所有本地数据
华为 ArkData 文档把 Preferences 定位为轻量级配置数据持久化,典型场景是应用配置与用户偏好;关系型数据管理则提供结构化增删改查。当前主题、声音、振动、活动转盘 ID 都是典型 Preferences 数据。三个预置转盘和少量自定义转盘也可以接受整包 JSON 存储。
历史记录的性质不同。工程上限为 500,每产生一次结果都会:创建新数组、截断、序列化整个数组、覆盖同一个字符串并 flush()。数量不大时实现简单,但随着结果文本变长,写放大会逐步增加。如果后续要支持按时间范围查询、分页、统计、导出或单条更新,HistoryRecord 应成为迁移到 RDB 的第一组数据,而不是继续扩大一个 JSON 数组。
选择依据不是“Preferences 能不能存”,而是数据是否需要局部查询、局部更新、索引、迁移和容量治理。
七、PreferencesStore 的单例边界是合理的
PreferencesStore 用静态字段保存唯一 preferences.Preferences 实例,所有业务服务共享名为 random_picker_store 的存储。这样能避免页面各自创建实例,也让键名和序列化行为集中在一个位置。
private static pref: preferences.Preferences | null = null;
static async init(context: common.UIAbilityContext | common.Context): Promise<void> {
if (PreferencesStore.pref) return;
PreferencesStore.pref = await preferences.getPreferences(context, STORE_NAME);
}
问题不在单例,而在初始化失败后的状态表达。当前 init() 捕获异常、记录日志后返回 void;调用方会继续执行设置、历史和转盘加载。随后 getString() 返回默认值,putString() 直接返回,应用看起来能运行,却失去了持久化能力。
八、初始化失败不能伪装成“首次安装”
Preferences 获取失败与“键不存在”是两种完全不同的状态。前者说明存储服务不可用,后者才适合使用默认值。当前实现把两者都折叠成默认值,可能触发 WheelService 重建三个预置转盘,然后调用一个同样会静默返回的 putJson()。用户看到正常界面,下一次启动仍会重复重建。
更明确的契约是让初始化失败向上抛出,或保存一个可查询的初始化状态:
export class PreferencesStore {
private static pref: preferences.Preferences | null = null;
static async init(context: common.Context): Promise<void> {
PreferencesStore.pref = await preferences.getPreferences(context, STORE_NAME);
}
private static requireStore(): preferences.Preferences {
if (!PreferencesStore.pref) {
throw new Error('PreferencesStore is not initialized');
}
return PreferencesStore.pref;
}
}
这样 EntryAbility 的统一 try/catch 才能真正识别服务初始化失败,并决定展示错误态、允许重试或进入只读模式,而不是把故障误判为没有数据。
九、启动顺序已经体现了依赖关系
当前 EntryAbility.onCreate() 的顺序是:
await PreferencesStore.init(this.context);
const settings = await SettingsService.load();
await HistoryService.load();
await WheelService.load();
SettingsService.applyTheme(settings.theme);
await SoundService.init();
Preferences 必须先于三个业务服务;设置必须先加载,才能应用主题;AppStorage 必须在页面通过 @StorageLink 订阅前写入可信初值。这个顺序是正确的架构信号。
需要补足的是“窗口何时可见”的失败语义。onCreate() 中即使服务初始化失败,onWindowStageCreate() 仍会加载 pages/Index。根页面至少应订阅一个 bootstrapState,区分 loading、ready 与 error,避免把空数组误当成用户真的没有历史或转盘。
十、WheelService 的预置恢复有副作用
WheelService.load() 在数组为空时创建三个预置转盘:今天吃什么、现在做什么、去哪玩。这让首次启动有可操作内容,但也意味着“用户主动删除全部转盘”和“存储中从未有转盘”会得到同样结果。当前编辑页删除最后一个转盘后,下一次冷启动会重新生成全部预置项。
这是否正确取决于产品定义。如果业务不允许零转盘,应在删除最后一个之前阻止并解释;如果允许空状态,就需要单独保存 has_initialized_wheels,不能仅用空数组判断首次启动。默认数据策略本身也是数据契约,而不是 UI 细节。
十一、活动转盘 ID 必须与列表共同校验
当前 active_wheel_id 独立于 wheels_v1 保存。加载时直接把字符串写入 AppStorage;页面找不到对应 ID 时会回退到列表第一项。视觉上仍能显示转盘,但选中样式依赖 w.id === activeId,因此回退项可能没有高亮,磁盘里也继续保留陈旧 ID。
加载阶段应把活动 ID 归一化:
const savedId = PreferencesStore.getString(ACTIVE_KEY, '');
const activeId = list.some((wheel: Wheel) => wheel.id === savedId)
? savedId
: list[0].id;
AppStorage.setOrCreate<string>(WheelService.ACTIVE_STORAGE_KEY, activeId);
if (activeId !== savedId) {
await PreferencesStore.putString(ACTIVE_KEY, activeId);
}
这样页面状态和持久化状态会在一次启动内收敛。删除转盘时也应由 WheelService 在同一业务操作中更新列表与活动 ID,而不是要求每个调用页面记住第二次调用 setActive()。
十二、AppStorage 是运行时镜像,不是数据库
WheelService、HistoryService 和 SettingsService 都把对象写进 AppStorage,页面通过 @StorageLink('wheels')、@StorageLink('historyList')、@StorageLink('settings') 自动刷新。这是合理的 UI 状态通路:AppStorage 负责当前进程内的共享与通知,Preferences 负责重启后的恢复。
需要避免两个误区。第一,写入 AppStorage 不代表磁盘提交成功;第二,直接修改嵌套对象不一定触发期望的界面更新。当前代码多数采用 list.slice()、concat() 或创建新对象再整体替换,这比原地修改数组更稳健。WheelEdit.cycleColor() 修改选项后又执行 this.options = this.options.slice(),正是为了显式产生新数组引用。
十三、当前提交顺序可能制造“本次会话成功”假象
三个业务服务写数据时都先更新 AppStorage,再等待 Preferences:
AppStorage.setOrCreate<Wheel[]>(WheelService.STORAGE_KEY, next);
await PreferencesStore.putJson<Wheel[]>(KEY, next);
如果 put() 或 flush() 抛错,界面已经显示新转盘,调用方却可能进入异常路径;如果错误被上层忽略,用户会以为保存成功,重启后数据回退。历史新增更明显:多个页面在动画完成后调用 HistoryService.add(),但没有 await,随后立即跳转结果页。磁盘失败不会阻止流程,也没有用户可见反馈。
对“保存”按钮,建议先持久化成功再替换 AppStorage;对“旋转历史”这类不应阻塞主动画的写入,可以采用明确的后台提交队列,并在失败时记录待重试状态。两类业务不必强行采用同一种交互策略,但都必须让失败可追踪。
十四、并发写入需要串行化
save()、remove()、add() 都先从 AppStorage 取当前快照,再构造 next。如果短时间内两个异步操作同时开始,它们可能基于同一旧快照计算,各自覆盖 Preferences。常见例子是连续产生两条历史:两次 add() 都读到 N 条,最后完成的写入只包含自己的新记录,另一条被覆盖。
简单应用可以在 Service 内维护一条写入链,让读快照、计算和提交位于同一个串行任务中。另一种做法是引入仓储层,由仓储统一负责队列、重试与错误映射。关键不是增加文件数量,而是确保“读旧值到提交新值”是一个不可交错的业务单元。
十五、HistoryRecord 的 500 条上限只解决数量问题
HistoryService 使用 [record, ...current].slice(0, 500),新记录在前,最多保留 500 条。这个规则简单明确,也能防止无限增长。但它没有约束单条 title 和 result 长度,没有记录数据结构版本,也没有提供按类型之外的索引。
如果继续使用 Preferences,至少应在写入前限制文本长度,并在加载后逐条过滤:ID 为空、type 不在联合类型集合、时间戳无效的记录应丢弃或隔离。若产品增加搜索、月度统计、分页与导出,则直接设计 RDB 表比继续扩展 JSON 修补逻辑更清晰。
十六、SettingsService 已有迁移意识,但校验还不完整
SettingsService 没有直接返回解析对象,而是创建 new AppSettings() 再合并字段:旧数据缺少声音或振动字段时,默认值仍然成立。这是正确的向前兼容思路。
const merged = new AppSettings();
merged.theme = (raw.theme || 'auto') as ThemeMode;
merged.soundEnabled = raw.soundEnabled !== false;
merged.vibrationEnabled = raw.vibrationEnabled !== false;
不足在于 raw.theme 只要是真值就会被断言成 ThemeMode。应显式检查 light、dark、auto 三个值。布尔字段也应确认 typeof value === 'boolean';当前表达式会把字符串 "false" 当成启用。合并默认值与运行时校验要一起做,才能称为迁移。
十七、键名带 v1 只是版本提示,不是迁移逻辑
wheels_v1、history_records_v1、app_settings_v1 已经体现版本意识,但代码目前只读取 v1,没有 schemaVersion、旧键探测、迁移成功标记或回滚策略。以后改为 wheels_v2 时,如果直接换键,用户会看到预置转盘,旧数据仍留在 v1,却没有迁移入口。
一个安全迁移流程应包含:
- 优先读取新键;新键有效就直接使用。
- 新键不存在时读取旧键,并用旧版本解码器恢复。
- 转换为新 DTO,写入新键并
flush()。 - 重新读取新键确认数量与关键 ID。
- 最后再删除旧键,或保留一个版本周期用于回滚。
迁移必须幂等。应用在第 3 步后被系统终止,再次启动仍应安全继续,而不是重复生成 ID 或叠加预置数据。
十八、坏数据恢复不能立即覆盖唯一证据
当前 JSON 语法错误时直接返回默认值。WheelService 随后把预置数据写回原键,损坏原文会被覆盖,排查证据消失。更稳健的做法是先把原字符串复制到 wheels_v1_corrupt_<timestamp> 或应用沙箱文件,再写入恢复值;同时记录键名、长度、恢复条数,不记录完整用户内容。
对于普通用户,界面可以提示“本地转盘数据无法读取,已恢复默认内容”;对于开发与回归阶段,保留坏数据副本能复现解码问题。恢复策略要兼顾可用性和可诊断性,而不是只追求不崩溃。
十九、敏感性与日志边界
转盘标题、选项与历史结果可能包含用户自定义文本。它们虽然不一定属于高敏感数据,也不应完整输出到公共日志。当前 PreferencesStore 的解析错误只记录 key,这个方向是安全的;初始化错误使用 JSON.stringify(e) 并标为 public,则可能携带路径或系统细节,适合改成错误码和有限消息。
本应用定位为本地工具,Preferences 数据保存在应用沙箱中,卸载时随应用数据删除。文章中的调试方案也只核对数量、ID 是否存在、版本与错误码,不打印完整选项和历史内容。
二十、四层职责应该固定下来

可以把当前工程的职责稳定为四层:
| 层 | 负责 | 不负责 |
|---|---|---|
| Model/DTO | 字段、默认值、版本结构 | 直接访问 Context 或 Preferences |
| Decoder/Migration | 未知数据校验、旧版本转换、坏数据隔离 | 导航页面与视觉状态 |
| 服务/存储库 | 业务规则、串行提交、按键名、错误映射 | ArkUI 组件树 |
| AppStorage/UI | 当前进程图像、订阅、加载与错误提交 | 把内存状态当成提交成功 |
这不是为了增加抽象,而是为了让每次数据变化只有一个可信入口。当前小型工程可以把解码器放在服务同文件中;当模型和迁移激增时,再拆除独立以太坊也不迟。
二十一、冷启动核验要验证而不是数据只看页面
先前固定版本与包名:com.jiaweikang.one4、应用 1.0.9、versionCode 2000008、API 22。然后执行以下真机路径:
- 首次安装启动,确认生成3个预置转盘,活动ID指向第一个。
- 新建一个转盘,修改标题和颜色,返回后立即可以看到新值。
- 强制停止进程后重新启动,新转盘、活动项和设置均恢复。
- 连续产生3条不同类型历史,重启后顺序保持“新到旧”。
- 删除当前活动转盘,重新启动后活动 ID 恢复到仍存在的第一个。
- 切换主题、声音、振动,逐项重启确认,不把字符串误当布尔值。
- 模拟无效主题和缺字段旧数据,确认解码后回落默认值。
- 模拟JSON语法损坏,确认应用进入可解释的恢复路径,并保留损坏的数据副本。
hdc list targets -v
hdc shell aa force-stop com.jiaweikang.one4
Write-Host "重新从桌面启动应用并核对转盘、历史与设置"
hdc shell hilog -x | findstr "PrefStore EntryAbility"
日志通过条件是初始化完成一次、迁移版本明确、恢复条数与 UI 一致、没有完整的用户文本。这里不把未运行的设备结果写成成功,只给出可以重复执行的操作和判定条件。
二十二、服务级测试应覆盖五类边界
持久化代码的价值主要体现在异常输入。至少准备以下数据集:
| 输入 | 预期 |
|---|---|
| 空字符串 | 使用默认值,不写恢复日志 |
| 非法 JSON | 隔离译文,默认返回值并记录键名 |
| 收入不是储备 | 转盘与历史拒绝该值 |
| 后台中混入坏对象 | 保留合法项目,记录丢弃数量 |
| v1 旧对象缺字段 | 使用默认值迁移到新的 DTO |
| 活动ID不存在 | 回退第一篇并回写新ID |
| 双重增加 | 预留记录都存在且顺序确定 |
| 冲洗失败 | UI不暗示“已保存”状态 |
解码器尽量写成不依赖 Context 的纯函数,这样本地测试不需要 HarmonyOS 运行时。首选项只负责 get、put、flush 和异常映射,业务服务用可替换接口调用它,测试时可注入内存实现并主动制造提交失败。
二十三、落地顺序
对当前工程,改造不需要一次更换掉所有存储。可以按风险递增分四步:
- 首先让首选项初始化失败向上暴露,根页面增加加载与错误状态。
- 给 ThemeMode、Wheel、WheelOption、HistoryRecord 增加运行时解码。
- 统一活动ID修复、串行化和提交失败反馈。
- 为键增加正式迁移函数;历史查询需求增长时迁至RDB。
每一步都应先写一个边界,再修改实现,最后执行冷启动、热启动、强制停止和升级安装核验。这样就可以把风险限定在一个数据域内,不会同时进行转盘、历史和设置的全部行为。
二十四、工程核对清单
- [ ] 首选项初始化失败不会被首次安装。
- [ ]
JSON.parse()后的对象经过字段级运行时校验。 - [ ] WheelOption 的 id、text、color 与转盘备份逐层校验。
- [ ] ThemeMode 只接受 light、dark、auto。
- [ ] AppStorage 只保存可信运行时镜像。
- [ ] 保存成功提示发生在持久化提交确认之后。
- [ ] 多次写入经过串联,不丢失历史或转盘。
- [ ] 活动转盘ID与转盘列表始终一致。
- [ ] v1 到新版本的迁移可重复执行且能恢复。
- [ ] 损坏数据先隔离,再写默认值。
- [ ] 日志不输出用户自定义标题、选项和结果。
- [ ] 历史增长到需要查询和统计时迁移到RDB。
- [ ] 强制停止与重启后,转盘、历史、设置和活动事项均一致。
总结
“转盘决定吧”的持久化结构已经有了数据集:模型集中定义,PreferencesStore统一访问,WheelService、HistoryService、SettingsService管理业务,AppStorage状态数据集ArkUI。真正把是需要加强边界语义。
泛型断言不能替代运行时解码;初始化失败不能伪装成没有数据;AppStorage更新不能替代磁盘分配;带_v1的键名不能替代迁移流程。把这四点补齐后,三个预置转盘、用户自定义选项、500条历史和主题切换才能在冷启动、升级、异常数据和连续写入下保持一致。
参考文件与官方资料
entry/src/main/ets/model/Models.etsentry/src/main/ets/service/PreferencesStore.etsentry/src/main/ets/service/WheelService.etsentry/src/main/ets/service/HistoryService.etsentry/src/main/ets/service/SettingsService.etsentry/src/main/ets/entryability/EntryAbility.ets- 华为方舟数据简介
- 华为应用数据持久化概述
- 华为应用存储指南
更多推荐

所有评论(0)