471 lines
13 KiB
Markdown
471 lines
13 KiB
Markdown
---
|
||
tags: [DEV, GO, golang, GORM, backend, ORM, database]
|
||
create time: 2026-04-22 10:00
|
||
---
|
||
|
||
# GORM - Go 语言 ORM 框架
|
||
|
||
## 概述
|
||
|
||
GORM 是 Go 语言中最流行的 ORM（对象关系映射）框架，由 [@jinzhu](https://github.com/jinzhu) 创建。它基于 `database/sql` 构建，提供了链式 API、关联预加载、插件扩展等特性，让 Go 开发者以符合 Go 风格的方式高效操作数据库。
|
||
|
||
> **思考**：为什么在有了 `database/sql` 标准库之后，还需要 GORM 这样的 ORM？ORM 的价值是什么？它的代价又是什么？
|
||
|
||
ORM 的核心价值在于**将数据库表映射为结构体**，用面向对象的方式操作数据，减少样板 SQL 代码。代价是：理解 ORM 生成的 SQL 至关重要，复杂查询场景下仍需手写 SQL。
|
||
|
||
## 安装与初始化
|
||
|
||
```bash
|
||
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 驱动
|
||
```
|
||
|
||
```go
|
||
import (
|
||
"gorm.io/gorm"
|
||
"gorm.io/driver/mysql"
|
||
)
|
||
|
||
// MySQL 连接
|
||
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
|
||
if err != nil {
|
||
panic("failed to connect database")
|
||
}
|
||
```
|
||
|
||
## 定义模型
|
||
|
||
```go
|
||
type User struct {
|
||
ID uint `gorm:"primaryKey"` // 主键，自动命名为 id
|
||
Name string `gorm:"size:255;not null"` // 非空 + 字段长度
|
||
Email string `gorm:"uniqueIndex"` // 唯一索引
|
||
Age int `gorm:"default:0"` // 默认值
|
||
Role string `gorm:"default:'user'"`
|
||
CreatedAt time.Time // 自动管理 CreatedAt
|
||
UpdatedAt time.Time // 自动管理 UpdatedAt
|
||
DeletedAt gorm.DeletedAt // 软删除支持
|
||
}
|
||
```
|
||
|
||
**GORM 约定**：
|
||
|
||
| 约定 | 说明 |
|
||
|------|------|
|
||
| 表名 | 结构体名的复数形式（`User` → `users`），可通过 `TableName()` 重写 |
|
||
| 主键 | 名为 `ID` 的字段自动作为主键，类型推断为 `INT UNIQUE PRIMARY KEY` |
|
||
| 字段名 | Go 字段名 → snake_case 的列名（`UserName` → `user_name`） |
|
||
| CreatedAt/UpdatedAt | 自动填充时间戳（可通过 `DisableCreateTimeIndex` / `DisableUpdateTimeIndex` 关闭） |
|
||
|
||
## CRUD 操作
|
||
|
||
### 创建
|
||
|
||
```go
|
||
user := User{Name: "Alice", Age: 25, Role: "admin"}
|
||
result := db.Create(&user) // 返回 *gorm.Result
|
||
|
||
// 批量创建（一次 INSERT）
|
||
users := []User{
|
||
{Name: "Bob", Age: 30},
|
||
{Name: "Carol", Age: 28},
|
||
}
|
||
db.Create(&users) // GORM 自动优化为批量 INSERT
|
||
```
|
||
|
||
### 查询
|
||
|
||
```go
|
||
// 单一查询
|
||
var user User
|
||
db.First(&user, 10) // 主键查询
|
||
db.First(&user, "name = ?", "Alice") // 条件查询
|
||
db.Where("age > ?", 20).First(&user) // Where 链式
|
||
|
||
// 多结果查询
|
||
var users []User
|
||
db.Where("role = ?", "user").Find(&users)
|
||
|
||
// 链式条件
|
||
db.Where("role = ?", "admin").
|
||
Where("age >= ?", 25).
|
||
Order("age desc").
|
||
Limit(10).
|
||
Offset(20).
|
||
Find(&users)
|
||
```
|
||
|
||
**GORM 查询 API 速查**：
|
||
|
||
| 方法 | 等价 SQL |
|
||
|------|----------|
|
||
| `First` / `Take` | `LIMIT 1`，找第一条 |
|
||
| `Last` | `ORDER BY PRIMARY KEY DESC LIMIT 1` |
|
||
| `Find` | `SELECT * FROM ...` |
|
||
| `Where` | `WHERE ...` |
|
||
| `Or` | `OR ...` |
|
||
| `Not` | `NOT ...` |
|
||
| `Order` | `ORDER BY ...` |
|
||
| `Select` | `SELECT col1, col2` |
|
||
| `Group` / `Having` | `GROUP BY` / `HAVING` |
|
||
| `Joins` | `JOIN ...` |
|
||
| `Scan` | 扫描到自定义结构体 |
|
||
|
||
> **注意**：`First`、`Last` 在没有数据时返回 `gorm.ErrRecordNotFound`，务必处理此错误。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["db.Model(&User{})"] --> B["Where 条件过滤"]
|
||
B --> C["Order 排序"]
|
||
C --> D["Select 字段选择"]
|
||
D --> E["Limit/Offset 分页"]
|
||
E --> F["Group/Having 分组"]
|
||
F --> G["Preload 预加载关联"]
|
||
G --> H["Find/First/Last 执行"]
|
||
H --> I["Scan 扫描到结构体"]
|
||
|
||
classDef start fill:#4285f4,color:#fff
|
||
classDef step fill:#f1f3f4,stroke:#333
|
||
classDef finish fill:#34a853,color:#fff
|
||
class A start
|
||
class I finish
|
||
class B,C,D,E,F,G,H step
|
||
```
|
||
|
||
> **链式 API 的本质**：每个方法返回 `*gorm.DB` 对象，不断累积查询条件，最终 `Find`/`First` 时才组装并执行 SQL。
|
||
|
||
### 更新
|
||
|
||
```go
|
||
// 更新单个字段
|
||
db.Model(&user).Update("name", "Alice Updated")
|
||
|
||
// 更新多个字段
|
||
db.Model(&user).Updates(User{Name: "Alice V2", Age: 26, Role: "superadmin"})
|
||
|
||
// 带条件的更新
|
||
db.Where("age > ?", 18).Model(&user).Update("role", "adult")
|
||
|
||
// 用 map 更新（会跳过零值字段，慎用）
|
||
db.Model(&user).Updates(map[string]interface{}{"name": "New", "age": 30})
|
||
```
|
||
|
||
### 删除
|
||
|
||
```go
|
||
// 软删除（推荐）
|
||
db.Delete(&user) // 设置 DeletedAt = now()，而非物理删除
|
||
|
||
// 硬删除
|
||
db.Unscoped().Delete(&user) // 物理删除
|
||
|
||
// 批量删除
|
||
db.Where("age < ?", 18).Delete(&User{})
|
||
```
|
||
|
||
## 关联（Associations）
|
||
|
||
GORM 支持三种关联关系，通过标签定义。
|
||
|
||
```go
|
||
type User struct {
|
||
gorm.Model
|
||
Name string
|
||
Role string
|
||
CreditCards []CreditCard `gorm:"foreignKey:UserID"` // HasMany
|
||
}
|
||
|
||
type CreditCard struct {
|
||
gorm.Model
|
||
Number string
|
||
UserID uint `gorm:"not null"` // 外键
|
||
}
|
||
```
|
||
|
||
### 三种关联类型
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph User 用户
|
||
U1["ID\nName\nRole"]
|
||
end
|
||
|
||
subgraph CreditCard 信用卡
|
||
C1["ID\nNumber\nUserID (FK)"]
|
||
end
|
||
|
||
subgraph Profile 个人资料
|
||
P1["ID\nBio\nUserID (FK)"]
|
||
end
|
||
|
||
subgraph Language 语言[关联表: user_languages]
|
||
L1["ID\nName"]
|
||
UM["user_id"]
|
||
LM["language_id"]
|
||
end
|
||
|
||
U1 -->|"1:N HasMany"| C1
|
||
U1 -->|"1:1 HasOne"| P1
|
||
U1 -.->|"N:M BelongsToMany"| L1
|
||
|
||
classDef user fill:#4285f4,stroke:#336,stroke-width:2px,color:#fff
|
||
classDef card fill:#ea4335,stroke:#c33,stroke-width:2px,color:#fff
|
||
classDef profile fill:#34a853,stroke:#264,stroke-width:2px,color:#fff
|
||
classDef lang fill:#fbbc04,stroke:#cc8,stroke-width:2px,color:#333
|
||
|
||
class U1 user
|
||
class C1 card
|
||
class P1 profile
|
||
class L1 lang
|
||
```
|
||
|
||
> **关键理解**：标签写在**一端**，GORM 会根据外键位置自动判断关系方向。
|
||
|
||
- **HasOne**：外键在对方模型（`Profile.UserID`）→ 写在 `User` 上用 `hasOne`
|
||
- **HasMany**：外键在对方模型（`CreditCard.UserID`）→ 写在 `User` 上用 `hasMany`
|
||
- **BelongsTo**：外键在当前模型 → 写在「从属」一方
|
||
- **BelongsToMany**：需要中间关联表（`user_languages`）
|
||
|
||
| 关联类型 | 标签方式 | 示例 |
|
||
|----------|----------|------|
|
||
| **HasOne** | 外键在对方模型 | `Profile` 包含 `UserID`，`User` 通过 `HasOne` 关联 |
|
||
| **HasMany** | 外键在对方模型 | `CreditCards` 数组，`CreditCard` 包含 `UserID` |
|
||
| **BelongsTo** | 外键在当前模型 | `CreditCard` 包含 `UserID`，`BelongsTo` 指向 `User` |
|
||
| **BelongsToMany** | 需要通过关联表 | `User` ↔ `Languages`（多对多） |
|
||
|
||
### 预加载（Preloading）
|
||
|
||
```go
|
||
// N+1 问题：一次查询 N 条关联记录
|
||
db.Preload("CreditCards").Find(&users)
|
||
// 生成 2 条 SQL：SELECT * FROM users; SELECT * FROM credit_cards WHERE user_id IN (...)
|
||
|
||
// 嵌套预加载
|
||
db.Preload("CreditCards").
|
||
Preload("Profile").
|
||
Find(&users)
|
||
|
||
// 带条件的预加载
|
||
db.Preload("CreditCards", "type = ?", "premium").Find(&users)
|
||
|
||
// 使用 Joins 预加载（生成 INNER JOIN，减少查询次数）
|
||
db.Joins("Profile").Find(&users)
|
||
```
|
||
|
||
> **核心原则**：批量查询时务必使用 `Preload`，否则会在循环中触发 N+1 查询问题。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph Bad ["❌ 不使用 Preload - N+1 问题"]
|
||
direction TB
|
||
S1["SQL 1: SELECT * FROM users"] --> Loop["循环 N 次"]
|
||
Loop --> S2["SQL 2: SELECT * FROM credit_cards WHERE user_id=1"]
|
||
Loop --> S3["SQL 3: SELECT * FROM credit_cards WHERE user_id=2"]
|
||
Loop --> S4["SQL N: SELECT * FROM credit_cards WHERE user_id=N"]
|
||
end
|
||
|
||
subgraph Good ["✅ 使用 Preload - 2 条 SQL"]
|
||
direction TB
|
||
G1["SQL 1: SELECT * FROM users"] --> G2["SQL 2: SELECT * FROM credit_cards WHERE user_id IN (1,2,...,N)"]
|
||
end
|
||
```
|
||
|
||
## 多对多关联（BelongsToMany）
|
||
|
||
```go
|
||
type User struct {
|
||
gorm.Model
|
||
Name string
|
||
Languages []Language `gorm:"many2many:user_languages;"`
|
||
}
|
||
|
||
type Language struct {
|
||
gorm.Model
|
||
Name string
|
||
}
|
||
|
||
// 自动创建关联表 user_languages（字段：user_id, language_id）
|
||
// 插入关联数据
|
||
db.Model(&user).Association("Languages").Append(&Language{Name: "Go"})
|
||
|
||
// 查询关联
|
||
db.Preload("Languages").Find(&users)
|
||
|
||
// 替换关联
|
||
db.Model(&user).Association("Languages").Replace(
|
||
&Language{Name: "Python"}, &Language{Name: "Rust"},
|
||
)
|
||
```
|
||
|
||
## 高级查询技巧
|
||
|
||
### Raw SQL & 条件构造
|
||
|
||
```go
|
||
// 原生 SQL
|
||
db.Raw("SELECT name, SUM(amount) FROM orders WHERE status = ? GROUP BY name", "PAID").
|
||
Scan(&results)
|
||
|
||
// 条件表达式
|
||
db.Where(
|
||
"name LIKE ? AND age BETWEEN ? AND ?", "%jon%", 20, 30,
|
||
).Find(&users)
|
||
|
||
// IN 查询
|
||
db.Where("id IN ?", []int{1, 2, 3}).Find(&users)
|
||
|
||
// 子查询
|
||
subQuery := db.Model(&Order).Select("user_id").Where("amount > ?", 100)
|
||
db.Where("id IN (?)", subQuery).Find(&users)
|
||
```
|
||
|
||
### 事务
|
||
|
||
```go
|
||
tx := db.Begin() // 注意：事务中需使用 tx 而非 db
|
||
|
||
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
|
||
```
|
||
|
||
> **关键点**：事务内的所有操作必须使用事务句柄 `tx`，而非全局 `db`。
|
||
|
||
### 自定义表名与列名
|
||
|
||
```go
|
||
func (User) TableName() string {
|
||
return "app_users" // 不使用复数形式
|
||
}
|
||
|
||
// 列名自定义
|
||
type User struct {
|
||
ID int `gorm:"column:uid"`
|
||
Name string `gorm:"column:username"`
|
||
}
|
||
```
|
||
|
||
### Scope（可复用查询片段）
|
||
|
||
```go
|
||
func AmountGT(amount int) func(db *gorm.DB) *gorm.DB {
|
||
return func(db *gorm.DB) *gorm.DB {
|
||
return db.Where("amount > ?", amount)
|
||
}
|
||
}
|
||
|
||
func Active() func(db *gorm.DB) *gorm.DB {
|
||
return func(db *gorm.DB) *gorm.DB {
|
||
return db.Where("status = ?", "active")
|
||
}
|
||
}
|
||
|
||
// 使用
|
||
db.Scopes(AmountGT(100), Active()).Find(&orders)
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
### 1. Select 指定字段
|
||
|
||
```go
|
||
// 只查询需要的字段，避免加载大字段（如 text/blob）
|
||
db.Select("name", "age").Find(&users)
|
||
```
|
||
|
||
### 2. 批量操作
|
||
|
||
```go
|
||
// 批量写入：1次 INSERT N行，而非 N次 INSERT
|
||
db.Create(&users)
|
||
|
||
// 批量更新：1次 UPDATE
|
||
db.Model(&user).Where("id IN ?", ids).Update("status", "active")
|
||
|
||
// 批量删除
|
||
db.Delete(&User{}, ids)
|
||
```
|
||
|
||
### 3. 关闭预编译（极端性能场景）
|
||
|
||
```go
|
||
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
|
||
PrepareStmt: true, // 开启预编译，适合高并发同一 SQL
|
||
})
|
||
```
|
||
|
||
开启 `PrepareStmt` 后，GORM 会使用 `sql.DB.Prepare` + `sql.Stmt` 缓存预编译语句，适合大量相同 SQL 的执行场景。
|
||
|
||
## 企业级注意事项
|
||
|
||
### 🚫 严禁使用 AutoMigrate
|
||
|
||
在团队协作和企业级项目中，**禁止使用 `db.AutoMigrate()`**。原因：
|
||
|
||
1. **不可控的 DDL**：自动建表/改表可能导致生产数据丢失
|
||
2. **DBA 审计要求**：所有表结构变更需经过 SQL 审查
|
||
3. **版本管理**：数据库结构应通过迁移脚本（如 `golang-migrate`）管理
|
||
|
||
**推荐做法**：通过 SQL 脚本初始化数据库，与 [数据库设计](file:///home/wonder/Code/obsidian/金山办公作业/Week05/数据库设计.md) 文档保持一致。
|
||
|
||
### 事务与并发
|
||
|
||
```go
|
||
// ❌ 错误：多个 goroutine 共享同一个 db 连接
|
||
// db.Create(&user1) // 并发不安全
|
||
|
||
// ✅ 正确：事务自带连接池，每个 goroutine 开启独立事务
|
||
func saveUser(tx *gorm.DB, user *User) error {
|
||
return tx.Create(user).Error
|
||
}
|
||
```
|
||
|
||
GORM 底层使用 `sql.DB` 连接池，本身是并发安全的，但 `db.Begin()` 返回的事务对象不可跨 goroutine 共享。
|
||
|
||
### 错误处理
|
||
|
||
```go
|
||
result := db.Where("id = ?", id).First(&user)
|
||
if result.Error != nil {
|
||
if errors.Is(result.Error, gorm.ErrRecordNotFound) {
|
||
// 记录不存在
|
||
} else {
|
||
// 其他数据库错误
|
||
return result.Error
|
||
}
|
||
}
|
||
```
|
||
|
||
## GORM vs 原生 SQL
|
||
|
||
| 场景 | 推荐方案 | 原因 |
|
||
|------|----------|------|
|
||
| 简单 CRUD | GORM | 代码简洁，开发效率高 |
|
||
| 复杂 JOIN | GORM `Joins` | GORM 链式写法比手写 SQL 更直观 |
|
||
| 聚合查询（GROUP BY + HAVING） | GORM `Select/Group/Having` | 原生 SQL 也可，看团队偏好 |
|
||
| 复杂子查询/CTE | 原生 SQL `Raw/Scan` | GORM 对复杂 SQL 支持有限 |
|
||
| 高性能写入（大批量） | GORM 批量 | 或直接用 `sql.Batch` |
|
||
| 数据库迁移 | SQL 脚本 / golang-migrate | GORM AutoMigrate 禁用于生产 |
|
||
|
||
## 关联笔记
|
||
|
||
- [[DEV/GO/README]]
|
||
- [[金山办公作业/Week05/数据库设计]]
|
||
- [[金山办公作业/Week05/全栈开发实战：AI 智能单词本]]
|