HarmonyOS鸿蒙Next中IBest-ORM - 基于SQLite打造的ORM工具库

📖 项目简介

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

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

✨ 核心特性

🎯 专为鸿蒙NEXT定制

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

🛠️ 开发体验优先

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

📊 功能完整

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

🚀 快速开始

安装方式

# 通过npm安装
ohpm install [@ibestservices](/user/ibestservices)/ibest-orm

基本使用示例

import { GetIBestORM } from '[@ibestservices](/user/ibestservices)/ibest-orm';
import { Table, Field, FieldType, Model } from '[@ibestservices](/user/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);

🌟 为什么选择 IBest ORM？

1. 🎯 专业定制

• 专门为鸿蒙NEXT生态系统设计，深度优化性能和兼容性，确保在鸿蒙设备上的最佳表现。

2. 🚀 提高效率

• 更快地开发：简化数据库操作，提高开发效率
• 更少的代码：减少重复的SQL编写工作
• 更丰富的功能：持续更新扩展中

3. 📚 完善生态

• 详细的官方文档
• 丰富的使用示例
• 活跃的社区支持
• 持续的功能更新

4. 🛡️ 稳定可靠

• 完善的错误处理机制
• 全面的测试覆盖
• 生产环境验证

📚 学习资源

官方文档结构

• 快速入门：从安装到第一个示例
• 指南教程：详细的使用指南
• 关系映射：完整的关系处理教程
• 高级功能：事务、迁移、错误处理等
• API参考：完整的API文档

社区资源

• GitHub仓库：https://github.com/ibestservices/ibest-orm
• 在线文档：https://ibest-orm.ibestservices.com
• 三方仓地址：https://ohpm.openharmony.cn/#/cn/detail/@ibestservices%2Fibest-orm
• 示例项目：实际项目中的使用案例

🤝 参与贡献

IBest-ORM 是一个开源项目，欢迎参与社区贡献！

贡献方式

• 提交Issue：报告bug或提出功能建议
• 提交PR：贡献代码或文档改进
• 完善文档：帮助改进文档质量
• 分享经验：在社区分享使用经验和最佳实践

🎉 感谢阅读

IBest-ORM 致力于为鸿蒙开发者提供最优秀的SQLite数据持久化解决方案。无论你是鸿蒙开发新手还是资深开发者，希望这篇文章能够帮助您更好地了解和使用 IBest-ORM，帮助你更高效地构建数据驱动的鸿蒙应用。