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') -> true2）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 + 复杂业务 + 向量检索）
)