HarmonyOs应用《重要日》开发第6篇 - 数据持久化存储

本篇深入剖析 ImportantDays 项目的数据持久化方案——基于 HarmonyOS ArkData 模块的 Preferences 轻量级存储，以及 PreferenceUtil 工具类的单例封装。

一、HarmonyOS 数据存储方案对比

HarmonyOS 提供了多种数据存储方案：

ImportantDays 选择 Preferences 的原因：

1. 数据量小（通常几十条重要日）
2. 数据结构简单（JSON 字符串）
3. 不需要复杂查询
4. 同步操作，代码简洁

二、PreferenceUtil 工具类

2.1 完整实现

// utils/PreferenceUtil.etsimport{preferences}from'@kit.ArkData';import{common}from'@kit.AbilityKit';import{Logger}from'./Logger';exportclassPreferenceUtil{privatestaticpreferenceRecord:Map<string,PreferenceUtil>=newMap();privatedataPreferences:preferences.Preferences|null=null;privateconstructor(context:Context,fileName:string){preferences.removePreferencesFromCacheSync(context,fileName);this.dataPreferences=preferences.getPreferencesSync(context,{name:fileName});Logger.info(`PreferenceUtil:${fileName}init:${this.dataPreferences!=null}`);}publicstaticgetInstance(context?:Context,fileName:string='default'):PreferenceUtil{if(PreferenceUtil.preferenceRecord.has(fileName)){returnPreferenceUtil.preferenceRecord.get(fileName)!;}constctx:Context=context||getContext()ascommon.UIAbilityContext;constpreferenceUtil:PreferenceUtil=newPreferenceUtil(ctx,fileName);PreferenceUtil.preferenceRecord.set(fileName,preferenceUtil);returnpreferenceUtil;}publicgetPreferences():preferences.Preferences|null{returnthis.dataPreferences;}publicput(key:string,value:object|string|number|boolean):void{if(!this.dataPreferences){Logger.info('PreferenceUtil: dataPreferences is null');return;}try{this.dataPreferences.putSync(key,value);this.dataPreferences.flushSync();Logger.info(`PreferenceUtil: put:${key}`);}catch(e){Logger.error(`PreferenceUtil: put error:${JSON.stringify(e)}`);}}publicget(key:string,defaultValue:object|string|number|boolean):object|string|number|boolean{if(!this.dataPreferences){returndefaultValue;}try{returnthis.dataPreferences.getSync(key,defaultValue)asobject|string|number|boolean;}catch(e){Logger.error(`PreferenceUtil: get error:${JSON.stringify(e)}`);returndefaultValue;}}publicdelete(key:string):void{if(!this.dataPreferences){return;}try{this.dataPreferences.deleteSync(key);this.dataPreferences.flushSync();Logger.info(`PreferenceUtil: delete:${key}`);}catch(e){Logger.error(`PreferenceUtil: delete error:${JSON.stringify(e)}`);}}}

2.2 设计要点

单例模式（按文件名区分）

privatestaticpreferenceRecord:Map<string,PreferenceUtil>=newMap();publicstaticgetInstance(context?:Context,fileName:string='default'):PreferenceUtil{if(PreferenceUtil.preferenceRecord.has(fileName)){returnPreferenceUtil.preferenceRecord.get(fileName)!;}// ...创建新实例}

使用Map按fileName维护多个实例，每个文件对应一个PreferenceUtil实例。

缓存清理

privateconstructor(context:Context,fileName:string){preferences.removePreferencesFromCacheSync(context,fileName);this.dataPreferences=preferences.getPreferencesSync(context,{name:fileName});}

在创建实例前先从缓存中移除，确保获取的是最新实例。这是处理开发热重载时缓存残留的关键。

同步 API

this.dataPreferences.putSync(key,value);this.dataPreferences.flushSync();

使用同步 API 而非异步，简化调用方代码。对于轻量级数据，同步操作的性能影响可以忽略。

容错处理

publicput(key:string,value:object|string|number|boolean):void{if(!this.dataPreferences){Logger.info('PreferenceUtil: dataPreferences is null');return;}try{this.dataPreferences.putSync(key,value);this.dataPreferences.flushSync();}catch(e){Logger.error(`PreferenceUtil: put error:${JSON.stringify(e)}`);}}

所有操作都包含 try-catch，确保存储异常不会导致应用崩溃。

三、在 MainViewModel 中使用

3.1 初始化

// viewmodel/MainViewModel.etspublicasyncinit(context:Context):Promise<void>{this.prefUtil=PreferenceUtil.getInstance(context,AppConstants.PREF_FILE);this.loadDays();}

常量定义：

// common/Constants.etsexportclassAppConstants{publicstaticreadonlyPREF_FILE:string='important_days';publicstaticreadonlyPREF_KEY_DAYS:string='important_day_list';}

3.2 加载数据

privateloadDays():void{if(!this.prefUtil)return;constjsonStr=this.prefUtil.get(AppConstants.PREF_KEY_DAYS,'[]')asstring;try{constarr:string[]=JSON.parse(jsonStr);this.dayList=arr.map((json:string)=>ImportantDay.fromJSON(json)).filter((day:ImportantDay|null)=>day!==null)asImportantDay[];}catch(e){Logger.error(`MainViewModel: loadDays error:${JSON.stringify(e)}`);this.dayList=[];}}

3.3 保存数据

privatesaveDays():void{if(!this.prefUtil)return;constarr:string[]=this.dayList.map((day:ImportantDay)=>day.toJSON());this.prefUtil.put(AppConstants.PREF_KEY_DAYS,JSON.stringify(arr));}

3.4 数据存储格式

Preferences 中存储的数据结构：

文件: important_days 键: important_day_list 值: '["{\"id\":\"1690000000000_3456\",\"title\":\"妈妈生日\",\"date\":\"2026-03-15\",\"description\":\"记得买蛋糕\",\"colorIndex\":5,\"countMode\":0,\"repeatType\":1,\"advanceDays\":3,\"isPinned\":true,\"createdAt\":1690000000000,\"updatedAt\":1690000000000}"]'

外层是一个 JSON 数组字符串，每个元素是ImportantDay.toJSON()的结果。这种嵌套设计的原因：

1. Preferences 的putSync只支持基本类型（string、number、boolean）和 string
2. 将数组序列化为字符串存储，可以一次性保存所有数据
3. 加载时一次性反序列化，减少 IO 操作

四、putSync 与 flushSync 的区别

this.dataPreferences.putSync(key,value);// 写入内存缓存this.dataPreferences.flushSync();// 持久化到文件

• putSync：将数据写入内存缓存，速度极快
• flushSync：将内存缓存的数据刷写到磁盘文件，确保数据持久化

两者必须配合使用。如果只调用putSync而不flushSync，数据在应用关闭后会丢失。

五、removePreferencesFromCacheSync 的作用

preferences.removePreferencesFromCacheSync(context,fileName);

这行代码在构造函数中调用，用于从内存缓存中移除指定文件的 Preferences 实例。这在以下场景中很重要：

1. 开发阶段热重载：DevEco Studio 热重载时，旧的 Preferences 实例可能还留在缓存中
2. 多实例场景：确保每次getInstance获取的是最新状态
3. 数据同步：防止缓存中的脏数据影响新实例

六、存储方案扩展思考

6.1 当前方案的局限

1. 全量保存：每次修改都保存整个列表，数据量大时可能有性能问题
2. 无索引：查询某日的重要日需要遍历整个列表
3. 无事务：多步操作不具备原子性

6.2 如果使用 RDB

如果未来数据量增长，可以迁移到关系型数据库：

CREATETABLEimportant_days(idTEXTPRIMARYKEY,titleTEXTNOTNULL,dateTEXTNOTNULL,descriptionTEXT,color_indexINTEGERDEFAULT0,count_modeINTEGERDEFAULT0,repeat_typeINTEGERDEFAULT0,advance_daysINTEGERDEFAULT0,is_pinnedINTEGERDEFAULT0,created_atINTEGER,updated_atINTEGER);CREATEINDEXidx_dateONimportant_days(date);CREATEINDEXidx_pinnedONimportant_days(is_pinned);

但当前 Preferences 方案对于这个应用规模完全够用，简单可靠。

七、小结

本篇详细介绍了 ImportantDays 项目的数据持久化方案。PreferenceUtil 通过单例模式封装 Preferences API，提供简洁的get/put/delete接口。MainViewModel 在每次 CRUD 操作后自动调用saveDays()持久化数据，确保数据不丢失。