鸿蒙开源第三方组件 —— IBest-ORM - 基于SQLite打造的鸿蒙ORM工具库原创精华

Groot_

发布于 2025-9-3 15:13

浏览

0收藏

📖 项目简介

IBest-ORM 是一个专门为鸿蒙应用开发设计的简单易用的开源ORM工具库。基于SQLite数据库，它为鸿蒙开发者提供了一套完整的数据持久化解决方案，让数据库操作变得更加简单高效。

官方定位：一个简单易用的鸿蒙开源ORM工具库，基于 @ohos.data.relationalStore 定制的鸿蒙ORM工具库

✨ 核心特性

🎯 专为鸿蒙NEXT定制

原生适配：基于HarmonyOS NEXT开发环境
SQLite专用：深度优化SQLite数据库操作
轻量高效：最小化资源占用，提升应用性能

🛠️ 开发体验优先

简洁API：直观易用的接口设计，降低学习成本
链式调用：支持流畅的方法链式调用
自定义模型：灵活的数据模型定义方式

📊 功能完整

完整CRUD：支持创建、查询、更新、删除操作
关系映射：支持一对一、一对多、多对多、反向关联等复杂关系
事务支持：保证数据一致性和完整性
数据迁移：支持数据库结构自动迁移

🚀 快速开始

安装方式

# 通过npm安装
ohpm install @ibestservices/ibest-orm

基本使用示例

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

@Table
export class User extends Model {
  /**
   * 名字
   */
  @Field({ type: FieldType.TEXT })
  Name?: string
  /**
   * 年龄
   */
  @Field({ type: FieldType.INTEGER })
  Age?: number

  /**
   * 没有被装饰器装饰的字段, 不会被映射成表字段,
   */
  Salary?: number

  constructor(name: string, age: number) {
    super();
    this.Name = name
    this.Age = age
  }
}

@Entry
@Component
export struct DemoPage {
  private db = GetIBestORM();

  onPageShow(){
    this.db.AutoMigrate(User);
    const user = new User("zhangsan", 18);
    this.db.Create(user);

    const valueBucket: relationalStore.ValuesBucket = {
      Name: 'ming',
      Age: 18,
    };
    this.db.Table("User").Insert(valueBucket);
    // Or
    // this.db.Session(User).Insert(valueBucket);
    let result = this.db.Table("User").Where('age', 18).Find();
    // ...
  }

  build(){}
}

🏗️ 核心功能模块

1. 数据模型定义

支持灵活的自定义模型定义，通过装饰器轻松配置表结构：

@Table({name: 'posts'})
class Post {
  @Field({ name: "id", type: FieldType.INTEGER, tag: ['primaryKey', 'autoIncrement', 'notNull'] })
  id: number;
  
  @Field({ type: FieldType.TEXT })
  title: string;
  
  @Field({ type: FieldType.TEXT })
  content: string;
  
  @Field({ type: FieldType.INTEGER })
  userId: number;
}

2. 关系映射

支持完整的关系映射功能：

一对一关系（Has One）：用户与用户资料
一对多关系（Has Many）：用户与文章
反向关联（Belongs To）：文章属于用户
多对多关系（Many to Many）：用户与角色

3. 查询构建器

提供强大的查询构建功能：

// 复杂查询示例
const results = await this.db
  .Select(['id', 'name', 'email'])
  .Where('age', 18)
  .Where('status', ['active', 'pending'])
  .Or('vip_level', 3)
  .OrderByDesc('created_at')
  .Limit(20)
  .Offset(10)
  .Find();

4. 事务处理

确保数据操作的原子性：

this.db.Begin();
// 执行一系列数据库操作
let ref = new User("", 0, 0);
this.db.Table("User").Where('id', 1).First(ref);
if(this.db.GetError()) {
    this.db.Rollback(); // 发生异常时回滚
} else {
    ref.Name = "ZhangSan";
    this.db.Save(ref);
    if(this.db.GetError()) {
        this.db.Rollback(); // 发生异常时回滚
    } else {
        this.db.Commit();  // 没有发生异常时提交
    }
}

5. 数据迁移

AutoMigrate 用于自动迁移您的表结构变化。AutoMigrate 会创建表、添加字段、修改字段和类型. 出于保护您数据的目的，它不会删除未使用的列。

export class User extends Model {
  /**
   * 名字
   */
  @Field({ type: FieldType.TEXT })
  Name?: string
  /**
   * 年龄
   */
  @Field({ type: FieldType.INTEGER })
  Age?: number
}

this.db.AutoMigrate(User);