一个转盘应用的数据看起来并不复杂:转盘有标题和选项,旋转后产生一条历史,设置页面保存主题、声音与振动开关。真正容易出问题的位置,不是字段数量,而是这些对象要同时经过 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

模型与持久化封面

本文要回答五个具体问题:

  1. Wheel、WheelOption、HistoryRecord各自AppSettings承担什么数据契约。
  2. 为什么JSON.parse(raw) as T只让编译器接受结果,却不能得出磁盘数据确实符合T。
  3. Preferences 与 AppStorage 要分工,而不能互相替代。
  4. 内存先更新、磁盘后提交时,失败和装载写入会造成什么状态差异。
  5. 带上_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 链路的是转盘、历史和设置三组对象。

模型关键字段生命周期当前持久化位置
WheelOptionid、text、color跟随所属转盘wheels_v1 的嵌套数组
Wheelid、title、options、createdAt、updatedAt长期业务数据wheels_v1
HistoryRecordid、type、title、result、timestamp最多保留 500 条history_records_v1
AppSettingstheme、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,却没有迁移入口。

一个安全迁移流程应包含:

  1. 优先读取新键;新键有效就直接使用。
  2. 新键不存在时读取旧键,并用旧版本解码器恢复。
  3. 转换为新 DTO,写入新键并 flush()。
  4. 重新读取新键确认数量与关键 ID。
  5. 最后再删除旧键,或保留一个版本周期用于回滚。

迁移必须幂等。应用在第 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。然后执行以下真机路径:

  1. 首次安装启动,确认生成3个预置转盘,活动ID指向第一个。
  2. 新建一个转盘,修改标题和颜色,返回后立即可以看到新值。
  3. 强制停止进程后重新启动,新转盘、活动项和设置均恢复。
  4. 连续产生3条不同类型历史,重启后顺序保持“新到旧”。
  5. 删除当前活动转盘,重新启动后活动 ID 恢复到仍存在的第一个。
  6. 切换主题、声音、振动,逐项重启确认,不把字符串误当布尔值。
  7. 模拟无效主题和缺字段旧数据,确认解码后回落默认值。
  8. 模拟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 和异常映射,业务服务用可替换接口调用它,测试时可注入内存实现并主动制造提交失败。

二十三、落地顺序

对当前工程,改造不需要一次更换掉所有存储。可以按风险递增分四步:

  1. 首先让首选项初始化失败向上暴露,根页面增加加载与错误状态。
  2. 给 ThemeMode、Wheel、WheelOption、HistoryRecord 增加运行时解码。
  3. 统一活动ID修复、串行化和提交失败反馈。
  4. 为键增加正式迁移函数;历史查询需求增长时迁至RDB。

每一步都应先写一个边界,再修改实现,最后执行冷启动、热启动、强制停止和升级安装核验。这样就可以把风险限定在一个数据域内,不会同时进行转盘、历史和设置的全部行为。

二十四、工程核对清单

  • [ ] 首选项初始化失败不会被首次安装。
  • [ ]JSON.parse()后的对象经过字段级运行时校验。
  • [ ] WheelOption 的 id、text、color 与转盘备份逐层校验。
  • [ ] ThemeMode 只接受 light、dark、auto。
  • [ ] AppStorage 只保存可信运行时镜像。
  • [ ] 保存成功提示发生在持久化提交确认之后。
  • [ ] 多次写入经过串联,不丢失历史或转盘。
  • [ ] 活动转盘ID与转盘列表始终一致。
  • [ ] v1 到新版本的迁移可重复执行且能恢复。
  • [ ] 损坏数据先隔离,再写默认值。
  • [ ] 日志不输出用户自定义标题、选项和结果。
  • [ ] 历史增长到需要查询和统计时迁移到RDB。
  • [ ] 强制停止与重启后,转盘、历史、设置和活动事项均一致。

总结

“转盘决定吧”的持久化结构已经有了数据集:模型集中定义,PreferencesStore统一访问,WheelService、HistoryService、SettingsService管理业务,AppStorage状态数据集ArkUI。真正把是需要加强边界语义。

泛型断言不能替代运行时解码;初始化失败不能伪装成没有数据;AppStorage更新不能替代磁盘分配;带_v1的键名不能替代迁移流程。把这四点补齐后,三个预置转盘、用户自定义选项、500条历史和主题切换才能在冷启动、升级、异常数据和连续写入下保持一致。

参考文件与官方资料

Logo

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

更多推荐