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

【鸿蒙优选三方库】@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 命名规范:异步同步接口统一后缀,约定清晰。

六、为什么值得选它?

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

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

相关推荐
码间留白13 分钟前
AI 给的两个方案都被我否了:把 startIcon 与启动遮罩做成同一张图,鸿蒙 APP 冷启动零白屏
性能优化·uni-app·ai编程·harmonyos
二流小码农44 分钟前
鸿蒙开发:证书只能创建3个,第4个应用怎么办
android·ios·harmonyos
威哥爱编程4 小时前
模拟面试智能体开发实战 12:每篇都能跑不等于接起来能跑,端到端联调收官把十一块拼图合成一个能用的智能体
python·agent·harmonyos
威哥爱编程4 小时前
模拟面试智能体开发实战 11:报告只躺在后端怎么复盘,把总评搬上手机还要适配大小屏
python·agent·harmonyos
我闪了个去6 小时前
一个 Scroll 撑起整个首页:HarmonyOS 7 懒加载布局把网格、瀑布流、吸顶分组装进一次滚动
harmonyos·arkts
二流小码农1 天前
鸿蒙开发:router组件升级,彻底告别手动配置
android·ios·harmonyos
威哥爱编程1 天前
模拟面试智能体开发实战 09:把面试官装进手机,鸿蒙端聊天界面用 SSE 流式输出让回复逐字滚出来
python·agent·harmonyos
威哥爱编程1 天前
模拟面试智能体开发实战 10:配置写死在代码里还怎么换服务端,把设置和简历做成界面可配、可存
python·agent·harmonyos
Sirius_Ji2 天前
# 一份鸿蒙原生支持硬解的 ffmpeg 开发基座
harmonyos
贾伟康2 天前
HarmonyOS API 26 Navigation路由栈上限:stackSizeLimit、过载保护与容量观测
harmonyos·arkts·navigation·navpathstack·api26