GORM 开发指南

go get -u gorm.io/gorm
go get -u gorm.io/driver/mysql    # MySQL 驱动
go get -u gorm.io/driver/postgres  # PostgreSQL
go get -u gorm.io/driver/sqlite    # SQLite（本地开发）

sqlDB, _ := db.DB()

// 相当于 Hikari 的 maximum-pool-size
sqlDB.SetMaxOpenConns(100)

// 相当于 minimum-idle
sqlDB.SetMaxIdleConns(10)

// 连接最大存活时间（重要！避免长连接被 DB 断开）
sqlDB.SetConnMaxLifetime(time.Hour)

// 连接最大空闲时间
sqlDB.SetConnMaxIdleTime(10 * time.Minute)

db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
    NamingStrategy: schema.NamingStrategy{
        TablePrefix:   "t_",   // 表名加前缀 t_user
        SingularTable: true,    // 禁用复数表名
    },
    Logger: logger.Default.LogMode(logger.Info),
    PrepareStmt: true,              // 启用预编译缓存
})

type User struct {
    ID       uint
    FirstName string `gorm:index:idx_name,priority:1`
    LastName  string `gorm:index:idx_name,priority:2`
    Age      int    `gorm:index:idx_age,,composite:age_group`
}
// 生成复合索引 idx_name(first_name, last_name)

// 只插入指定字段
db.Select("Name", "Age").Create(&user)
// INSERT INTO users (name, age) VALUES ('Alice', 18)

// 排除字段（插入时不包含）
db.Omit("Age").Create(&user)
// INSERT INTO users (name) VALUES ('Alice')

// 批量插入指定条数一批
var users = []User{...}  // 10000 条
db.CreateInBatches(users, 100)  // 每批 100 条

// 条件批量更新
db.Model(User{}).Where("age > ?", 100).Update("active", false)
// UPDATE users SET active=false WHERE age > 100

// 表达式更新（基于当前值）
db.Model(&user).Update("age", gorm.Expr("age + ?", 1))
// UPDATE users SET age=age+1 WHERE id=1

type User struct {
    gorm.Model   // 含 DeletedAt
    Name string
}

db.Delete(&user)
// UPDATE users SET deleted_at='2026-07-12 ...' WHERE id=1

// 查询自动过滤已删除
db.Find(&users)
// SELECT * FROM users WHERE deleted_at IS NULL

// 查询包含已删除
db.Unscoped().Find(&users)
// SELECT * FROM users（无 deleted_at 条件）

// 永久删除
db.Unscoped().Delete(&user)
// DELETE FROM users WHERE id=1

// 字符串条件（最灵活，类似 MyBatis）
db.Where("name = ?", "Alice").First(&user)
db.Where("name LIKE ?", "Al%").Find(&users)
db.Where("age BETWEEN ? AND ?", 18, 30).Find(&users)
db.Where("name IN ?", []string{"Alice", "Bob"}).Find(&users)

// 结构体条件（只认非零值，自动 AND）
db.Where(&User{Name: "Alice", Age: 18}).Find(&users)
// WHERE name = 'Alice' AND age = 18

// Map 条件（认零值）
db.Where(map[string]any{"age": 0}).Find(&users)
// WHERE age = 0

// Not 条件
db.Not("name = ?", "Alice").Find(&users)
// WHERE NOT name = 'Alice'

// Or 条件
db.Where("age = 18").Or("age = 20").Find(&users)
// WHERE age = 18 OR age = 20

// Where 链式（推荐，可读性好）
db.Where("age > ?", 18).
   Where("name LIKE ?", "A%").
   Find(&users)
// WHERE age > 18 AND name LIKE 'A%'

// 内联条件（简洁，适合简单查询）
db.Find(&users, "age > ? AND name LIKE ?", 18, "A%")

// 多个 Where 是 AND 关系
// Or 需要用 .Or() 显式
db.Where("age > 18").
   Or(Where("name = 'Alice'").
            Where("age < 10")).
   Find(&users)
// WHERE age > 18 OR (name = 'Alice' AND age < 10)

// 查询指定列
db.Select("name, age").Find(&users)
// SELECT name, age FROM users

// DISTINCT
db.Distinct("name").Find(&users)
db.Model(&User{}).Distinct("role").Pluck("role", &roles)

// Pluck：查单列到切片（比 Select 简洁）
var names []string
db.Model(&User{}).Pluck("name", &names)
// SELECT name FROM users

// 用 @name 占位
db.Raw("SELECT * FROM users WHERE name = @name AND age > @age",
    sql.Named("name", "Alice"),
    sql.Named("age", 18)).Scan(&users)

// 或用 map
db.Raw("SELECT * FROM users WHERE name = @name",
    map[string]any{"name": "Alice"}).Scan(&users)

// 执行 UPDATE/DELETE/DDL
db.Exec("UPDATE users SET age = age + 1 WHERE id = ?", 1)
db.Exec("DROP TABLE IF EXISTS old_logs")

// 获取影响的行数
result := db.Exec("UPDATE users SET active = 0 WHERE age > 100")
if result.Error == nil {
    fmt.Println(result.RowsAffected())
}

type Article struct {
    ID     uint
    Title  string
    UserID uint
    User   User   // Belongs To
}

var articles []Article
db.Joins("User").Find(&articles)
// SELECT articles.*, User.* FROM articles
//   LEFT JOIN users User ON articles.user_id = User.id

// 带条件的 Joins
db.Joins("User", db.Where(&User{Name: "Alice"})).Find(&articles)

user := User{}
user.ID = 1

// 追加关联
db.Model(&user).Association("Articles").Append(&Article{Title: "new"})

// 替换关联（Many2Many）
db.Model(&user).Association("Tags").Replace(&Tag{Name: "go"}, &Tag{Name: "web"})

// 删除关联（只断开关系，不删记录）
db.Model(&user).Association("Tags").Delete(&tag)

// 清空关联
db.Model(&user).Association("Tags").Clear()

// 关联数量
count := db.Model(&user).Association("Articles").Count()

// 自定义中间表（带额外字段）
type UserTag struct {
    UserID uint `gorm:primaryKey`
    TagID  uint `gorm:primaryKey`
    CreatedAt time.Time
    Note  string
}

type User struct {
    gorm.Model
    Tags []Tag `gorm:many2many:user_tags;`
}

type Tag struct {
    gorm.Model
    Name string
}

tx := db.Begin()
defer func() {
    if r := recover(); r != nil {
        tx.Rollback()
    }
}()

if err := tx.Create(user).Error; err != nil {
    tx.Rollback()
    return err
}

if err := tx.Create(order).Error; err != nil {
    tx.Rollback()
    return err
}

return tx.Commit().Error

// 所有模型的 INSERT 都会经过这个钩子
db.Callback().Create().Before("gorm:create").Register(
    "audit_log",
    func(tx *gorm.DB) {
        log.Println("creating:", tx.Statement.Table)
    })

// 类似 Spring AOP 的 @Around 通知

// 手动建表
db.Migrator().CreateTable(&User{})

// 添加列
db.Migrator().AddColumn(&User{}, "Age")

// 修改列类型
db.Migrator().AlterColumn(&User{}, "Age")

// 添加索引
db.Migrator().CreateIndex(&User{}, "idx_name")

// 删除表
db.Migrator().DropTable("users")

// 检查表是否存在
db.Migrator().HasTable(&User{})

// ❌ N+1：循环里查关联
db.Find(&users)
for _, u := range users {
    db.Model(&u).Related(&u.Articles)  // N 次查询！
}

// ✅ Preload：1 次查询（WHERE user_id IN (...)）
db.Preload("Articles").Find(&users)

db, _ := gorm.Open(mysql.Open(dsn), &gorm.Config{
    PrepareStmt: true,   // 缓存预编译语句
})
// 相同 SQL 第二次执行走预编译，减少解析开销
// 高并发场景提升 20%~30%

// ❌ SELECT * 查出大字段（如 TEXT/BLOB）
db.Find(&users)

// ✅ 只查需要的列
db.Select("id, name, age").Find(&users)

// 批量插入，每批 1000 条
db.CreateInBatches(users, 1000)

// 批量更新用 CASE WHEN（GORM 自动优化）
db.Save(users)

// 批量 upsert（不存在则建，存在则更新）
db.Clauses(clause.OnConflict{
    Columns:   []clause.Column{{Name: "id"}},
    DoUpdates: clause.Assignments(map[string]any{
        "age": 20,
    }),
}).Create(&users)
// INSERT INTO users ... ON DUPLICATE KEY UPDATE age=20

// 开发环境：打印 SQL
db.Debug().Find(&users)

// 生产环境：静默（或只记错误）
db, _ = gorm.Open(mysql.Open(dsn), &gorm.Config{
    Logger: logger.Default.LogMode(logger.Error),
})

// 生成 SQL 但不执行（调试用）
stmt := db.Session(&gorm.Session{DryRun: true}).
    Where("age > ?", 18).Find(&users)

stmt.Statement.SQL.String()
// 输出：SELECT * FROM users WHERE age > ?

// ❌ 想查 age=0 的用户，但 0 被忽略
db.Where(&User{Age: 0).Find(&users)
// 实际：SELECT * FROM users（无 age 条件）

// ✅ 用字符串条件或 map
db.Where("age = ?", 0).Find(&users)
db.Where(map[string]any{"age": 0}).Find(&users)

// ❌ 想把 active 设为 false，但 false 被忽略
db.Updates(User{Active: false})

// ✅ 用 map
db.Updates(map[string]any{"active": false})

// ✅ 或用 Select 强制指定
db.Select("active").Updates(User{Active: false})

// 已软删除的数据查不到
db.Find(&users)  // WHERE deleted_at IS NULL

// ✅ 加 Unscoped 才能查到
db.Unscoped().Find(&users)

// ✅ 永久删除也要 Unscoped
db.Unscoped().Delete(&user)

db.Transaction(func(tx *gorm.DB) error {
    // ❌ 用了外层 db，不在事务中！
    db.Create(user)

    // ✅ 必须用 tx
    return tx.Create(user).Error
})

// ❌ 字符串拼接（SQL 注入风险）
db.Raw("SELECT * FROM users WHERE name = '" + name + "'")

// ✅ 参数化
db.Raw("SELECT * FROM users WHERE name = ?", name)