鸿蒙数据库开发：单例模式与RdbManager实践-代码聚汇网

鸿蒙数据库开发：单例模式与RdbManager实践

第三世界的妖孽

1. 鸿蒙数据库开发痛点与解决方案

在鸿蒙应用开发中，数据库操作看似简单，实则暗藏诸多陷阱。许多开发者都曾遇到过这样的场景：应用运行一段时间后莫名卡顿，排查发现是数据库连接泄漏；或是应用升级后频繁闪退，原因是忘记处理旧版本数据迁移。这些问题往往在开发阶段难以察觉，直到上线后才暴露出来。

1.1 常见数据库管理误区

资源泄漏问题：频繁创建未关闭的数据库连接会导致内存和文件句柄耗尽。我曾在一个项目中接手过这样的代码：每个页面都独立创建RdbStore实例，结果应用在低端设备上运行30分钟后必然崩溃。

版本升级灾难：当应用新增表结构或字段时，若未正确处理旧版本数据迁移，用户更新应用后轻则数据丢失，重则直接闪退。去年某知名应用的大版本更新就因此收到大量差评。

线程安全隐患：多线程同时操作数据库时，若未做好同步控制，可能导致数据错乱。特别是在鸿蒙的分布式场景下，这个问题会被放大。

1.2 单例模式的必要性

单例模式是解决上述问题的银弹方案。通过确保全局只有一个数据库连接实例，我们可以：

避免重复创建连接的开销
集中管理资源释放
统一处理版本迁移
简化多线程同步控制

在鸿蒙的RdbStore实现中，底层SQLite连接本身是线程安全的，但应用层仍需保证对同一个RdbStore实例的访问有序性。我们的RdbManager单例封装正是为此而生。

2. RdbManager核心实现解析

2.1 单例生命周期管理

typescript复制// 精简后的核心单例实现
export class RdbManager {
  private static instance: RdbManager;
  private rdbStore: relationalStore.RdbStore | null = null;
  private context: common.UIAbilityContext | null = null;

  public static getInstance(): RdbManager {
    if (!RdbManager.instance) {
      RdbManager.instance = new RdbManager();
    }
    return RdbManager.instance;
  }

  public init(context: common.UIAbilityContext): void {
    this.context = context;
  }
}

这里有几个关键设计点：

私有构造函数：防止外部通过new创建实例
静态instance变量：持有唯一实例
懒加载策略：首次调用getInstance()时才创建实例
显式初始化：需要手动调用init()注入Context

提示：为什么不直接在getInstance()中初始化？因为Ability的context创建时机早于UI线程，分离初始化更符合鸿蒙生命周期。

2.2 数据库连接管理

typescript复制public async getRdbStore(): Promise<relationalStore.RdbStore> {
  // 已存在则直接返回
  if (this.rdbStore) return this.rdbStore; 
  
  // 检查上下文
  if (!this.context) throw new Error('Context未初始化');
  
  // 创建新连接
  const config: relationalStore.StoreConfig = {
    name: DB_NAME,
    securityLevel: DB_SECURITY_LEVEL
  };
  
  this.rdbStore = await relationalStore.getRdbStore(this.context, config);
  
  // 版本管理逻辑
  await this.handleVersion(this.rdbStore);
  
  return this.rdbStore;
}

连接管理中的几个精妙之处：

连接复用：避免重复创建的性能开销
懒加载：只有真正需要时才建立连接
异常处理：捕获并转换底层异常
版本检查：下文会详细展开

2.3 版本迁移机制

版本迁移是数据库管理的重中之重。我们的方案采用version-driven方式：

typescript复制private async handleVersion(store: relationalStore.RdbStore) {
  const currentVersion = store.version;
  const targetVersion = RdbManager.DB_VERSION;
  
  if (currentVersion === 0) {
    // 全新安装
    await this.initTables(store);
    store.version = targetVersion;
  } else if (currentVersion < targetVersion) {
    // 版本升级
    await this.upgradeTables(store, currentVersion, targetVersion);
    store.version = targetVersion;
  }
  // 版本相同无需处理
}

升级逻辑采用递进式设计：

typescript复制private async upgradeTables(store: relationalStore.RdbStore, 
                          oldVersion: number, 
                          newVersion: number) {
  // 版本1→2：新增sort_order字段
  if (oldVersion < 2) {
    await store.executeSql('ALTER TABLE project ADD COLUMN sort_order INTEGER');
  }
  
  // 版本2→3：创建索引
  if (oldVersion < 3) {
    await store.executeSql('CREATE INDEX idx_project_name ON project(name)');
  }
}

这种设计的好处是：

支持跨版本升级（如从v1直接升到v3）
每个版本变更隔离，便于维护
升级过程可加入数据迁移逻辑

3. DAO层设计与实现

3.1 仓库模式的优势

在RdbManager之上，我们采用Repository模式封装具体业务操作。这种分层架构带来以下好处：

业务逻辑与存储解耦：上层不关心SQL细节
统一入口：所有数据库操作收敛到固定位置
类型安全：TypeScript接口约束输入输出

3.2 实体映射实践

数据库层使用下划线命名，而业务层使用驼峰命名，需要做转换：

typescript复制// 业务对象→数据库值
function projectToValues(project: Project): relationalStore.ValuesBucket {
  return {
    'id': project.id,
    'name': project.name,
    'description': project.description ?? '',
    'color': project.color,
    'created_at': project.createdAt,
    'updated_at': project.updatedAt
  };
}

// 数据库行→业务对象
function rowToProject(resultSet: relationalStore.ResultSet): Project {
  return {
    id: resultSet.getString(resultSet.getColumnIndex('id')),
    name: resultSet.getString(resultSet.getColumnIndex('name')),
    description: resultSet.getString(resultSet.getColumnIndex('description')),
    color: resultSet.getString(resultSet.getColumnIndex('color')),
    createdAt: resultSet.getLong(resultSet.getColumnIndex('created_at')),
    updatedAt: resultSet.getLong(resultSet.getColumnIndex('updated_at'))
  };
}

3.3 完整CRUD示例

以Project实体为例，完整的数据操作封装：

typescript复制// 插入
export async function insertProject(project: Project): Promise<number> {
  const store = await RdbManager.getInstance().getRdbStore();
  return store.insert(TABLE_PROJECT, projectToValues(project));
}

// 查询
export async function queryProjects(): Promise<Project[]> {
  const store = await RdbManager.getInstance().getRdbStore();
  const predicates = new relationalStore.RdbPredicates(TABLE_PROJECT);
  const resultSet = await store.query(predicates);
  
  const projects: Project[] = [];
  try {
    while (resultSet.goToNextRow()) {
      projects.push(rowToProject(resultSet));
    }
  } finally {
    resultSet.close(); // 必须手动关闭
  }
  return projects;
}

// 更新
export async function updateProject(project: Project): Promise<number> {
  const store = await RdbManager.getInstance().getRdbStore();
  const predicates = new relationalStore.RdbPredicates(TABLE_PROJECT);
  predicates.equalTo('id', project.id);
  return store.update(projectToValues(project), predicates);
}

// 删除
export async function deleteProject(id: string): Promise<number> {
  const store = await RdbManager.getInstance().getRdbStore();
  const predicates = new relationalStore.RdbPredicates(TABLE_PROJECT);
  predicates.equalTo('id', id);
  return store.delete(predicates);
}

4. 性能优化与调试技巧

4.1 事务的正确使用

批量操作务必使用事务：

typescript复制async function batchInsert(projects: Project[]) {
  const store = await RdbManager.getInstance().getRdbStore();
  store.beginTransaction();
  try {
    for (const project of projects) {
      await store.insert(TABLE_PROJECT, projectToValues(project));
    }
    store.commit();
  } catch (e) {
    store.rollBack();
    throw e;
  }
}

事务带来的性能提升可达10倍以上，特别是在插入大量数据时。

4.2 查询优化建议

只查询需要的列：避免SELECT *
合理使用索引：高频查询字段建索引
分页加载：大数据集使用LIMIT和OFFSET
预编译语句：重复查询使用缓存

typescript复制// 分页查询示例
async function queryPaged(page: number, size: number): Promise<Project[]> {
  const store = await RdbManager.getInstance().getRdbStore();
  const predicates = new relationalStore.RdbPredicates(TABLE_PROJECT);
  predicates.limit(size).offset(page * size);
  // ...其余处理逻辑
}

4.3 调试与问题排查

常见问题排查清单：

数据库未初始化：检查EntryAbility是否调用了init()
版本不一致：确认DB_VERSION与升级逻辑匹配
ResultSet未关闭：使用try-finally确保资源释放
线程冲突：检查是否有并发操作

调试时可以开启SQL日志：

typescript复制const config: relationalStore.StoreConfig = {
  name: DB_NAME,
  securityLevel: DB_SECURITY_LEVEL,
  // 开启调试日志
  isDebug: true  
};

5. 扩展与进阶实践

5.1 分布式数据库适配

鸿蒙的分布式特性要求数据库设计考虑跨设备同步：

typescript复制const config: relationalStore.StoreConfig = {
  name: DB_NAME,
  securityLevel: DB_SECURITY_LEVEL,
  // 开启分布式同步
  distributed: true,
  // 设置同步模式
  syncMode: relationalStore.SyncMode.SYNC_MODE_PUSH
};

需要特别注意冲突解决策略和数据一致性保障。

5.2 数据加密方案

敏感数据应当加密存储：

typescript复制const config: relationalStore.StoreConfig = {
  name: DB_NAME,
  securityLevel: relationalStore.SecurityLevel.S4, // 最高安全级别
  encryptKey: new Uint8Array([...]), // 32字节密钥
  encrypt: true
};

密钥管理建议使用鸿蒙的密钥管理系统。

5.3 单元测试策略

数据库测试需要特殊处理：

内存数据库：测试时使用:memory:模式
测试隔离：每个测试用例使用独立数据库
Mock方案：对RdbStore接口进行Mock

typescript复制// 测试示例
describe('ProjectRepo', () => {
  beforeEach(async () => {
    // 初始化测试数据库
    const config = { name: ':memory:', securityLevel: DB_SECURITY_LEVEL };
    const context = getContext(); // 获取测试上下文
    RdbManager.getInstance().init(context);
  });
  
  afterEach(() => {
    // 清理数据库
    RdbManager.resetForTest();
  });
});

6. 避坑指南与最佳实践

6.1 必须避免的常见错误

忘记关闭ResultSet：这是内存泄漏的主要原因
在主线程执行大量操作：会导致UI卡顿
忽略版本迁移：用户升级后数据丢失
硬编码SQL语句：难以维护且不安全

6.2 性能优化检查清单

[ ] 是否使用了事务处理批量操作？
[ ] 是否建立了必要的索引？
[ ] 是否避免了N+1查询问题？
[ ] 是否对大数据集做了分页处理？

6.3 代码组织建议

推荐的项目结构：

code复制src/
  data/
    db/
      RdbManager.ts      # 数据库管理核心
      entities/          # 各实体对应的Repository
        ProjectRepo.ts
        ContactRepo.ts
      migrations/        # 数据库迁移脚本
        v1_to_v2.ts
    models/              # 业务对象定义
      Project.ts
      Contact.ts

这种结构清晰分离了数据库操作与业务逻辑。