HarmonyOS 应用数据持久化概述：Preferences、KV-Store、RelationalStore 到底怎么选？

更新时间：2025-12-11 11:47（结合我平时做 HarmonyOS 项目时的理解，整理成一篇"能直接拿去用"的笔记）

做应用迟早会遇到一个问题：数据放在内存里，一退出就没了 。

所以我们得把数据"落地"------这就是 数据持久化 ：把内存里的对象/结构，保存成文件、数据库、二进制等形式放到设备上，下次打开还能恢复。

鸿蒙开发者第四期活动

HarmonyOS 标准系统里，最典型、最常用的三种持久化形态就是：

用户首选项（Preferences）：存配置、小数据，读取很快
键值型数据库（KV-Store）：非关系型，键值对，适合业务关系不复杂、还想做分布式同步
关系型数据库（RelationalStore） ：表格形式（行/列），支持 SQL、复杂查询；还提供向量数据库能力（相似度检索）

下面我按"你到底该用哪个 + 怎么用 + 踩坑点"讲清楚。

1）Preferences：保存"配置项"的首选

适合什么场景？

一句话：只存配置，不存业务大数据。

常见例子：

是否开启深色模式
是否第一次启动（引导页开关）
上次登录账号（不建议存密码）
用户选择的语言、字体大小、开关项

它的特点（优缺点）

✅ 访问快、效率高 ：因为使用时会全量加载到内存
✅ 写法简单
❌ 不适合存大量数据：数据多了全量加载会拖慢、也不优雅
❌ 不适合复杂查询（它就是配置存储）

你怎么选？

如果你在纠结：

"这个东西是不是一堆开关/小配置？"

是的话就 Preferences。

伪代码示例（理解思路就行）

（你写博客可以用"思路式"代码，读者更容易懂）

复制代码

// 伪代码：保存一个开关配置
// set('darkMode', true)
// get('darkMode') -> true

2）KV-Store：键值型数据库（业务数据不复杂 + 想要分布式更友好）

适合什么场景？

一句话：数据之间关系不强，但属于业务数据，而且你可能会考虑分布式/跨设备。

常见例子：

购物车（key=商品id，value=数量/详情）
消息未读数（key=会话id，value=未读数）
用户草稿（key=草稿id，value=草稿内容）
一些结构化但不需要表关联的数据

它的特点（优缺点）

✅ 非关系型：key-value 组织，上手快
✅ 更容易做跨设备跨版本兼容（因为数据模型简单）
✅ 分布式场景里，能减少版本兼容/冲突处理复杂度
❌ 不擅长复杂关联查询（比如 join、多表统计）
❌ 如果你硬拿 KV 去做复杂数据结构，会越来越难维护

你怎么选？

如果你发现你要存的数据是这种形式：

"我只要通过一个 key 快速拿到对应 value"
"我不想写 SQL"
"后面可能要做多端数据同步"

那 KV-Store 很合适。

伪代码示例

复制代码

// key = "draft_1001"
// value = { title: "...", content: "...", updatedAt: 123456 }
put(key, value)
get(key)
delete(key)

3）RelationalStore：关系型数据库（最强、最常用的业务数据库）

适合什么场景？

一句话：只要你的数据能落到"表格（行/列）"，而且你要做查询/筛选/排序/统计，就用它。

常见例子：

订单、商品、用户、地址（典型业务数据）
学习计划、错题本、打卡记录
笔记、分类、标签（多对多关系）
任何需要"条件查询"的内容：按时间、按关键字、按类型筛选

它的特点（优缺点）

✅ 支持增删改查 + 自定义 SQL
✅ 适合复杂业务：索引、排序、分页、统计
✅ 数据结构清晰：长期维护更稳
❌ 学习成本稍高（表设计、字段、SQL 思维）
❌ 设计不好会导致后期改表麻烦（但这是所有关系库的通病）

重点：它还提供"向量数据库能力"

这个是很多人会忽略的点：RelationalStore 里还能做向量相似度计算，适合：

推荐（相似内容推荐）
相似图片检索
NLP 语义检索（比如"我搜这句话，找最像的笔记/文档"）

一句人话解释：

你可以把文本/图片变成向量（embedding），存进库里，然后用"相似度"去找最接近的内容。

4）到底怎么选？我给你一个"秒选表"

只存开关/配置/少量字段 → ✅ Preferences
key-value 结构，业务关系少，还可能分布式 → ✅ KV-Store
需要查询、筛选、排序、分页、统计、多表关系 → ✅ RelationalStore
要做语义检索/推荐/相似度 → ✅ RelationalStore（向量能力）

5）我自己项目里的"组合用法"（最实用）

真实开发里基本不会只用一种，通常是：

Preferences：放"设置项"（主题、引导页、用户偏好）
RelationalStore：放"核心业务数据"（订单/笔记/错题/计划）
KV-Store：放"轻量业务缓存/跨端同步更合适的数据"

这样逻辑清楚，后期也不容易乱。

6）最后一句话总结

Preferences = 配置存储
KV-Store = key-value 业务数据（分布式友好）
RelationalStore = 正经数据库（SQL + 复杂业务 + 向量检索）