在鸿蒙（HarmonyOS）开发中，集成并封装 SQLite 数据库主要有两种主流路径：一是直接使用官方提供的 RelationalStore（关系型数据库）API；二是通过 NAPI 机制在 C++ 层调用原生的 sqlite3 库。以下是这两种方案的详细集成与封装指南：

方案一：基于官方 RelationalStore 封装（推荐）

这是鸿蒙官方推荐的方式，底层基于 SQLite，但提供了更安全、类型友好的 ArkTS 接口。

1. 核心架构设计
为了避免在业务代码中散落大量数据库操作，建议封装一个通用的 RdbManager 工具类：

• 单例模式：确保全局只有一个数据库连接实例，避免多表操作时频繁创建 RelationalStore 实例带来的资源开销。
• 统一异常处理：在内部封装 try-catch，对外暴露清晰的 Promise 接口。

2. 基础 CRUD 封装

• 获取实例：通过 relationalStore.getRdbStore(context, config) 获取 RdbStore 实例。
• 增/改：使用 ValuesBucket（键值对容器）封装数据，结合 insert 和 update 方法进行操作。
• 删/查：使用 RdbPredicates 构建类型安全的查询条件。查询返回的 ResultSet 结果集在使用完毕后，必须调用 close() 关闭，否则会导致数据库连接池耗尽。

3. 性能优化关键点

• 批量插入：使用 batchInsert 接口一次性插入多条数据，大幅减少系统调用开销。
• 事务管理：对于批量写入或高并发场景，强烈建议使用 createTransaction 包裹操作。实测表明，使用事务的性能比非事务高出约 200 倍，且能保证操作的原子性。

方案二：基于 NAPI + C++ 原生 sqlite3 封装

如果项目对性能有极致要求，或者需要复用现有的 C++ 数据库逻辑，可以通过 NAPI 机制在 Native 层操作数据库。

1. 架构分层

• ArkTS UI层：负责界面展示，通过 import testNapi from 'libentry.so' 调用 Native 方法。
• NAPI 绑定层：处理 ArkTS 与 C++ 之间的数据类型转换。
• C++ 数据库操作层：直接调用 OH_Rdb API 或原生 sqlite3 接口执行 SQL。

2. 核心操作流程

• 初始化：在 C++ 侧使用 OH_Rdb_GetOrOpen 打开或创建数据库，配置安全级别和存储路径。
• 数据操作：
  • 插入：通过 OH_Rdb_CreateValuesBucket 创建值桶，填充数据后调用 OH_Rdb_Insert。
  • 查询：调用 OH_Rdb_Query 获取结果，并使用 OH_Cursor 遍历数据。
• 内存管理：在 C++ 层操作完毕后，务必调用 destroy 释放 valueBucket 等资源，防止内存泄漏。

方案三：引入社区三方库（快捷方案）

如果不想从零封装，可以直接通过 OHPM 引入社区成熟的封装库：

• @abner/datastore：支持通过对象形式（而非纯 SQL）创建表和执行增删改查，极大弱化了 SQL 拼接的复杂度，适合快速开发。
• 自研 ORM 框架：部分开发者基于 @ohos/sqlite 封装了类似 Java Bean 注解映射、链式调用（如 query().where().orderBy()）的轻量级 DBHelper，从根本上杜绝 SQL 注入风险。