快速熟悉掌握一个框架/库:

1. 常备文档, 快速查询: gorm文档 https://github.com/go-gorm/gorm.io , 文档在 pages/docs/ 目录下
2. 按照官方文档快速过一遍, 建立索引, 方便进行第一步的 快速查询, 详细见后续的 index 章节
   1. 小技巧: 文档添加到 vscode, 可通过 cmd-p 通过文件名快速查询&打开
3. 常备test环境, 随时随地coding进行细节验证, 并记录
4. 持续步骤3, 最终就能沉淀出 框架/库 的使用指南和最佳实践

本篇 blog 即为 GORM 学习/实践/总结 的成果

资源

https://gorm.io/docs

go get -u gorm.io/gorm
go get -u gorm.io/driver/sqlite
go get -u gorm.io/plugin/soft_delete

• 易错点: struct->忽略0值->指定值

index

• model
• database: driver
• CURD: create query update delete sql_builder
• associations: belongs_to has_one has_many many_to_many associations preload
• tutorial: context err.errors.go method session hook transcation migration logger perf data_type scope convention setting
• advance: dbresolver.多数据源 sharding serializer Prometheus hint index constraint.外键 gorm_config write(plugin.callback driver)

model 定义

• type
  • Go基础类型
  • pointer alia
  • custom types implementing Scanner and Valuer interfaces
• Convention.约定
  • ID as primary key
  • pluralizes struct name to snake_cases as table name, snake_case as column name -> json默认和struct一致, 需要手动指定
  • uses CreatedAt, UpdatedAt to track creating/updating time
• 日期时间
  • datetime/date/timesatmp -> time.Time, 运算使用 carbon 库
  • time -> 使用 string
  • 不推荐null, 可以为null使用指针或者对应对应null类型
• mark
  • tag: gorm:"-".ignore
  • 内嵌字段 gorm.Model
  • gorm:"default:galeone": insert + 0值 时使用
  • 由于TableName()仅在初次解析后即缓存，后续不再解析，因此无法通过TableName()来实现动态表名，但可以通过Table()来实现动态表名

-- 建表语句推荐
CREATE TABLE `tdb_person` (
    -- 默认字段
    `id`          bigint unsigned NOT NULL AUTO_INCREMENT primary key,
    `create_at`   datetime                 DEFAULT CURRENT_TIMESTAMP, -- 使用数据库自动更新
    `update_at`   datetime                 DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    `delete_at`   datetime,
    `is_del`      tinyint not null default 0,

    -- 基础数据类型
    `username`    varchar(32)     NOT NULL DEFAULT '' COMMENT '用户名',
    `sex`         tinyint         NOT NULL DEFAULT '0' COMMENT '性别',
    `email`       varchar(255)    NOT NULL DEFAULT '' COMMENT '邮箱',
    `person_type` tinyint                  DEFAULT NULL, -- 验证null字段, 数据库不推荐null

    -- 日期时间: 默认都为null, 需要显式设置
    `in_date`     date            NOT NULL COMMENT '进入日期',
    `in_time`     time            NOT NULL COMMENT '进入时间',
    `in_dt`       datetime        NOT NULL COMMENT '进入日期时间',
    `in_ts`       int             NOT NULL COMMENT '进入时间戳',

    UNIQUE KEY `uni_username` (`username`),
    KEY `idx_create_at` (`create_at`),
    KEY `idx_update_at` (`update_at`)
) COMMENT ='tdb-person';

import (
    "time"

    "gorm.io/gorm"
    "gorm.io/plugin/soft_delete"
)

type Model struct {
    Id       uint      `gorm:"primarykey" json:"id"`
    CreateAt time.Time `gorm:"->" json:"create_at"`
    UpdateAt string    `gorm:"->" json:"update_at"`
    DeleteAt gorm.DeletedAt `json:"delete_at"`
    IsDel    soft_delete.DeletedAt `gorm:"softDelete:flag,DeletedAtField:DeleteAt" json:"is_del"` // use `1` `0`
}


type PersonModel struct {
    Model
    Username   string
    Sex        int
    Email      string
    PersonType *int

    InDate time.Time
    InDt   time.Time
    InTime string
    InTs   int64

  More string `gorm:"-"` // 数据库没有字段
}

// gorm.Model
type Model struct {
    ID        uint `gorm:"primarykey"`
    CreatedAt time.Time
    UpdatedAt time.Time
    DeletedAt DeletedAt `gorm:"index"`
}

读

• 书写顺序 -> 默认和sql保持一致 select xxx from xxx where xxx order by xxx limit xxx
• T表示model的struct D表示对应model的DAO的struct定义

db.
Model(&M{}). // 查询结果指定T可省略model; *T/T 指定id查询;  Table() ❌ 不推荐
Select(). // 推荐使用 string; 根据定义的struct返回
Where(). // 避免fmt导致sql注入
Order().
Limit().Offset()
.Take() // 获取结果 -> 主键/where

• where: id []id str map struct.0值.指定字段 Scopes
• result
  • Error
  • 返回值: 单个值 *T []*T map[string]any []map[string]any
    • 单个值: 使用 int 而非 type Status int
  • row: Take First Last
    • db.Limit(1).Find(&user): ErrRecordNotFound 必须使用Limit.Find会查询出所有数据
  • rows: Find Scan FindInBatches
  • 单列: Distinc().Pluck("xxx")
  • Distinc("xxx").Count()
• 其他
  • Join() Joins() ❌ 不推荐: 没必要再学习一个 queryBuild 语法
  • FirstOrInit FirstOrCreate

func (d *D) Get(id) (*T, error) {
  var row T
  err := db.Take(&row, 1).Error
  if err != nil {
    if errors.Is(err, gorm.ErrRecordNotFound) {
      return nil, err
    }
    return nil, err
  }
  return &row, nil
}

func (d *D) List(id) (*T, error) {
  var row []*T
  err := db.Find(&row).Error
  if err != nil {
    if errors.Is(err, gorm.ErrRecordNotFound) {
      return nil, err
    }
    return nil, err
  }
  return &row, nil
}

写

• create: Create(&row) Create(&rows) Omit()/Select() CreateInBatches(users, 100) upsert
• update: Save.所有字段 Update.单列 Updates.多列(map struc.0值.指定列) ErrMissingWhereClause.wherer("1=1") UpdateColumn.UpdateColumns
• delete: Delete(*T id []id) ErrMissingWhereClause ReturnDeletedRows.Delete(&rows)
  • SoftDelete: gorm.DeletedAt db.Unscoped().Where() db.Unscoped().Delete()
• sql_builder: Raw().Exce() Raw().Scan() ToSQL

user := User{Name: "Jinzhu", Age: 18, Birthday: time.Now()}

result := db.Create(&user) // pass pointer of data to Create

user.ID             // returns inserted data's primary key
result.Error        // returns error
result.RowsAffected // returns inserted records count

more

• soft_delete

• transcation

db.Transaction(func(tx *gorm.DB) error { // begin
  if err := tx.Create(&Animal{Name: "Giraffe"}).Error; err != nil {
    return err // rollback
  }
  if err := tx.Create(&Animal{Name: "Lion"}).Error; err != nil {
    return err
  }
  return nil // commit
})

• gorm中有3类method: chain finisher session -> *gorm.DB 使用 session 方法来共享 chain

db, err := gorm.Open(sqlite.Open("test.db"), &gorm.Config{})

db.Where("name = ?", "jinzhu").Where("age = ?", 18).Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu' AND age = 18;
db.Where("name = ?", "jinzhu2").Where("age = ?", 20).Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu2' AND age = 20;
db.Find(&users)
// SELECT * FROM users;

tx := db.Where("name = ?", "jinzhu")
tx.Where("age = ?", 18).Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu' AND age = 18;
tx.Where("age = ?", 28).Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu' AND age = 18 AND age = 28; ❌

// session
tx := db.Where("name = ?", "jinzhu").Session(&gorm.Session{})
tx := db.Where("name = ?", "jinzhu").WithContext(context.Background())
tx := db.Where("name = ?", "jinzhu").Debug()
tx.Where("age = ?", 18).Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu' AND age = 18;
tx.Where("age = ?", 28).Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu' AND age = 28;

• scope

func TableOfYear(user *User, year int) func(db *gorm.DB) *gorm.DB {
  return func(db *gorm.DB) *gorm.DB {
    tableName := user.TableName() + strconv.Itoa(year)
    return db.Table(tableName)
  }
}

DB.Scopes(TableOfYear(user, 2019)).Find(&users)
// SELECT * FROM users_2019;