【共创稿事节】HarmonyOS7 元服务【拼词小达人】的 preferences 双表存储与全量序列化
学习数据存得很朴素:一张 preferences 表,六个键,其中两个键里塞的是整个 JSON 字符串 —— 所有词的学习记录序列化成一个数组,所有历史记录序列化成另一个数组。每次翻卡都重写一次完整的统计数组,这在 4423 个词的规模上是个明确的取舍:写入量随学习量线性增长,换来的是不需要为单条记录设计键名,也不需要处理「某个键写坏了但别的还好」这种部分失败。
单表六个键
表名 en_ordmester,键名集中在一个类里:
export class PrefKeys {
static readonly SELECTED_VERSION_CODE: string = 'selected_version_code';
static readonly SELECTED_GRADE_KEY: string = 'selected_grade_key';
static readonly SELECTED_GRADE_NAME: string = 'selected_grade_name';
static readonly FIRST_USE_DATE: string = 'first_use_date';
static readonly WORD_STATS: string = 'word_stats';
static readonly HISTORY: string = 'history_entries';
}
六个键分两类,形态完全不同:
| 键 | 值类型 | 形态 | 谁写 |
|---|---|---|---|
selected_version_code | string | 单值,如 pep | saveSelectedGrade |
selected_grade_key | string | 单值,如 grade_3_up | saveSelectedGrade |
selected_grade_name | string | 单值,如 三年级上册 | saveSelectedGrade |
first_use_date | number | 毫秒时间戳 | ensureFirstUseDate |
word_stats | string | JSON 数组,每项是一个 UserWordStat | saveStats |
history_entries | string | JSON 数组,上限 200 项 | saveHistory |
前四个是标量,读写都简单。后两个是「把数组当字符串存」,这是这套设计的核心:preferences 的 value 支持 number、string、boolean、Array<number>、Array<string>、Array<boolean>、Uint8Array、object,但没有「对象数组」这一档。要用键值对存一张表,可选做法是按 wordId 派生键名(stat_${wordId}),或者整表序列化成一个字符串。这里选了后者。
选它的直接好处是原子性。整表要么全写进去,要么这次调用失败、上一次的内容原样保留;派生键名的做法会变成「N 个键各写一次」,中间失败就留下一半新一半旧。另一个好处是不需要维护键的清单 —— 清空数据只需写两次 '[]',不用遍历删键。
代价是每次改动都要重写全表。
全量序列化
saveStats 是唯一的写入函数:
private async saveStats(): Promise<void> {
const arr: UserWordStat[] = [];
this.statsMap.forEach((stat: UserWordStat) => {
arr.push(stat);
});
const json: string = JSON.stringify(arr);
await this.pref?.put(PrefKeys.WORD_STATS, json);
await this.pref?.flush();
}
Map 转数组再序列化,两步都是全量。序列化出来的每一项长这样:
{"wordId":"pep_grade_3_up_1_0","readCount":3,"lastReadTime":1750492800000,"mastered":false,"collected":false}
一条约 100 字节。写入量的上限不是词库的 4423,而是 statsMap 的实际条目数 —— 只有被 recordRead、toggleCollected、toggleMastered 碰过的词才会进这个 Map:
| 触发方式 | 何时发生 | 产生的条目 |
|---|---|---|
recordRead | CardLearnPage 每翻一张卡、aboutToAppear、onFinish | readCount 从 0 起 |
toggleCollected | 点收藏按钮,词此前不存在 | collected: true,其余零值 |
toggleMastered | 点记住了按钮,词此前不存在 | mastered: true,其余零值 |
三个方法在词不存在时都会补一条新记录,所以「先收藏再读」和「先读再收藏」最终都落到同一条上 —— 差别只在于 collected 与 readCount 的初始值。这是 Map<string, UserWordStat> 按 wordId 去重的结果:一个词在表里永远只有一条。
flush() 紧跟 put() 之后。put 只更新内存中的副本,flush 才落盘。两个都 await,因为调用方需要知道「已经落盘了」这件事 —— 尤其是 clearAllStats 之后紧接着跳转页面,如果不保证落盘,跳到年级选择页时数据可能还在内存里没写出去。
saveHistory 结构一样,只是没有 Map 转换:
private async saveHistory(): Promise<void> {
const json: string = JSON.stringify(this.historyList);
await this.pref?.put(PrefKeys.HISTORY, json);
await this.pref?.flush();
}
this.pref?. 的 ?. 不是随手写的。pref 的类型是 preferences.Preferences | null,在 init 完成前是 null。三个写入方法都是 async,理论上可以在 init 之前被调用 —— 那时 ?. 让整句变成空操作,不抛异常也不写任何东西,方法正常返回。这是一种「静默降级」:调用方不会收到错误,但数据也没进去。页面侧不会遇到这种情况,因为 EntryAbility 把 init 挡在前面;卡片进程走 FormAbility.initData,也有 isInitialized() 在前面。
读回时的两级校验
读取分两层:先按类型读出,再解析 JSON。第一层是两个小工具函数:
private async getString(key: string, defaultValue: string): Promise<string> {
if (!this.pref) {
return defaultValue;
}
const raw = await this.pref.get(key, defaultValue);
if (typeof raw === 'string') {
return raw;
}
return defaultValue;
}
private async getNumber(key: string, defaultValue: number): Promise<number> {
if (!this.pref) {
return defaultValue;
}
const raw = await this.pref.get(key, defaultValue);
if (typeof raw === 'number') {
return raw;
}
return defaultValue;
}
pref.get() 的返回类型是 preferences.ValueType,一个联合类型。直接 as string 也能过编译,但运行时会拿到 undefined 或数字,后面拼字符串就会出现 undefined 字样。typeof 检查把「键被别处写成了别的类型」这种情况也接住了 —— 比如某次版本迭代把 first_use_date 从字符串改成数字,老数据读出来是字符串,getNumber 会返回默认值 0 而不是把它硬转成 NaN。
第二层是 JSON.parse,包在 try/catch 里:
private async loadStats(): Promise<void> {
const json: string = await this.getString(PrefKeys.WORD_STATS, '[]');
try {
const rawStats = JSON.parse(json) as UserWordStat[];
if (Array.isArray(rawStats)) {
for (const stat of rawStats) {
this.statsMap.set(stat.wordId, stat);
}
}
} catch (e) {
this.statsMap.clear();
}
}
三层防护叠在一起。getString 的默认值 '[]' 保证键不存在时拿到的是合法 JSON;Array.isArray 挡住「值是合法 JSON 但不是一个数组」(比如被写成 '{}');catch 挡住「值不是 JSON」(比如被写成空串或被截断)。三种情况的结果不同:前两种会走正常流程并得到一个空表,第三种清空 statsMap。
loadHistory 完全对称:
private async loadHistory(): Promise<void> {
const json: string = await this.getString(PrefKeys.HISTORY, '[]');
try {
const rawHistory = JSON.parse(json) as HistoryEntry[];
if (Array.isArray(rawHistory)) {
this.historyList = rawHistory;
}
} catch (e) {
this.historyList = [];
}
}
loadHistory 用整体赋值而不是逐条 push,因为 historyList 是个数组不是 Map,直接换引用最简单。loadStats 必须逐条 set,因为要从 stat.wordId 里取出键。
JSON.parse 出来的对象是普通对象,as UserWordStat[] 只是编译期断言,运行时没有校验字段。所以一份手工改坏的数据(少一个 readCount)能顺利进 statsMap,然后 stat.readCount > 0 得到 false(undefined > 0),这一条就被算成「未学」。这类脏数据不会让程序崩,只会让某个统计数字偏低。
三个清空操作
三个清空方法的实现各不相同,差别在于「清什么」和「走哪条写入路径」。
clearHistory 最直接:
async clearHistory(): Promise<void> {
this.historyList = [];
await this.pref?.put(PrefKeys.HISTORY, '[]');
await this.pref?.flush();
this.notifyStatsChange();
}
没有调 saveHistory(),而是直接把字面量 '[]' 写进去。两种做法结果完全一样(JSON.stringify([]) 就是 '[]'),省掉的是一次 Map 转换和一次序列化。notifyStatsChange() 也要调 —— 历史页绑的是 statsVersion,不递增就不会重新分组。
clearFavorites 保留 statsMap 的条目,只把 collected 置 false:

图:批量清空收藏前的确认交互。
async clearFavorites(): Promise<void> {
this.statsMap.forEach((stat: UserWordStat) => {
stat.collected = false;
});
await this.saveStats();
this.notifyStatsChange();
}
这里 await 了 saveStats()。对比 toggleCollected 里的调用:
toggleCollected(wordId: string): boolean {
const existing: UserWordStat | undefined = this.statsMap.get(wordId);
let newCollected: boolean;
if (existing) {
existing.collected = !existing.collected;
newCollected = existing.collected;
} else {
const stat: UserWordStat = {
wordId: wordId,
readCount: 0,
lastReadTime: 0,
mastered: false,
collected: true
};
this.statsMap.set(wordId, stat);
newCollected = true;
}
this.saveStats();
this.notifyStatsChange();
return newCollected;
}
saveStats() 前面没有 await,toggleCollected 也不是 async。写盘是后台进行的,调用方立刻拿到新的布尔值用于更新按钮状态。这对点击按钮没问题 —— 用户不等落盘,UI 已经变了。但如果用户点完收藏立刻杀进程,最后那次写可能没完成。
clearFavorites 必须 await,因为它是「批量操作 + 立刻跳转/刷新」的组合:MinePage 的确认对话框里写了 .then(() => this.refreshStats()),如果不 wait 到落盘完成,refreshStats 读到的是内存(已正确),但页面重进时可能拿到旧数据。两种调用的差异不是风格问题,而是「调用方是否依赖写盘已完成」。
clearAllStats 是所有键一起归零:

图:清空全部学习数据前的确认交互。
async clearAllStats(): Promise<void> {
this.statsMap.clear();
this.historyList = [];
await this.pref?.put(PrefKeys.WORD_STATS, '[]');
await this.pref?.put(PrefKeys.HISTORY, '[]');
await this.pref?.put(PrefKeys.SELECTED_VERSION_CODE, '');
await this.pref?.put(PrefKeys.SELECTED_GRADE_KEY, '');
await this.pref?.put(PrefKeys.SELECTED_GRADE_NAME, '');
await this.pref?.put(PrefKeys.FIRST_USE_DATE, 0);
await this.pref?.flush();
AppStorage.setOrCreate(StoreKeys.VERSION_CODE, '');
AppStorage.setOrCreate(StoreKeys.GRADE_KEY, '');
AppStorage.setOrCreate(StoreKeys.GRADE_NAME, '');
AppStorage.setOrCreate(StoreKeys.FIRST_USE_DATE, 0);
this.notifyStatsChange();
}
六个 put 之后只有一次 flush。put 改的是内存副本,一次 flush 把这批改动一起落盘,比每个键后各来一次 flush 少五次 IO。AppStorage 侧只重置四个「选择类」键,三个计数交给 notifyStatsChange 重算(此时 statsMap 已空,算出来都是 0)。statsVersion 不重置 —— 它是单调递增的信号量,重置回 0 会让所有页面的 @Watch 误判成「值变小了但还是一次变化」,语义上没必要。
AppStorage 与 preferences 在这段代码里是两套独立的状态,必须手动保持一致。六次 put 之后紧接着四次 setOrCreate,两组一一对应(除了 WORD_STATS / HISTORY 没有对应的 AppStorage 键)。
历史记录的截断与去重
addHistory 是唯一在业务层做数据结构维护的方法:
addHistory(wordId: string): void {
const now: number = Date.now();
const existing: HistoryEntry | undefined = this.historyList.find((entry: HistoryEntry) => entry.wordId === wordId);
if (existing) {
existing.timestamp = now;
this.historyList = this.historyList.filter((entry: HistoryEntry) => entry.wordId !== wordId);
const newEntry: HistoryEntry = { wordId: wordId, timestamp: now };
this.historyList.unshift(newEntry);
} else {
const newEntry: HistoryEntry = { wordId: wordId, timestamp: now };
this.historyList.unshift(newEntry);
}
if (this.historyList.length > 200) {
this.historyList = this.historyList.slice(0, 200);
}
this.saveHistory();
this.notifyStatsChange();
}
historyList 的契约是「按时间倒序、每个词只出现一次」。达成方式是三步:先 find 判断是否已存在,存在则改 timestamp 再用 filter 把它摘掉,最后无论新旧都 unshift 到头部。existing.timestamp = now 这一步其实不影响结果 —— 紧接着 filter 就把这个对象从数组里剔了,新 unshift 的是一个新对象。它存在的意义只在于「如果 filter 之后没有 unshift,时间戳也已经更新」,属于防御性写法。
200 是硬上限,slice(0, 200) 从头部截。截断发生在 unshift 之后,所以刚进的词一定在保留范围内,被丢掉的是最老的那条。
saveHistory() 与 notifyStatsChange() 都没有 await。历史页靠 statsVersion 刷新,读的是内存里的 historyList,与落盘无关 —— 只要内存对了,页面就对了。CardLearnPage 里 recordRead 和 addHistory 是连着调的两个同步方法:
private recordCurrentRead(): void {
if (this.currentIndex >= 0 && this.currentIndex < this.words.length) {
const word = this.words[this.currentIndex];
const storage = StorageService.getInstance();
storage.recordRead(word.id);
storage.addHistory(word.id);
}
}
一次翻卡会触发两次全量写:saveStats 写整个统计表,saveHistory 写整个历史表,各自带一次 flush。单单元 72 词学完就是 72 次翻页 × 2 次写盘。这个频率下没做合并,因为合并需要引入延迟写入和脏标记,而现有的写入量(几十 KB)在闪存上耗时可忽略。
getHistory() 返回的是内部数组的引用,不是拷贝:
getHistory(): HistoryEntry[] {
return this.historyList;
}
返回的是内部数组的引用,不是拷贝。FormAbility 拿它遍历反推候选词,HistoryPage 拿它分组,两处都只读不写。但类型上它是可写的 —— 任何调用方 push 一个元素都不会触发落盘,也不会递增 statsVersion,造成内存与盘上数据不一致。要防住这一点得返回 [...this.historyList],代价是每次调用复制 200 个对象。这里选了不防,靠调用方自律。
为什么不用文件
词库用的是 getRawFileContent 读文件,学习数据用的是 preferences,两套不同的存储。区别在于读写模式:
| 维度 | preferences | fileIo 写 JSON |
|---|---|---|
| 当前用法 | 六个键,整表序列化成字符串 | 单个 JSON 文件 |
| 写入方式 | put + flush | 打开、写入、关闭 |
| 原子性 | 由框架保证单键 | 需要自己写临时文件再重命名 |
| 读取方式 | await get(key) | 读全量字节再解码 |
| 适合的规模 | 单值小、整体不大 | 大文件、流式读写 |
这个项目的数据量级是「几百条记录、几十 KB」,preferences 的 get / put 直接对上了需求,不需要自己处理文件句柄、编码、临时文件、重命名这几步。词库是 950KB 的只读资源,性质完全不同,用 rawfile 才是对的。
如果学习记录涨到上万条,全量序列化的成本会变得显眼:一次翻页要序列化上万条记录、写几十万字节。那时该换成「按 wordId 分文件」或者干脆迁到关系型存储,用 UPDATE 只改一行。现在这个体量,全量写是对的 —— 它把「一致性」这件事交给了「一次 put」这个原子操作,代码里不需要任何事务逻辑。
数据层的全貌就是这些:一张表、六个键、两处 JSON 序列化、三个清空入口、一套读写各两步的校验。上层看到的是一堆同步的 getXxxCount() 和 isXxx(wordId),异步只出现在初始化和清空这两类操作上。
更多推荐
所有评论(0)