GoFrame 的 gdb ORM 链式操作

ORM 链式操作

GoFrame 的 gdb 提供了简单灵活的链式操作方式，是框架官方推荐的数据库操作方式。本文档详细介绍各种链式操作的使用方法。

目录

• 模型创建
• 写入保存
• 更新删除
• 数据查询
• 模型关联
• 对象输入
• 字段过滤
• 字段获取
• 事务处理
• 主从切换
• 查询缓存
• 时间维护
• 数据库切换
• Hook特性
• Handler特性
• 锁机制

模型创建

基本用法

// 创建一个用户模型
user := g.Model("user")

// 指定数据库
user := g.Model("user").DB("mydb")

// 带前缀的表名
user := g.Model("prefix_user")

表结构定义

type User struct {
    Id       int    `orm:"id,primary"` // 主键
    Name     string `orm:"name"`       // 名称
    Age      int    `orm:"age"`        // 年龄
    CreateAt string `orm:"create_at"`  // 创建时间
}

写入保存

单条数据写入

// 插入数据
result, err := g.Model("user").Data(g.Map{
    "name": "John",
    "age":  18,
}).Insert()

// Save方法
result, err := g.Model("user").Data(g.Map{
    "id":   1,
    "name": "John",
    "age":  18,
}).Save()

批量数据写入

// 批量插入
data := g.List{
    {"name": "John", "age": 18},
    {"name": "Jane", "age": 20},
}
result, err := g.Model("user").Data(data).Insert()

更新删除

更新操作

// 更新单个字段
result, err := g.Model("user").
    Where("id", 1).
    Data("age", 20).
    Update()

// 更新多个字段
result, err := g.Model("user").
    Where("id", 1).
    Data(g.Map{
        "name": "John",
        "age":  20,
    }).Update()

删除操作

// 硬删除
result, err := g.Model("user").
    Where("id", 1).
    Delete()

// 软删除（需要配置 deletedAt 字段）
result, err := g.Model("user").
    Where("id", 1).
    Unscoped().
    Delete()

数据查询

基本查询

// 单条查询
record, err := g.Model("user").
    Where("id", 1).
    One()

// 多条查询
records, err := g.Model("user").
    Where("age >", 18).
    All()

// 查询数量
count, err := g.Model("user").
    Where("age >", 18).
    Count()

复杂查询

// 条件组合
result, err := g.Model("user").
    Where("age >", 18).
    Where("status", 1).
    WhereOr("vip", 1).
    All()

// 分页查询
result, err := g.Model("user").
    Page(1, 10).
    Order("id DESC").
    All()

模型关联

一对一关联

type User struct {
    *gdb.Model
    Id      int      `orm:"id,primary"`
    Name    string   `orm:"name"`
    Profile *Profile `orm:"with:user_id=id"` // 关联Profile表
}

// 查询带关联数据
user, err := g.Model("user").
    With("Profile").
    Where("id", 1).
    One()

一对多关联

type User struct {
    *gdb.Model
    Id      int       `orm:"id,primary"`
    Name    string    `orm:"name"`
    Orders  []*Order  `orm:"with:user_id=id"` // 关联订单表
}

对象输入

type UserInput struct {
    Name string
    Age  int
}

user := &UserInput{
    Name: "John",
    Age:  18,
}

result, err := g.Model("user").
    Data(user).
    Insert()

字段过滤

// 指定字段
result, err := g.Model("user").
    Fields("id,name").
    All()

// 排除字段
result, err := g.Model("user").
    FieldsEx("password,salt").
    All()

字段获取

// 获取单个字段值
name, err := g.Model("user").
    Where("id", 1).
    Value("name")

// 获取多个字段值
values, err := g.Model("user").
    Fields("id,name").
    Where("age>", 18).
    Array()

事务处理

err := g.DB().Transaction(ctx, func(ctx context.Context, tx *gdb.TX) error {
    // 事务操作1
    _, err := tx.Model("user").Data(g.Map{
        "name": "John",
    }).Insert()
    if err != nil {
        return err
    }
    
    // 事务操作2
    _, err = tx.Model("user_log").Data(g.Map{
        "user_id": 1,
        "action": "register",
    }).Insert()
    return err
})

主从切换

// 强制主库查询
result, err := g.Model("user").
    Master().
    All()

// 强制从库查询
result, err := g.Model("user").
    Slave().
    All()

查询缓存

// 设置查询缓存
result, err := g.Model("user").
    Cache(gdb.CacheOption{
        Duration: time.Hour,
        Name:     "UserList",
    }).All()

// 清除查询缓存
g.Model("user").
    Cache(gdb.CacheOption{
        Name: "UserList",
    }).
    Clear()

时间维护

// 自动维护时间字段
type User struct {
    Id        int       `orm:"id,primary"`
    Name      string    `orm:"name"`
    CreateAt  time.Time `orm:"create_at"`
    UpdateAt  time.Time `orm:"update_at"`
    DeleteAt  time.Time `orm:"delete_at"`
}

数据库切换

// 切换数据库
result, err := g.Model("user").
    DB("backup").
    All()

// 动态切换数据库
result, err := g.Model("user").
    DB(g.DB("backup")).
    All()

Hook特性

type User struct {
    *gdb.Model
}

func (u *User) BeforeInsert(ctx context.Context) error {
    // 插入前的钩子处理
    return nil
}

func (u *User) AfterInsert(ctx context.Context) error {
    // 插入后的钩子处理
    return nil
}

Handler特性

// 注册全局Handler
g.DB().GetCore().SetHandler(gdb.DefaultHandlerGroup{
    BeforeInsert: func(ctx context.Context, in *gdb.HandlerInsertInput) (result gdb.Result, err error) {
        // 插入前的处理
        return nil, nil
    },
    AfterInsert: func(ctx context.Context, in *gdb.HandlerInsertInput) (result gdb.Result, err error) {
        // 插入后的处理
        return nil, nil
    },
})

锁机制

悲观锁

// 共享锁
result, err := g.Model("user").
    Lock().
    Where("id", 1).
    One()

// 排他锁
result, err := g.Model("user").
    LockUpdate().
    Where("id", 1).
    One()

乐观锁

type User struct {
    Id      int `orm:"id,primary"`
    Name    string
    Version int `orm:"version"` // 版本字段
}

// 更新时自动检查版本
result, err := g.Model("user").
    Data(g.Map{
        "name":    "John",
        "version": 2,
    }).
    Where("id", 1).
    Where("version", 1). // 检查版本号
    Update()