HarmonyOS 用 relationalStore 做本地数据库的完整实战 —— 一个真实项目的 5 个决策

各好，又回~

上周三我在一个已经上架的鸿蒙 App 里改本地数据库结构，加两个字段。改完跑了一遍，App 起不来。日志说 no such column。

其实是我忘了处理老用户的库。新库有字段，旧库没有，一 ALTER TABLE 已存在的列，SQLite 直接甩错。这类事情在原生 SQLite 上人人都懂怎么处理，但在 HarmonyOS 的 relationalStore 里，官方文档给的示例大多只到"建库 + 建表 + 查询"，schema 升级、异常兜底、单例管理这些工程化的东西是要自己搭的。

这篇是把我在一个中等规模鸿蒙 App 里，围绕 relationalStore 做过的 5 个真实决策抠出来讲，包括我一开始判断错、后来推翻自己的过程。适合已经跑通 helloworld、准备把 rdb 用到线上 App 的开发者。

一、RdbStore 该做成什么级别的单例

我一开始按官方文档写，每次要用数据库就 relationalStore.getRdbStore(...) 拿一次。跑本地没问题，上真机后有个偶发现象：第一次进 App 时如果快速切页面，会出现两个页面各自持有 rdbStore 的场景，一个页面 insert，另一个刚初始化到一半，UI 有几十毫秒空数据。

调了一下才发现，getRdbStore 是异步的，短时间连续调用会返回不同的 promise，而这些 promise 各自去初始化。看起来官方内部有做缓存，但缓存粒度和时机不完全可控。

我把它改成了应用级单例 + 初始化 promise 复用：

import type Context from '@ohos.app.ability.common';
import relationalStore from '@ohos.data.relationalStore';
import { DB_NAME, PROGRAM_PROGRESS_COLUMNS, SESSION_COLUMNS, TABLES } from './RdbSchema';

export class RdbStoreManager {
  private static store?: relationalStore.RdbStore;
  private static initializing?: Promise<relationalStore.RdbStore>;

  static async getStore(context: Context): Promise<relationalStore.RdbStore> {
    if (RdbStoreManager.store) {
      return RdbStoreManager.store;
    }
    if (!RdbStoreManager.initializing) {
      const config: relationalStore.StoreConfig = {
        name: DB_NAME,
        securityLevel: relationalStore.SecurityLevel.S1
      };
      RdbStoreManager.initializing = (async () => {
        try {
          const store = await relationalStore.getRdbStore(context, config);
          await RdbStoreManager.ensureTables(store);
          RdbStoreManager.store = store;
          return store;
        } catch (err) {
          RdbStoreManager.initializing = undefined;
          throw new Error('Failed to initialize database store.');
        }
      })();
    }
    return RdbStoreManager.initializing;
  }
  // ...
}

关键就三件事：

第一，store 变量保存已经初始化好的实例，命中直接返回。第二，initializing 保存"正在初始化"的 Promise，如果 3 个页面同时调进来，只有第一个真的走 getRdbStore，后两个 await 同一个 Promise。第三，一旦初始化失败，把 initializing 清掉，让下次调用可以重试，不至于永远卡在 rejected promise 上。

这套写法本身不复杂，但踩过一次才会想到把 initializing 加进来。只有 store 单例、没有 initializing 单例的写法，在并发场景下等同于没做单例。

二、securityLevel 该怎么选

StoreConfig 里必填的字段有两个：name 和 securityLevel。name 好懂，就是数据库文件名。securityLevel 我一开始随手抄了 S3，因为看到官方示例里写 S3。后来才反应过来这不是"越高越好"的字段。

securityLevel 从 S1 到 S4，本质是告诉系统这份数据的敏感度，用来决定加密和跨设备同步的策略。你选得越高，未来想接分布式数据同步（比如手机 + 平板 + 手表）时限制越多，数据可能被拒绝跨端流转。

我的 App 存的是呼吸训练历史记录：什么时候练了什么模式、练了多久。这算个人使用数据，但不涉及金融、健康诊断这种硬敏感项。选 S1 就够了：

const config: relationalStore.StoreConfig = {
  name: DB_NAME,
  securityLevel: relationalStore.SecurityLevel.S1
};

选 S1 之后有个观察：应用启动 + 频繁读写的场景明显顺畅了一些，加密开销确实存在。对于一个每秒最多也就 insert 一两条记录的 App，这个差距肉眼不明显。但如果你的场景是要批量导入几万条数据（比如从 CSV 恢复），这个差距就要考虑了。

选择建议大致是：普通业务数据 S1；含个人身份识别（手机号、身份证号）S2；含健康、金融、行为轨迹 S3；含高敏感（生物识别原始数据）S4。在纠结的时候往下一级选，比往上多选一级要稳。

三、Schema 迁移：新版加字段怎么不让老用户崩

前面提到的"改完跑不起来"的坑就是这里。做法上其实很简单，但需要你在设计阶段就想清楚："我以后会不会加字段"。答案基本是"会"，所以老老实实为 schema 演进准备两件事。

第一件：建表用 CREATE TABLE IF NOT EXISTS，别用 CREATE TABLE。这样对老用户（表已存在）来说是空操作，不会报错。

const createSessions = `CREATE TABLE IF NOT EXISTS ${TABLES.sessions} (` +
  `${SESSION_COLUMNS.id} TEXT PRIMARY KEY, ` +
  `${SESSION_COLUMNS.timestamp} INTEGER NOT NULL, ` +
  `${SESSION_COLUMNS.modeId} TEXT NOT NULL, ` +
  `${SESSION_COLUMNS.duration} INTEGER NOT NULL` +
  `);`;

try {
  await store.executeSql(createSessions);
} catch (_err) {
  // Ignore table creation failures.
}

第二件：加字段时用 ALTER TABLE ... ADD COLUMN，然后把错误吞掉。SQLite 里 ADD COLUMN 已存在的列会抛 "duplicate column" 错误，你 catch 掉即可：

private static async ensureCompatibilityColumns(store: relationalStore.RdbStore): Promise<void> {
  const statements: string[] = [
    `ALTER TABLE ${TABLES.sessions} ADD COLUMN ${SESSION_COLUMNS.courseId} TEXT`,
    `ALTER TABLE ${TABLES.sessions} ADD COLUMN ${SESSION_COLUMNS.programId} TEXT`,
    `ALTER TABLE ${TABLES.sessions} ADD COLUMN ${SESSION_COLUMNS.programDay} INTEGER`,
    `ALTER TABLE ${TABLES.sessions} ADD COLUMN ${SESSION_COLUMNS.preCheckin} TEXT`,
    `ALTER TABLE ${TABLES.sessions} ADD COLUMN ${SESSION_COLUMNS.postCheckin} TEXT`,
  ];
  for (const stmt of statements) {
    try {
      await store.executeSql(stmt);
    } catch (_err) {
      // Ignore "duplicate column" and keep startup resilient on old/new schemas.
    }
  }
}

这个模式我叫它"幂等式迁移"：每次 App 冷启动都跑一遍 ALTER，跑不通的就当没跑。对老用户来说，第一次冷启动会加上新列；对新用户来说，CREATE TABLE IF NOT EXISTS 已经把最新 schema 建好了，ALTER 全部会因为"列已存在"被 catch 掉，也没事。

这里有个更"优雅"的做法是用 store.version 做版本化迁移 ，官方 API 里有 RdbStore.version 字段可以读写。理论上更规范，但要写个 switch 处理每个版本号的迁移逻辑。我在这个项目里没用，理由很朴素：这个 App 的 schema 变更频率不高、每次改动都是加字段而不是改结构，加个 version 反而让代码里多出一整套没用几次的迁移分支，投入产出不划算。如果你的 App schema 会长期演进、有可能要改列类型或删列，version 迁移是更好的选择。

四、RdbPredicates 的用法比想象中好用

早期我写查询是这样的：拼一个 SQL 字符串，executeSql 执行。能跑，但类型不安全，改列名时容易漏。

后来看到 RdbPredicates 后基本全换了。核心思路是把 where、orderBy、limit 这些都用链式 API 表达，然后传给 store.query：

async listRecent(context: Context, limit: number = 50): Promise<SessionRecord[]> {
  const store = await RdbStoreManager.getStore(context);
  const predicates = new relationalStore.RdbPredicates(TABLES.sessions)
    .orderByDesc(SESSION_COLUMNS.timestamp);
  if (limit > 0) {
    predicates.limitAs(limit);
  }
  const resultSet = await store.query(predicates, Object.values(SESSION_COLUMNS));
  // ... 遍历 resultSet
}

好处是列名和表名都从常量文件（RdbSchema）里来的，改一次到处生效。缺点是 resultSet 的读取仍然是 SQLite 那套 getString / getLong / getColumnIndex，得自己写 helper 转成业务模型。这块我封了两个私有方法处理可选字段：

private optionalString(resultSet: relationalStore.ResultSet, column: string): string | undefined {
  try {
    const index = resultSet.getColumnIndex(column);
    if (resultSet.isColumnNull(index)) {
      return undefined;
    }
    const value = resultSet.getString(index);
    return value.length ? value : undefined;
  } catch (_err) {
    return undefined;
  }
}

private optionalNumber(resultSet: relationalStore.ResultSet, column: string): number | undefined {
  try {
    const index = resultSet.getColumnIndex(column);
    if (resultSet.isColumnNull(index)) {
      return undefined;
    }
    return Number(resultSet.getLong(index));
  } catch (_err) {
    return undefined;
  }
}

为什么把空字符串也当 undefined 处理 ：因为业务模型里的 preCheckin?: string，值有可能是"用户跳过了这个可选步骤"（应该是 undefined），也可能是"用户填了个空字符串"（应该是 ''）。数据库里没法区分这两种，我按第一种处理，反正 UI 层看到 undefined 就当没填。

五、Upsert：新增和更新用同一个方法

这个是最容易被忽略的一点。业务上很多"保存"操作其实是"如果已存在就更新，否则插入"。SQLite 有 INSERT OR REPLACE，但会重置 rowid、破坏关联；INSERT ... ON CONFLICT 用 relationalStore 的 API 不好表达。

我最后选的写法是先查一遍，根据结果决定 insert 还是 update：

async upsertProgress(context: Context, record: ProgramProgressRecord): Promise<void> {
  const store = await RdbStoreManager.getStore(context);
  const existing = await this.getProgress(context, record.programId);
  const now = Date.now();
  const values: relationalStore.ValuesBucket = {};
  values[PROGRAM_PROGRESS_COLUMNS.programId] = record.programId;
  values[PROGRAM_PROGRESS_COLUMNS.startedAt] = Math.floor(record.startedAt ?? existing?.startedAt ?? now);
  values[PROGRAM_PROGRESS_COLUMNS.lastCompleted] = Math.floor(record.lastCompleted ?? now);
  values[PROGRAM_PROGRESS_COLUMNS.completedDays] = this.serializeDays(record.completedDays);

  if (existing) {
    const predicates = new relationalStore.RdbPredicates(TABLES.programProgress)
      .equalTo(PROGRAM_PROGRESS_COLUMNS.id, existing.id);
    await store.update(values, predicates);
  } else {
    values[PROGRAM_PROGRESS_COLUMNS.id] = `${Date.now()}-${Math.floor(Math.random() * 100000)}`;
    await store.insert(TABLES.programProgress, values);
  }
}

有两个细节容易漏：

一个是 startedAt 的取值：record.startedAt ?? existing?.startedAt ?? now。第一次插入时用参数或 now；更新时如果参数没给，保留原 startedAt（不能被 now 覆盖，否则用户第 3 天完成时会以为程序是今天才开始的）。

一个是 id 生成。上面这段用 Date.now() + Math.random()，够用，但如果你的表有可能被多设备同步 ，要用 UUID 之类的全局唯一 id，不能用时间戳。项目里另有一处用了 crypto.randomUUID() 处理需要跨端稳定标识的场景。

尾声

关于 relationalStore 我最初的印象是"能用但不好用"，官方 API 看起来像给系统开发者用的、不像给业务开发者用的。真正投入项目后发现，工程化的坑一个都跑不掉：单例、schema 迁移、异常兜底、类型安全、可选字段。

上面 5 个决策全部来自 App 的实际代码（entry/src/main/ets/data/db 和 entry/src/main/ets/data/repos），如果有类似场景直接抄或改一改都 OK。

有一个 API 我一直没用上但想推荐给你看看：RdbStore.beginTransaction / commit / rollBack。目前没有需要跨表原子操作的场景，所以省了。你要做类似"扣钱 + 加账单"这种，一定要开事务。