🐘 GORM 中文使用手册（简化实战版）

适用于实际项目开发场景，包含常见查询、更新、事务等操作。

---

🔧 基本结构

假设我们有一个用户模型：

type User struct {
    ID     uint   `gorm:"primaryKey"`
    Name   string
    Phone  string
    Status int
}

func (User) TableName() string {
    return "users"
}

---

📌 1. 模型上下文：Model()

db.Model(&User{}) // 明确操作 users 表

常用于：

• 更新（Update / Updates）
• 聚合统计（Count）
• 插入非结构体数据（如 []map[string]interface{}）

---

🔍 2. 查询操作

2.1 查询单个（First）

var user User
err := db.Where("id = ?", 1).First(&user).Error

2.2 查询多个（Find）

var users []User
err := db.Where("status = ?", 1).Find(&users).Error

2.3 查询字段（Select）

db.Select("id", "name").Where("status = ?", 1).Find(&users)

2.4 排序 + 分页

db.Order("created_at desc").Limit(10).Offset(20).Find(&users)

---

✏️ 3. 更新操作

3.1 更新单字段（Update）

db.Model(&User{}).Where("id = ?", 1).Update("phone", "13900000000")

3.2 批量更新字段（Updates）

db.Model(&User{}).Where("status = ?", 1).Updates(map[string]interface{}{
    "status": 2,
    "phone":  "13900000000",
})

---

➕ 4. 插入操作

4.1 单条插入

db.Create(&User{Name: "Tom", Phone: "13900000000"})

4.2 批量插入

users := []User{...}
db.CreateInBatches(users, 100)

---

❌ 5. 删除操作

db.Where("id = ?", 1).Delete(&User{})

---

🔄 6. 事务处理

err := db.Transaction(func(tx *gorm.DB) error {
    if err := tx.Create(&user).Error; err != nil {
        return err
    }
    if err := tx.Model(&Account{}).Where("uid = ?", user.ID).Update("balance", gorm.Expr("balance - ?", 100)).Error; err != nil {
        return err
    }
    return nil
})

---

🔁 7. 条件构造（Where/Or）

db.Where("status = ?", 1).Or("name LIKE ?", "%Tom%").Find(&users)

db.Where(map[string]interface{}{"name": "Tom", "status": 1}).Find(&users)

---

✅ 8. 判断记录是否存在

err := db.First(&user, "phone = ?", "13900000000").Error
if errors.Is(err, gorm.ErrRecordNotFound) {
    // 未查到
}

---

🧪 9. 原生 SQL

type Result struct {
    Name  string
    Count int
}

db.Raw("SELECT name, COUNT(*) as count FROM users GROUP BY name").Scan(&results)

---

💡 10. GORM 最佳实践建议

建议	理由
使用 Model(&Type{}) 明确表结构	增强可读性和类型推断
使用 WithContext(ctx) 传递链路上下文	支持超时、追踪等
errors.Is(err, gorm.ErrRecordNotFound) 判断未命中	避免错误处理不当
不用 ID == 0 判断“未找到”	有副作用风险
更新用 Updates(map[string]interface{})	更灵活清晰
写入使用 CreateInBatches	批量性能更佳
使用事务包裹多操作逻辑	保证原子性

---

📚 附加资源

• GORM 官方文档
• GORM GitHub

• 常用 GORM 插件：

  • gorm-gen：代码生成工具
  • gorm-tracer：链路追踪
  • gorm-logger：日志增强

---

如果你需要，我可以继续帮你：

1. 生成 企业内训 GORM 手册 PDF
2. 提供 GORM 项目脚手架模板
3. 封装 GORM Repository 模板代码

是否继续？你希望文档以 PDF、Markdown 还是在线文档格式呈现？