【鸿蒙优选三方库】@ohos/dataorm：让 HarmonyOS 的数据库操作告别手写 SQL

在鸿蒙应用里做数据持久化，还在为关系型数据库的 SQL 语句头疼？@ohos/dataorm 基于 Android 圈经典 greenDAO 思路打造，用注解定义实体 、一行代码操作数据库 、链式调用拼装查询------让你专注业务，告别样板 SQL。

包名：@ohos/dataorm
当前版本：v2.3.10-rc.1
协议：Apache License 2.0
安装：ohpm install @ohos/dataorm
仓库：gitcode.com/CPF-Applica...

一、它解决了什么问题？

HarmonyOS 应用做本地持久化，常见选择是关系型数据库（RDB）。但直接用原生 RDB Store，会遇到这些痛点：

写 SQL 字符串拼装，易出错且难维护；
表结构变更需要手动处理迁移；
实体 ↔ 数据库映射全部手写；
关联查询（一对多、多对一）写起来痛苦；
批量操作缺乏统一封装；
异步/同步命名混乱。

@ohos/dataorm 把 Java/Kotlin 圈最成熟的 greenDAO 思路搬进 HarmonyOS ArkTS：

用 @Entity、@Id、@Column、@ToMany 等注解声明模型；
编译期生成 Dao 类；
链式 API 拼装查询；
内置迁移、监听、缓存、批量操作工具。

二、核心特点

特性	说明
注解式实体定义	`@Entity`、`@Id`、`@NotNull`、`@Unique`、`@Index` 等
完整关联关系	`@ToMany`、`@ToOne`、`@JoinEntity`、`@OrderBy`
类型转换	`@Convert` 自定义类型 ↔ 数据库值转换
嵌套对象	`@Embedded`、`@Transient`、`@Union`
链式查询	`inquiry().where().eq().and().like().list()`
QueryBuilder 高级	去重、JOIN、分页、计数、排序
数据库迁移	Migration API，平滑升级表结构
监听器	表/库级别数据变更监听
多数据库	单应用支持多个数据库并存
异步/同步	统一 `Async`/`Sync` 命名后缀
DbUtils 工具	读取 rawfile 等常用工具方法

三、适用场景

本地数据存储：用户信息、设置、配置、缓存。
业务实体持久化：订单、商品、文章、聊天记录。
复杂关联模型：一对多（用户-订单）、多对一（订单-商品）、多对多（标签-文章）。
数据迁移需求：版本迭代时表结构平滑升级。
需要监听变化：跨页面/跨组件响应数据变更。
替代手写 SQL：减少样板代码与 SQL 注入风险。
教学/参考：学习鸿蒙 ORM 的完整工程范式。

四、快速上手

1. 安装

bash 复制代码

ohpm install @ohos/dataorm

2. 定义实体（注解）

typescript 复制代码

import { Entity, Id, NotNull, Column, Index } from '@ohos/dataorm'

@Entity({ tableName: 'NOTE' })
export class Note {
  @Id()
  @Column({ columnName: 'ID' })
  id: number = 0

  @NotNull()
  @Column({ columnName: 'TEXT' })
  text: string = ''

  @Column({ columnName: 'COMMENT' })
  comment: string = ''

  @Column({ columnName: 'DATE' })
  date: number = 0
}

3. 初始化数据库

typescript 复制代码

import { DataORM, DatabaseOptions } from '@ohos/dataorm'

const options: DatabaseOptions = {
  name: 'notes.db',
  version: 1,
  entities: [Note]
}

const db = DataORM.init(options)

4. 获取 Dao 与基本 CRUD

typescript 复制代码

const noteDao = db.dao(Note)

// 新增
const note = new Note()
note.text = 'Hello HarmonyOS'
note.date = Date.now()
const id = await noteDao.insert(note)

// 查询
const list = await noteDao.queryBuilder()
  .where(Note.TEXT.like('%Hello%'))
  .orderDesc(Note.DATE)
  .list()

// 更新
note.text = 'Updated'
await noteDao.update(note)

// 删除
await noteDao.deleteById(id)

5. 关联查询（一对多）

typescript 复制代码

@Entity({ tableName: 'USER' })
class User {
  @Id() @Column({ columnName: 'ID' }) id: number = 0
  @Column({ columnName: 'NAME' }) name: string = ''
  @ToMany({ joinEntity: Order.class })
  orders: List<Order> = new List()
}

@Entity({ tableName: 'ORDER' })
class Order {
  @Id() @Column({ columnName: 'ID' }) id: number = 0
  @Column({ columnName: 'USER_ID' }) userId: number = 0
  @ToOne({ joinColumn: 'USER_ID' })
  user: User = new User()
}

五、亮点能力速览

注解声明一切：实体、字段、主键、唯一、索引、关联，全部用装饰器表达。
链式查询 ：类 jOOQ 风格的 inquiry() 链，复杂条件也能优雅拼装。
JOIN 支持：QueryBuilder 原生支持多表连接查询。
数据库迁移 ：版本升级时声明 Migration，工具帮你做表结构变更。
数据监听：表级 / 库级监听器，跨组件响应数据变化。
多数据库并存：单应用可同时维护多个独立数据库。
Async/Sync 命名规范：异步同步接口统一后缀，约定清晰。

六、为什么值得选它？

节省样板代码：注解 + 编译期生成 Dao，让代码量下降一个数量级。
类型安全：ArkTS 强类型贯穿定义、操作、查询全链路。
迁移无忧：版本迭代最怕的"老用户数据库炸了"，Migration API 帮你兜底。
关联模型原生：一对一、一对多、多对多都能优雅表达。
可观测可监听：数据变更触发回调，UI 联动不愁。

如果你的鸿蒙应用需要本地关系型存储，又不想与 SQL 字符串死磕到底------@ohos/dataorm 把 greenDAO 十多年沉淀的 ORM 思想搬到了 HarmonyOS，放心用。