在鸿蒙（HarmonyOS）应用开发中，数据持久化是核心环节。直接使用原生的关系型数据库（relationalStore）进行开发，往往需要手动编写大量易错的 SQL 语句，并频繁进行业务对象与 ValueBucket 之间的复杂映射。为了解决这些痛点，鸿蒙生态提供了多种 ORM（对象关系映射）方案，让开发者能以面向对象的方式操作数据库，大幅提升开发效率。

一、 官方原生 ORM 框架

鸿蒙系统内置了基于 SQLite 的对象关系映射数据库框架，屏蔽了底层的 SQL 操作，提供了一系列面向对象的增删改查接口。

• 核心组件：包含被 @Database 注解修饰的数据库类、被 @Entity 注解修饰的实体对象，以及用于执行操作的 OrmContext 和谓词接口（OrmPredicate）。
• 运作机制：通过将实例对象映射到关系表上，开发者只需操作对象的属性和方法即可完成数据库的增删改查，无需与复杂的 SQL 语句打交道。

二、 社区与生态开源 ORM 库

除了官方原生方案，鸿蒙生态中还涌现了多款优秀的第三方 ORM 框架，进一步丰富了开发者的选择：

• dataORM：一款支持链式调用的关系映射数据库，提供了一行代码操作数据库的能力，支持备份、升级、缓存等特性，通过 @Entity、@Columns 等注解定义表结构。
• IBest-ORM：专为鸿蒙 NEXT 定制的轻量级开源 ORM 工具库。支持流畅的方法链式调用、一对一/一对多/多对多等复杂关系映射，并内置了 AutoMigrate 自动迁移功能，可自动处理表结构的创建与字段更新。
• RdbStore 声明式组件：由头部资讯伙伴共建的分布式数据库组件，通过声明式配置与 Entity 类自动映射表结构，彻底避免了手写 SQL 的繁琐，在鸿蒙版封面新闻等应用中实现了首屏数据的“瞬时呈现”。
• 字节 rdbStore 组件：专为鸿蒙生态设计的轻量级 ORM 组件，基于原生 relationalStore 接口封装，提供了高效开发、自动迁移、日志采集与调优等核心能力。

三、 核心封装能力与优势

优秀的 ORM 框架通常具备以下核心能力：

• 声明式表结构定义：通过装饰器（如 @Entity、@Field、@Column）直接将实体类映射为数据库表，自动处理主键、自增、非空及唯一约束等属性。
• 链式查询构建器：提供直观的 API（如 .Where().OrderByDesc().Limit().Find()），支持复杂条件的组合查询，极大提升代码可读性。
• 自动化结构迁移：在应用版本迭代时，ORM 框架可自动对比实体类的变化，执行添加字段或修改类型等升级操作，免去手动编写 onUpgrade SQL 的痛苦。
• 事务与关系映射：支持事务的原子性操作（Begin/Commit/Rollback），并能通过注解轻松建立实体间的一对多、多对多等关联关系。

四、官方原生 ORM 实战：声明式实体与谓词查询

场景：使用鸿蒙官方内置的 ORM 框架，通过 @Entity 等装饰器定义表结构，并利用 OrmPredicate 构建类型安全的查询条件，彻底告别手写 SQL。

import { relationalStore, orm } from '@kit.ArkData';

// 1. 声明式定义实体对象（对应数据库表）
@Entity('users')
class User extends orm.OrmObject {
    @PrimaryKey({ autoIncrement: true })
    id: number = 0;

    @Column({ name: 'user_name' })
    name: string = '';

    @Column({ name: 'user_age' })
    age: number = 0;
}

// 2. 使用谓词进行类型安全的查询
const predicates = new orm.OrmPredicate('users');
predicates.equalTo('user_age', 18).orderByAsc('id').limit(10);

// 执行查询
const users = await ormContext.query(predicates, User);

五、字节 rdbStore 实战：DTO 映射与自动迁移

场景：引入字节跳动开源的 rdbStore 组件，利用 DTO（数据传输对象）进行数据库操作，实现自动建表与平滑升级，并支持批量操作。

import { Rdb } from 'rdbstore';

// 1. 初始化数据库并开启自动迁移
const database = Rdb.databaseBuilder(context, {
    version: 2,
    dbName: 'app.db',
    entities: [UserEntity],
    autoMigrate: true // 自动处理表结构变更
}).build();

// 2. 基于 DTO 的批量插入与局部更新
const userDao = database.getDao(UserEntity);

// 批量插入
await userDao.batchInsert([user1, user2, user3]);

// 局部更新（仅更新指定字段，避免全量覆盖）
const values: relationalStore.ValuesBucket = { 'user_age': 26 };
await userDao.updatePartial(values, existingUser);

六、OCORM 实战：Schema-First 与关联预加载

场景：使用 @offlinecat/ocorm 框架，采用显式 Schema 定义（摒弃运行时反射），并通过 QueryBuilder 实现复杂的一对多关联数据预加载。

import { defineEntity, Repository, ConditionOperator } from '@offlinecat/ocorm';

// 1. 显式定义表结构（Schema-First）
defineEntity('User', {
    tableName: 'users',
    columns: [
        { property: 'id', primaryKey: true, autoIncrement: true },
        { property: 'name', type: ColumnType.TEXT, nullable: false }
    ]
});

// 2. 链式查询并自动预加载关联的订单数据（Eager Loading）
const userRepo = new Repository('User');
const users = await userRepo.createQueryBuilder()
    .where('status', ConditionOperator.EQUAL, 1)
    .with('orders') // 自动 JOIN 并填充 orders 数组
    .orderBy('createdAt', 'DESC')
    .limit(20)
    .getMany();

七、IBest-ORM 实战：极简链式调用与事务控制

场景：在鸿蒙 NEXT 环境下，使用 IBest-ORM 进行直观的数据模型定义，并利用其强大的链式查询构建器和事务机制，确保复杂业务逻辑下的数据一致性。

import { GetIBestORM, Table, Field, FieldType, Model } from '@ibestservices/ibest-orm';

// 1. 通过装饰器极简定义数据模型
@Table
export class User extends Model {
    @Field({ type: FieldType.TEXT })
    Name?: string;

    @Field({ type: FieldType.INTEGER })
    Age?: number;
}

// 2. 链式查询与事务处理实战
const db = GetIBestORM();

// 自动迁移表结构
db.AutoMigrate(User);

// 复杂链式查询：筛选年龄为18的用户，按创建时间倒序，分页获取
const users = db.Table("User")
    .Where('Age', 18)
    .OrderByDesc('created_at')
    .Limit(20)
    .Offset(0)
    .Find();

// 事务控制：保证批量操作的原子性
db.Begin();
try {
    db.Table("User").Insert({ Name: 'Alice', Age: 22 });
    db.Table("User").Insert({ Name: 'Bob', Age: 25 });
    db.Commit(); // 全部成功则提交
} catch (error) {
    db.Rollback(); // 发生异常则回滚，防止脏数据
}

八、原生 RdbStore 高阶实战：手写 SQL 与批量事务

场景：当 ORM 无法满足极度复杂的查询需求（如多表联查、复杂聚合统计）时，直接使用鸿蒙原生 relationalStore 执行手写 SQL，并结合事务提升批量写入性能。

import { relationalStore } from '@kit.ArkData';

// 1. 复杂 SQL 联表查询
const sql = `SELECT u.name, o.order_no 
             FROM users u 
             JOIN orders o ON u.id = o.user_id 
             WHERE u.age > ? AND o.status = ?`;

const resultSet = await rdbStore.querySql(sql, ['18', 'PAID']);

// 2. 批量插入与事务优化（性能提升数倍）
rdbStore.beginTransaction();
try {
    for (let i = 0; i < 1000; i++) {
        const bucket: relationalStore.ValuesBucket = {
            'name': `User_${i}`,
            'age': 20 + (i % 10)
        };
        await rdbStore.insert('users', bucket);
    }
    rdbStore.commit(); // 批量提交
} catch (err) {
    rdbStore.rollback(); // 失败回滚
}

九、 轻量级 KV 存储实战：分布式偏好设置

场景：并非所有数据都需要关系型数据库。对于用户偏好设置、Token 缓存等简单的键值对数据，使用鸿蒙原生的 distributedKVStore 性能更高，且天然支持多设备间的数据自动同步。

import { distributedKVStore } from '@kit.ArkData';

// 1. 创建 KV 管理器与 Store
const kvManager = distributedKVStore.createKVManager({
    bundleName: 'com.example.myapp',
    context: getContext()
});

const kvStore = await kvManager.getKVStore('user_preferences', {
    createIfMissing: true,
    encrypt: true, // 开启加密，适合存储敏感 Token
    kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION
});

// 2. 极简的读写操作
await kvStore.put('theme_mode', 'dark');
const theme = await kvStore.get('theme_mode') as string; // 输出: dark