一、我们要做什么

我们要构建一个"跨设备待办清单"应用。用户在手机上新建的待办，能实时同步到平板、智慧屏；应用的主题、字号等偏好设置需要长期保存；待办条目本身数量可能上千条，需要支持按状态筛选、按时间排序、模糊搜索。这三类数据的特征截然不同，因此不能用一种存储方案"一把梭"。

1.1 数据持久化需求表

数据类型	典型示例	数据量级	结构化程度	是否需跨设备	读写频率
应用偏好	主题色、字号、排序方式、是否首次启动	几十个键	键值对	否（本机）	读多写少
业务数据	待办条目（标题、内容、截止时间、优先级、状态）	数百至数千条	强结构化	是	频繁增删改查
会话状态	当前选中的分类、临时草稿	极少	简单值	部分	高频读写
跨端共享	待办完成状态、勾选进度	中等	半结构化	是（强）	实时同步

1.2 预期效果

• 偏好即时生效且持久：用户切换深色模式后，杀掉进程重启仍然保持；
• 业务数据高效检索：即便 3000 条待办，筛选"未完成 + 高优先级"仍能在毫秒级返回；
• 多端无感同步：手机勾选完成，平板 1 秒内自动打勾，无需手动刷新；
• UI 状态自动落盘：无需手写读写代码，@StorageProp 绑定的变量自动持久化；
• 离线可用：无网环境下仍可正常增删改查，联网后自动补同步，用户全程无感。

这些效果背后对应的正是 ArkData 三大能力的分工：Preferences 支撑偏好的即时与持久，RDB 支撑业务数据的高效检索，分布式能力支撑多端同步与离线可用。下文将逐一拆解实现。

1.3 核心挑战

1. 选型困境：Preferences、RDB、KVStore 各有边界，用错会导致性能或一致性问题；
2. 异步编程复杂度：ArkData 的绝大多数 API 是 Promise/callback 异步的，稍不注意就会出现"读到旧值"；
3. 分布式一致性：多端并发修改同一条数据，如何解决冲突（Last-Write-Wins 还是自定义合并）；
4. 数据迁移与版本升级：RDB 表结构随版本演进，如何平滑升级 schema 而不丢数据；
5. 安全与隐私：敏感字段是否需要加密存储，分布式同步的数据在设备间如何保证安全；
6. 主线程阻塞：数据库 IO 是磁盘操作，若在 UI 主线程同步执行会直接导致卡顿与丢帧，必须异步化。

这五大挑战贯穿整个开发过程，后文的每一个设计决策与代码实现，本质上都是在回应这些挑战。理解了挑战，才能看懂为什么要这样选型、这样写代码。

1.4 为什么不能"一把梭"

很多初学者会试图把所有数据都塞进一种存储：要么全用 Preferences（因为 API 最简单），要么全用 RDB（因为最"专业"）。这两种极端都会付出代价。

若把上千条待办塞进 Preferences，每条都是一个 JSON 字符串 key，那么一次"筛选未完成"就得把所有 key 全读进内存再逐条 JSON.parse 过滤，既慢又耗内存，且完全用不上索引；反之，若把"是否深色模式"这种单一开关也建一张 RDB 表，则为了读一个布尔值要走一次 SQL 查询、开一个 ResultSet，属于杀鸡用牛刀，还徒增异步复杂度。

正确的思路是按数据特征匹配存储能力：结构简单、量小、读多写少的配置交给 Preferences；结构化、需检索的业务数据交给 RDB；需要实时多端一致的小状态交给分布式 KVStore。这也是 ArkData 把三种能力并列提供、而非合并成一个"万能存储"的根本原因——存储没有银弹，只有权衡。

---

二、数据模型设计

好的持久化从清晰的数据模型开始。我们先用 TypeScript interface 把实体、存储 schema 以及各存储层的键约定固化下来，作为全项目的"契约"。

2.1 业务实体模型

// model/TodoModel.ets
// 优先级枚举
export enum Priority {
  LOW = 0,
  MEDIUM = 1,
  HIGH = 2
}

// 待办实体（对应 RDB 表 todo 的一行）
export interface Todo {
  id: number;            // 主键，自增
  title: string;         // 标题
  content: string;       // 详情
  priority: Priority;    // 优先级
  done: boolean;         // 是否完成
  dueTime: number;       // 截止时间戳（ms）
  createdAt: number;     // 创建时间戳
  updatedAt: number;     // 最近修改时间戳（用于分布式冲突解决）
}

// 应用偏好（对应 Preferences 的键值集合）
export interface AppSettings {
  darkMode: boolean;     // 深色模式
  fontSize: number;      // 字号
  sortBy: 'time' | 'priority';  // 排序方式
  firstLaunch: boolean;  // 是否首次启动
}

2.2 存储 schema 约定

将不同存储介质的键名、表名统一集中管理，避免"魔法字符串"散落各处：

// model/StorageSchema.ets
export const RDB_CONFIG = {
  name: 'TodoApp.db',        // 数据库文件名
  securityLevel: 3           // S3 安全等级
};

export const TABLE_TODO = 'todo';

// RDB 建表 SQL：包含索引以加速筛选
export const SQL_CREATE_TODO = `
CREATE TABLE IF NOT EXISTS todo (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  content TEXT,
  priority INTEGER DEFAULT 1,
  done INTEGER DEFAULT 0,
  dueTime INTEGER,
  createdAt INTEGER,
  updatedAt INTEGER
);`;

// 常用查询字段索引
export const SQL_INDEX_DONE =
  'CREATE INDEX IF NOT EXISTS idx_done ON todo(done, priority);';

// Preferences 文件名与键
export const PREF_NAME = 'app_settings';
export const PREF_KEYS = {
  DARK_MODE: 'darkMode',
  FONT_SIZE: 'fontSize',
  SORT_BY: 'sortBy',
  FIRST_LAUNCH: 'firstLaunch'
};

// 分布式 KVStore 的 storeId
export const KV_STORE_ID = 'todo_sync_store';

2.3 模型设计要点

• updatedAt 字段是分布式冲突解决的关键：多端修改时，比较该时间戳决定谁"胜出"；
• 布尔值在 RDB 中以 INTEGER（0/1）存储：SQLite 没有原生布尔类型；
• 索引不是越多越好：为高频查询列建复合索引 (done, priority)，写入时会有额外维护成本，需权衡；
• 时间戳统一用毫秒：createdAt、updatedAt、dueTime 均以毫秒时间戳（Date.now()）存储，既便于排序与区间查询，也避免了字符串日期格式不统一带来的比较错误；
• enum 而非魔法数字：优先级用 Priority 枚举而非直接写 0/1/2，提升可读性与类型安全；
• schema 版本号：建议在 Preferences 或数据库 user_version 中记录 schema 版本，为后续迁移做准备。
• 字段尽量稿扣可空与默认值：为 priority、done 等字段设定合理的 DEFAULT，能避免写入时遗漏字段导致的 NULL 异常，也为后续 ALTER 加列提供平滑兼容。

2.4 为什么要先定义接口再写存储

ArkTS 是强类型语言，先把实体、枚举、键名约定固化为类型，能在编译期就拦截大量错误：拼错键名、存错类型、漏字段都会在 IDE 里标红，而不是等到运行时才发现数据读不出来。把 SQL_CREATE_TODO、PREF_KEYS、KV_STORE_ID 集中到 StorageSchema.ets 一个文件，还能避免魔法字符串散落各处——当你要改表名或加字段时，只需改一处，避免了“改了建表 SQL 却忘了改查询列名”这类隐匿 bug。这是工程化持久化的第一步。

---

三、核心设计决策

面对三套存储能力，选型必须有据可依。下面从多维度对比，再给出本项目的落地方案。

3.1 三大存储方案横向对比

维度	Preferences	RDB（RelationalStore）	分布式 KVStore
数据模型	Key-Value	关系表（SQL）	Key-Value（分布式）
适用数据量	< 一万条键	大量结构化数据	中小量共享数据
查询能力	仅按键取值	完整 SQL、索引、事务	按键 / 前缀查询
是否支持跨设备	否	支持（分布式 RDB）	原生支持
一致性模型	本地强一致	本地 ACID 事务	最终一致（可选强一致）
典型场景	配置/开关/小状态	业务列表/复杂检索	跨端状态/共享文档
性能特点	内存缓存，极快	磁盘 + 索引，可控	网络同步有延迟

从这张表可以提炼出一个简单的选型直觉：只需“取一个值”用 Preferences，需要“查一批数据”用 RDB，需要“多端实时一致”用 KVStore。当一个需求同时命中多项（比如既要复杂查询又要多端同步），就应组合使用多种能力，而非勉强用一种去硬碰。需要强调的是，三者不是竞争关系而是互补关系，真实项目中它们往往同时存在。

3.2 应用级存储：PersistentStorage vs AppStorage vs LocalStorage

能力	AppStorage	PersistentStorage	LocalStorage
生命周期	应用进程内全局	持久化到磁盘	页面/UIAbility 级
是否落盘	否（内存）	是	否
绑定装饰器	@StorageLink / @StorageProp	依附于 AppStorage	@LocalStorageLink
适用场景	全局共享状态	需重启保留的轻量状态	局部 UI 状态

PersistentStorage 并非独立存储，而是给 AppStorage 中的指定 key 加上"自动落盘"能力。它底层其实用的就是 Preferences，因此只适合存少量简单类型（string/number/boolean）。

这三者的关系可以这样理解：LocalStorage 是“页面局部的共享状态”，AppStorage 是“全应用内存级的全局状态”，PersistentStorage 则是给 AppStorage 提供“重启不丢”的持久化属性。三者配合，可让开发者在 UI 层以声明式方式管理状态，无需手写任何读写磁盘的代码，极大简化了“配置类”数据的持久化负担。

3.3 本项目的选型结论

• 应用偏好（主题、字号） → Preferences，并对 UI 高频用到的项用 PersistentStorage + AppStorage 桥接，实现"绑定即持久"；
• 待办业务数据 → RDB（RelationalStore），利用 SQL 与索引支撑筛选、排序、搜索；
• 跨设备同步的完成状态 → 采用 分布式 KVStore（也可用分布式 RDB，本项目为演示同步机制选 KVStore），以 todoId 为 key、完成状态与 updatedAt 为 value；
• 冲突解决策略：默认 Last-Write-Wins，以 updatedAt 较大者为准，避免复杂合并逻辑。

需要提醒的是，“本地 vs 云端”也是一道重要选择。本文聚焦本地与分布式（可信设备间）同步；若需跨账号、跨网络、需长期备份，则应引入云数据库。本地方案延迟低、隐私好、无服务器成本，但受限于“同账号可信设备”范围；云端方案能突破设备限制并提供持久备份，但引入了网络依赖与服务端成本。本项目定位个人多设备协同，故采用本地 + 分布式方案，将云同步作为后续扩展。

选型理由：偏好数据结构简单、量小、只在本机用，Preferences 内存缓存读取零延迟；业务数据需要复杂查询，只有 SQL 关系库能优雅胜任；而勾选状态这种需要实时多端同步的小数据，KVStore 的最终一致同步机制最贴合，且开发成本远低于自己搭一套同步协议。

3.4 分布式 RDB vs 分布式 KVStore 如何取舍

有读者会问：既然 RDB 也支持分布式（通过 setDistributedTables 把表设为分布式表），为什么同步状态不直接用分布式 RDB？两者的差异在于：

• 分布式 RDB 适合结构化数据的整表同步，比如把整张待办表同步到平板，跨设备还能用 SQL 查询远端数据（predicates.inDevices(...)）。它的优势是保留了关系模型与查询能力，但同步粒度较粗、配置略重；
• 分布式 KVStore 适合细粒度、高频、小体积的状态同步，比如单条待办的完成状态。它以 key 为单位增量同步，延迟低、开销小。

本项目"勾选状态"正是典型的高频小状态，用 KVStore 增量同步单个 key 比同步整张表更高效，因此选 KVStore。若业务需要跨设备对整张业务表做 SQL 查询，则应改用分布式 RDB。二者并非互斥，成熟应用常常组合使用：业务主体用分布式 RDB，实时轻状态用 KVStore。

3.5 一致性与可用性的取舍

分布式系统绕不开 CAP 权衡。ArkData 的分布式能力在设计上偏向 AP（可用性 + 分区容忍）：网络断开时，各设备仍可在本地读写（高可用），待网络恢复后再同步收敛（最终一致）。这非常契合移动场景——用户在地铁里没网也要能勾选待办，而不是卡住等同步。代价是短暂的数据不一致窗口，我们通过 updatedAt 时间戳兜底，确保收敛后数据符合"最后写入者胜出"的直觉预期。若业务对强一致有硬要求（如金融余额），则不应依赖 KVStore 的最终一致模型，而应走服务端事务。

---

四、完整代码实现

下面给出四个核心模块的精炼可运行实现。为控制篇幅，每段只展示核心逻辑，省略了大量 try-catch 中的日志细节，实际工程中应补全错误处理。

4.1 Preferences 轻量存储读写

// storage/PreferencesHelper.ets
import { preferences } from '@kit.ArkData';
import { PREF_NAME, PREF_KEYS } from '../model/StorageSchema';

export class PreferencesHelper {
  private store: preferences.Preferences | null = null;

  // 初始化（在 EntryAbility.onCreate 中调用一次）
  async init(context: Context): Promise<void> {
    this.store = await preferences.getPreferences(context, PREF_NAME);
  }

  // 写入并持久化（put 只写内存，flush 才落盘）
  async setDarkMode(value: boolean): Promise<void> {
    if (!this.store) return;
    await this.store.put(PREF_KEYS.DARK_MODE, value);
    await this.store.flush();  // 关键：不 flush 重启会丢
  }

  // 读取，带默认值
  async getDarkMode(): Promise<boolean> {
    if (!this.store) return false;
    return await this.store.get(PREF_KEYS.DARK_MODE, false) as boolean;
  }

  // 判断是否首次启动并翻转标记
  async checkFirstLaunch(): Promise<boolean> {
    if (!this.store) return true;
    const first = await this.store.get(PREF_KEYS.FIRST_LAUNCH, true) as boolean;
    if (first) {
      await this.store.put(PREF_KEYS.FIRST_LAUNCH, false);
      await this.store.flush();
    }
    return first;
  }
}

要点：put 只更新内存缓存，必须调用 flush() 才会异步落盘；频繁写入时可批量 put 后统一 flush，减少磁盘 IO。

4.2 RDB 建表与增删改查

// storage/TodoRdbHelper.ets
import { relationalStore } from '@kit.ArkData';
import { Todo } from '../model/TodoModel';
import { RDB_CONFIG, TABLE_TODO, SQL_CREATE_TODO, SQL_INDEX_DONE }
  from '../model/StorageSchema';

export class TodoRdbHelper {
  private rdb: relationalStore.RdbStore | null = null;

  async init(context: Context): Promise<void> {
    this.rdb = await relationalStore.getRdbStore(context, {
      name: RDB_CONFIG.name,
      securityLevel: relationalStore.SecurityLevel.S3
    });
    await this.rdb.executeSql(SQL_CREATE_TODO);
    await this.rdb.executeSql(SQL_INDEX_DONE);
  }

  // 新增：返回自增主键
  async insert(todo: Todo): Promise<number> {
    if (!this.rdb) return -1;
    const bucket: relationalStore.ValuesBucket = {
      title: todo.title, content: todo.content,
      priority: todo.priority, done: todo.done ? 1 : 0,
      dueTime: todo.dueTime, createdAt: todo.createdAt,
      updatedAt: todo.updatedAt
    };
    return await this.rdb.insert(TABLE_TODO, bucket);
  }

  // 更新完成状态
  async setDone(id: number, done: boolean): Promise<number> {
    if (!this.rdb) return 0;
    const pred = new relationalStore.RdbPredicates(TABLE_TODO);
    pred.equalTo('id', id);
    return await this.rdb.update(
      { done: done ? 1 : 0, updatedAt: Date.now() }, pred);
  }

  // 删除
  async delete(id: number): Promise<number> {
    if (!this.rdb) return 0;
    const pred = new relationalStore.RdbPredicates(TABLE_TODO);
    pred.equalTo('id', id);
    return await this.rdb.delete(pred);
  }

  // 查询：未完成 + 按优先级降序
  async queryPending(): Promise<Todo[]> {
    if (!this.rdb) return [];
    const pred = new relationalStore.RdbPredicates(TABLE_TODO);
    pred.equalTo('done', 0).orderByDesc('priority');
    const rs = await this.rdb.query(pred, [
      'id', 'title', 'content', 'priority',
      'done', 'dueTime', 'createdAt', 'updatedAt']);
    const list: Todo[] = [];
    while (rs.goToNextRow()) {
      list.push({
        id: rs.getLong(rs.getColumnIndex('id')),
        title: rs.getString(rs.getColumnIndex('title')),
        content: rs.getString(rs.getColumnIndex('content')),
        priority: rs.getLong(rs.getColumnIndex('priority')),
        done: rs.getLong(rs.getColumnIndex('done')) === 1,
        dueTime: rs.getLong(rs.getColumnIndex('dueTime')),
        createdAt: rs.getLong(rs.getColumnIndex('createdAt')),
        updatedAt: rs.getLong(rs.getColumnIndex('updatedAt'))
      });
    }
    rs.close();  // 必须关闭 ResultSet，否则内存泄漏
    return list;
  }
}

要点：RdbPredicates 是链式条件构造器，支持 equalTo、orderByDesc、like、between、limit 等丰富谓词，无需手拼 SQL 字符串，既避免注入又提升可读性；查询结果 ResultSet 用完必须 close()；批量写入应包在 beginTransaction() / commit() 事务中，性能可提升数倍。需要模糊搜索时，可用 pred.like('title', '%' + keyword + '%')，但大数据量下 like 无法走索引，建议改用 FTS 全文检索。

4.3 分布式 KVStore 数据同步

// storage/SyncKvHelper.ets
import { distributedKVStore } from '@kit.ArkData';
import { KV_STORE_ID } from '../model/StorageSchema';

export class SyncKvHelper {
  private kv: distributedKVStore.SingleKVStore | null = null;

  async init(context: Context): Promise<void> {
    const manager = distributedKVStore.createKVManager({
      context, bundleName: 'com.example.todoapp'
    });
    this.kv = await manager.getKVStore(KV_STORE_ID, {
      createIfMissing: true,
      autoSync: true,                // 自动跨设备同步
      kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
      securityLevel: distributedKVStore.SecurityLevel.S2
    });
    this.listen();
  }

  // 写入完成状态（会自动同步到其他设备）
  async putDone(todoId: number, done: boolean): Promise<void> {
    if (!this.kv) return;
    const val = JSON.stringify({ done, updatedAt: Date.now() });
    await this.kv.put(`todo_${todoId}`, val);
  }

  // 监听远端数据变化
  private listen(): void {
    this.kv?.on('dataChange',
      distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE,
      (change: distributedKVStore.ChangeNotification) => {
        change.updateEntries.forEach((entry) => {
          const remote = JSON.parse(entry.value.value as string);
          // Last-Write-Wins：交给上层比较 updatedAt 决定是否覆盖本地
          this.onRemoteUpdate(entry.key, remote.done, remote.updatedAt);
        });
      });
  }

  private onRemoteUpdate(key: string, done: boolean, ts: number): void {
    // 上层实现：对比本地 updatedAt，较新则更新 RDB 与 UI
  }
}

要点：autoSync: true 时框架自动在同账号可信设备间同步；SUBSCRIBE_TYPE_REMOTE 只监听来自远端的变更，避免本地写入回环触发。

4.4 PersistentStorage 与 AppStorage 桥接

// 1) EntryAbility.ets 中初始化（onCreate 阶段）
import { PersistentStorage, AppStorage } from '@kit.ArkUI';
// 将 darkMode 声明为持久化：首次读磁盘，之后自动落盘
PersistentStorage.persistProp('darkMode', false);
PersistentStorage.persistProp('fontSize', 16);

// 2) pages/SettingsPage.ets 中使用
@Entry
@Component
struct SettingsPage {
  // 双向绑定 AppStorage 中的 darkMode，改动自动持久化
  @StorageLink('darkMode') darkMode: boolean = false;
  @StorageProp('fontSize') fontSize: number = 16;

  build() {
    Column() {
      Row() {
        Text('深色模式').fontSize(this.fontSize)
        Toggle({ type: ToggleType.Switch, isOn: this.darkMode })
          .onChange((isOn: boolean) => {
            // 仅赋值即可，PersistentStorage 自动写磁盘
            this.darkMode = isOn;
          })
      }.justifyContent(FlexAlign.SpaceBetween).width('100%')
    }.padding(16)
  }
}

要点：PersistentStorage.persistProp 建立了 AppStorage key 与磁盘的映射，之后任何对该 key 的修改（无论通过 @StorageLink 还是 AppStorage.set）都会自动持久化，开发者无需手写读写代码——这是 ArkData 与 ArkUI 状态管理深度融合的体现。

4.5 事务批量写入与版本迁移

实际工程中两个高频场景：批量导入与数据库升级。下面把两者的核心逻辑合并展示：

// storage/RdbMigration.ets
import { relationalStore } from '@kit.ArkData';
import { Todo } from '../model/TodoModel';
import { TABLE_TODO } from '../model/StorageSchema';

export class RdbMigration {
  // 事务批量写入：数千条合并为一次提交
  static async batchInsert(
    rdb: relationalStore.RdbStore, list: Todo[]): Promise<void> {
    rdb.beginTransaction();
    try {
      for (const t of list) {
        await rdb.insert(TABLE_TODO, {
          title: t.title, content: t.content,
          priority: t.priority, done: t.done ? 1 : 0,
          dueTime: t.dueTime, createdAt: t.createdAt,
          updatedAt: t.updatedAt
        });
      }
      rdb.commit();           // 一次 fsync，性能数倍提升
    } catch (e) {
      rdb.rollBack();         // 任一失败整体回滚
    }
  }

  // 版本升级：根据 user_version 逐级迁移，不丢数据
  static async migrate(rdb: relationalStore.RdbStore): Promise<void> {
    const TARGET = 2;
    if (rdb.version === 0) {
      rdb.version = 1;        // 首次建库
    }
    if (rdb.version === 1) {
      // v1 -> v2：新增 tags 列，保留已有数据
      await rdb.executeSql(
        `ALTER TABLE ${TABLE_TODO} ADD COLUMN tags TEXT DEFAULT ''`);
      rdb.version = 2;
    }
    // 继续追加 v2 -> v3 ...
  }
}

要点：beginTransaction 后的多条写入只在 commit 时落盘一次，避免逐条 fsync；升级采用“逐级台阶式”迁移，无论用户从哪个旧版本升级，都能逐步跑到最新 schema，切忌 DROP 重建。

---

五、深度技术原理

5.1 ArkData 分层架构

ArkData 并非单一模块，而是一套分层的数据管理框架，自上而下可分为：

• 接口层（API）：对外暴露 preferences、relationalStore、distributedKVStore、dataShare 等能力，屏蔽底层差异；
• 数据管理服务层（DatamgrService）：一个独立的系统服务进程，负责数据的统一调度、权限校验、跨应用/跨设备的数据流转；
• 存储引擎层：RDB 底层是 SQLite，KVStore 底层是华为自研的 GaussDB Micro / 键值引擎，Preferences 底层是 XML/二进制文件 + 内存缓存；
• 分布式软总线（SoftBus）：为跨设备同步提供底层通信通道，负责设备发现、认证与高效数据传输。

这种分层让上层应用无需关心数据到底存在本地文件还是要同步到另一台设备，框架自动完成路由。值得注意的是，DatamgrService 作为独立服务进程，意味着数据的生命周期不完全继贴在应用进程上：即使应用被回收，已提交的数据也不会丢失，重新启动时仍能读回，这正是“持久化”的本质。

5.2 数据库事务与索引

RDB 基于 SQLite，天然支持 ACID 事务。批量写入时，若逐条 insert，每条都会触发一次磁盘同步（fsync），极慢；用事务包裹后，多条写入合并为一次提交，性能可提升 10 倍以上：

this.rdb.beginTransaction();
try {
  for (const t of todos) { await this.rdb.insert(TABLE_TODO, toBucket(t)); }
  this.rdb.commit();
} catch (e) {
  this.rdb.rollBack();
}

索引本质是一棵 B+ 树。为 (done, priority) 建复合索引后，查询"未完成且高优先级"时，数据库直接在索引树上定位，无需全表扫描，复杂度从 O(n) 降至 O(log n)。代价是每次写入需同步维护索引树，因此索引应只建在高频查询列上。复合索引的列顺序也有讲究：遵循“最左前缀”原则，将选择性高、等值查询频繁的列放在前面，才能让索引被最大化利用。本例把 done 放在 priority 前，因为筛选总是先按完成状态过滤，再按优先级排序。

5.3 分布式同步与冲突解决

分布式 KVStore 采用最终一致性模型。当设备 A 与设备 B 同时修改同一 key：

1. 各自本地先写入成功（保证本地可用性）；
2. 通过软总线交换变更，每条变更携带逻辑时间戳/版本向量；
3. 冲突发生时，SINGLE_VERSION 库默认采用 Last-Write-Wins（LWW）：时间戳较大的写入胜出；
4. 若业务需要更精细的合并（如两端各加了不同待办），可选用 DEVICE_COLLABORATION 类型库，按设备维度隔离，读取时合并。

本项目在应用层再加一道保险：收到远端变更后，比较 value 中的 updatedAt 与本地记录，只有远端更新才覆盖，避免"旧数据回冲"覆盖新数据。

为什么不能直接信任物理到达时间？因为分布式环境下各设备时钟可能不同步，网络延迟也会打乱到达顺序；一个早修改的数据可能因网络抚摩比晚修改的更晚到达。因此以数据自带的业务时间戳 updatedAt（写入瞬间记录）作为判断依据，比单纯依赖到达顺序更可靠。对一致性要求极高的场景，可引入逻辑时钟（向量时钟）进一步避免时钟回拨带来的异常。

5.4 存储引擎底层与安全

• securityLevel（S1–S4）：决定数据加密强度与可跨设备的范围。S3/S4 数据存放在更安全的加密分区，跨设备同步时也要求对端达到同等安全等级；
• Preferences 的内存缓存：首次 getPreferences 时把整个文件加载进内存，之后 get 都是内存读取，故极快；flush 时才异步序列化落盘；
• 写时复制与 WAL：SQLite 开启 WAL（Write-Ahead Logging）模式后，读写可并发，写操作先追加到日志再异步 checkpoint 到主库，提升并发性能。

5.5 异步模型与“读到旧值”陷阱

ArkData 绝大多数写操作都是异步的，这带来一个经典坑：上一行 await put(...) 还未完成，下一行就 get(...)，若忘了 await，很可能读到写入前的旧值。正确做法是严格串行化依赖写结果的读，或将写入结果直接回写内存状态（如 AppStorage）避免回读。同时，所有数据库 IO 均应在子线程/异步中执行，切勿在 UI 主线程同步阻塞，否则会导致界面卡顿与丢帧。

5.6 软总线在同步中的角色

分布式同步的底层基石是 分布式软总线（DSoftBus）。它屏蔽了 Wi-Fi、蓝牙、蓝牙低功耗等异构传输介质，对上层提供统一的设备发现、认证与传输能力。当 KVStore 写入一个 key，DatamgrService 会将变更打包交给软总线，后者自动选择最优链路传输到对端设备的 DatamgrService，再写入对端本地库并触发 dataChange 回调。整个过程开发者无需感知网络细节，这正是 ArkData“一次开发、多端部署”理念的具体体现。

5.7 数据共享（DataShare）与沙箱隔离

HarmonyOS 应用运行在各自的沙箱中，应用 A 无法直接读写应用 B 的数据目录。若需跨应用共享数据，必须通过 DataShare 机制：数据提供方实现 DataShareExtensionAbility，对外暴露一个 datashare:// URI，消费方通过 dataShare.createDataShareHelper 获取代理后，就能像操作本地 RDB 一样 query/insert，而底层访问权限由提供方把关。这套机制既保障了沙箱隔离的安全，又提供了受控的共享通道，常用于桌面卡片、原子化服务读取宿主应用数据的场景。

5.8 安全等级与加密落盘

securityLevel 不仅影响能否跨设备，还决定了数据在磁盘上的存放位置与加密方式。S1 数据风险最低，而 S3/S4 涉及个人敏感信息，存放在更高等级的加密分区，只有设备解锁后才能解密访问。这意味着设置过高的安全等级会影响开机未解锁时的后台读写能力，应根据数据敏感度合理选择：普通业务数据 S2/S3，极敏感数据才用 S4。

---

六、常见问题解答（FAQ）

Q1：Preferences 的 put 之后不调用 flush，数据会丢吗？
会。put 只更新内存缓存，进程正常退出时框架可能自动 flush，但异常退出（崩溃、被系统杀死）就会丢失。任何需要持久化的写入，务必显式调用 flush()。

Q2：RDB 查询后忘记 close ResultSet 有什么后果？
ResultSet 持有底层游标与内存缓冲，不关闭会导致内存泄漏，累积多了甚至触发"too many open cursors"错误。务必在遍历完成后调用 rs.close()，建议放在 finally 块。

Q3：分布式数据同步不生效，怎么排查？
依次检查：①两台设备是否登录同一华为账号并处于同一可信网络；②autoSync 是否为 true；③securityLevel 是否满足跨设备要求；④是否申请了 DISTRIBUTED_DATASYNC 权限；⑤软总线是否正常（设备是否在"附近设备"中可见）。

Q4：PersistentStorage 能存对象或数组吗？
原生仅可靠支持 string、number、boolean 等简单类型。存复杂对象需先 JSON.stringify 成字符串再存，读取时 JSON.parse。大对象或结构化数据应改用 RDB。

Q5：数据库版本升级（加字段）怎么做才不丢数据？
在 getRdbStore 时读取 rdb.version，与代码中的目标版本比较；若过旧，执行 ALTER TABLE ... ADD COLUMN 等迁移 SQL，再把 rdb.version 更新为新值。切忌 DROP 重建表，那样会丢用户数据。

Q7：多个页面都要读写同一个 RdbStore，需要反复 getRdbStore 吗？
不需要，也不建议。getRdbStore 应在应用启动时初始化一次，把实例保存在单例或全局 Helper 中复用。反复创建不仅浪费资源，还可能导致多个连接并发写入时的锁竞争。正确做法是在 EntryAbility.onCreate 中完成初始化，页面仅引用已有实例。

Q6：Preferences 和 RDB 能存多大的数据？
Preferences 定位轻量，官方建议键值总量控制在一万条以内、单值不宜过大；超出应改用 RDB。RDB 基于 SQLite，理论上可存 GB 级数据，但移动端仍应结合分页查询避免一次性加载过多。

---

七、运行效果

下图用 ASCII 字符画展示本应用的数据存储分层与跨设备同步链路：

运行时，用户在手机勾选"交作业"，本地 RDB 与 KVStore 同步更新，UI 立即响应；约 1 秒内平板通过软总线收到远端变更，比较时间戳后更新本地数据库并刷新界面，实现无感多端同步。偏好设置修改后，重启应用依然保持——Preferences 与 PersistentStorage 保证了持久性。

7.1 实测性能参考

在一台中端测试机上，各存储能力的典型耗时如下（仅供量级参考，实际受设备与数据量影响）：

操作	存储能力	数据量	典型耗时
读取单个配置	Preferences（内存）	1 键	< 1ms
flush 落盘	Preferences	数十键	3–10ms
单条 insert	RDB	1 行	1–3ms
批量 insert（无事务）	RDB	1000 行	~800ms
批量 insert（事务）	RDB	1000 行	~80ms
索引查询	RDB	3000 行中筛选	5–15ms
跨设备同步廣时	KVStore	单 key	0.5–2s

从表中可以直观看到：事务把批量写入从 800ms 降到 80ms，提升约 10 倍；索引让三千条数据的筛选仍保持在十毫秒级。这也再次印证了三类存储各发挥所长的选型思路。

---

八、扩展方向

• 端云协同：接入 HarmonyOS 云数据库（Cloud DB），实现登录即同步、离线可用、上线自动合并，突破"仅可信设备"的局限；
• 全文检索：为待办内容引入 FTS（Full-Text Search）虚拟表，支持中文分词模糊搜索；
• 数据加密与备份：对敏感字段启用字段级加密，结合系统备份能力实现自动云备份与恢复；
• 数据共享（DataShare）：通过 DataShareExtensionAbility 把待办数据安全地共享给其他应用或桌面卡片；
• 响应式数据流：结合 @ohos.data.relationalStore 的订阅能力，实现数据变更自动驱动 UI 刷新，打造真正的响应式架构；
• 性能监控：接入 HiChecker / DevEco Profiler，监控数据库慢查询与主线程 IO 阻塞，持续优化。

从本项目出发，一个健康的持久化架构应遵循“分层、分职、可演进”三原则：分层是指 UI 层只面向状态，数据访问封装在 Helper/Repository 层，底层存储介质对上透明；分职是指配置、业务、同步状态各归其位；可演进是指 schema 有版本号、迁移有台阶、存储选型可随业务量级变化而升级。掌握了这三点，无论后续需求如何变化，ArkData 体系都能稳健地支撑应用的数据底座。

希望本文从需求、建模、选型、实现到原理的完整链路，能帮你建立起对 ArkData 的全局认知。真正的掌握来自动手实践——建议从一个最小的 Preferences 开关开始，逐步引入 RDB 与分布式同步，在真机上体验多端协同的魅力。