3、单设备数据持久化：使用KVStore进行本地数据存储、数据模型设计、性能调优建议

好，咱们进入第三个实战环节。单设备数据持久化，说白了就是让数据在App退出后还能活着。在鸿蒙分布式架构里，这是最基础也是最关键的一步——本地都存不好，跨设备同步就是空中楼阁。

我个人习惯把KVStore看作一个“超级字典”。你想想看，字典就是key查value，KVStore也一样，但它比普通字典强在：数据能落地到磁盘、能跨进程访问、还能自动处理并发。嗯，咱们今天就把它彻底讲透。

3.1 KVStore的核心概念与选型

鸿蒙的KVStore分两种：单版本KVStore和多版本KVStore。我在项目中遇到过不少同学上来就选多版本，结果发现根本用不上，还白白增加了复杂度。

类型	特点	适用场景
单版本KVStore	每个key只保留最新值，覆盖写入	用户配置、缓存数据、状态标记
多版本KVStore	保留历史版本，支持冲突合并	跨设备同步、多人协作编辑

我的建议是：单设备场景，无脑选单版本。多版本是为分布式冲突准备的，本地用纯属杀鸡用牛刀。

3.2 数据模型设计：别把KVStore当关系数据库用

这是最容易踩坑的地方。KVStore不是SQLite，它没有表结构、没有索引、没有关联查询。你想想看，如果硬要把一个用户对象拆成十几个key，查询时还得拼回来，那还不如直接用数据库。

我总结了一套“三级key设计法”，在多个项目中验证过，效果不错：

• 一级key（命名空间）：比如 "user_"、"config_"、"cache_"
• 二级key（业务ID）：比如用户ID、设备ID
• 三级key（字段名）：比如 "name"、"avatar"、"theme"

举个例子，存储用户配置：

// 推荐：使用JSON序列化整个对象
let userConfig = {
    name: "张三",
    theme: "dark",
    fontSize: 16,
    notifications: true
};
await kvStore.put("config_user_123", JSON.stringify(userConfig));

// 不推荐：拆成多个key
await kvStore.put("config_user_123_name", "张三");
await kvStore.put("config_user_123_theme", "dark");
// ... 查询时还得拼回来，麻烦死了

3.3 实战：创建与读写KVStore

好，咱们直接上代码。创建一个KVStore实例，其实就三步：获取KvManager、配置选项、打开Store。

import distributedKVStore from '@ohos.data.distributedKVStore';

// 1. 获取KvManager
let kvManager = distributedKVStore.createKvManager({
    bundleName: "com.example.myapp",
    context: getContext()
});

// 2. 配置选项
let options = {
    createIfMissing: true,  // 不存在就创建
    encrypt: false,         // 单设备一般不用加密
    backup: false,          // 关闭自动备份，提升性能
    kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION
};

// 3. 打开Store
let kvStore = await kvManager.getKVStore("my_store", options);

// 写入
await kvStore.put("user_name", "李四");
await kvStore.put("user_age", "28");  // 注意：value必须是string

// 读取
let name = await kvStore.get("user_name");
console.info("name: " + name);

// 删除
await kvStore.delete("user_age");

// 清空
await kvStore.clear();

3.4 性能调优：让KVStore跑得更快

说实话，KVStore在单设备场景下性能已经很好了。但如果你要存几千条数据，或者频繁读写，还是有一些优化空间的。我把自己压箱底的经验分享出来：

3.4.1 批量操作代替单条操作

每次put/get都是一次IPC调用，频繁操作时开销很大。用批量接口能减少调用次数：

// 不推荐：循环单条写入
for (let i = 0; i < 1000; i++) {
    await kvStore.put("key_" + i, "value_" + i);
}

// 推荐：批量写入
let entries = [];
for (let i = 0; i < 1000; i++) {
    entries.push({
        key: "key_" + i,
        value: { type: distributedKVStore.ValueType.STRING, value: "value_" + i }
    });
}
await kvStore.putBatch(entries);

3.4.2 合理设置同步模式

KVStore支持两种同步模式：自动同步和手动同步。单设备场景下，建议关闭自动同步：

let options = {
    // ... 其他配置
    autoSync: false,  // 关闭自动同步，减少不必要的IO
    syncMode: distributedKVStore.SyncMode.PULL_ONLY  // 单设备不需要推送
};

3.4.3 控制数据量

KVStore不是为大数据量设计的。我的经验是：

• 单个Store的key数量控制在 1万以内
• 单个value大小控制在 100KB以内
• 总数据量不要超过 50MB

超过这个量，建议改用关系型数据库（比如RDB）或者文件存储。

3.4.4 善用订阅机制

如果你需要监听数据变化，别用轮询。KVStore提供了数据变更订阅：

// 订阅数据变化
kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data) => {
    console.info("数据变了: " + JSON.stringify(data));
});

// 记得在不用时取消订阅
kvStore.off('dataChange');

3.5 数据备份与恢复

单设备数据持久化，备份是必须考虑的。鸿蒙提供了内置的备份机制，但我建议自己实现一套轻量方案：

// 导出所有数据
async function backupKVStore(kvStore) {
    let allEntries = await kvStore.getEntries("");  // 获取所有条目
    let backupData = {};
    for (let entry of allEntries) {
        backupData[entry.key] = entry.value.value;
    }
    // 写入文件或上传云端
    await writeToFile("backup.json", JSON.stringify(backupData));
}

// 恢复数据
async function restoreKVStore(kvStore) {
    let backupStr = await readFromFile("backup.json");
    let backupData = JSON.parse(backupStr);
    let entries = Object.keys(backupData).map(key => ({
        key: key,
        value: { type: distributedKVStore.ValueType.STRING, value: backupData[key] }
    }));
    await kvStore.putBatch(entries);
}

3.6 总结：记住这三条

好了，单设备KVStore的内容就这些。我帮你提炼三条核心原则：

1. 设计先行：先想好key的命名规则，别写到一半再改
2. 批量优先：能批量就别单条，能订阅就别轮询
3. 量力而行：KVStore不是万能的，数据量大就换数据库

下一章咱们会讲跨设备数据同步，到时候你会发现，今天这些本地存储的经验，全是分布式的基础。嗯，打好地基，才能盖高楼。