342 lines
11 KiB
Markdown
342 lines
11 KiB
Markdown
---
|
||
tags: [GORM, Go, ORM, 钩子函数, Callback, BeforeCreate, AfterUpdate, Lifecycle]
|
||
create time: 2026-04-28 00:00
|
||
---
|
||
|
||
# 钩子函数
|
||
|
||
## 概述
|
||
|
||
钩子（Hook）是 GORM 生命周期回调机制，允许你在特定操作前后注入自定义逻辑。它们是「横切关注点」的理想载体——不需要在每个业务代码里重复写加密、日志、审计等通用逻辑。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph CREATE["🟢 Create"]
|
||
A[Create 调用] --> BC["BeforeCreate"]
|
||
BC --> CreateSQL["执行 INSERT"]
|
||
CreateSQL --> AC["AfterCreate"]
|
||
end
|
||
|
||
subgraph UPDATE["🟡 Update"]
|
||
D[Update 调用] --> BU["BeforeUpdate"]
|
||
BU --> UpdateSQL["执行 UPDATE"]
|
||
UpdateSQL --> AU["AfterUpdate"]
|
||
end
|
||
|
||
subgraph DELETE["🔴 Delete"]
|
||
E[Delete 调用] --> BD["BeforeDelete"]
|
||
BD --> DeleteSQL["执行 DELETE"]
|
||
DeleteSQL --> AD["AfterDelete"]
|
||
end
|
||
|
||
subgraph FIND["🔵 Find/Query"]
|
||
F[Find/First 调用] --> AF["AfterFind"]
|
||
end
|
||
|
||
style CREATE fill:#22C55E,color:#fff,stroke:#16A34A
|
||
style UPDATE fill:#EAB308,color:#000,stroke:#CA8A04
|
||
style DELETE fill:#EF4444,color:#fff,stroke:#DC2626
|
||
style FIND fill:#3B82F6,color:#fff,stroke:#2563EB
|
||
style BC fill:#22C55E,color:#fff
|
||
style AC fill:#22C55E,color:#fff
|
||
style BU fill:#EAB308,color:#000
|
||
style AU fill:#EAB308,color:#000
|
||
style BD fill:#EF4444,color:#fff
|
||
style AD fill:#EF4444,color:#fff
|
||
style AF fill:#3B82F6,color:#fff
|
||
```
|
||
|
||
> [!note] GORM 的操作顺序
|
||
> 每个操作的执行流：`钩子(前置) → SQL 执行 → 钩子(后置)`。前置钩子返回错误可以**中断整个操作**。
|
||
|
||
## 完整钩子列表
|
||
|
||
### 创建阶段
|
||
|
||
```go
|
||
func (u *User) BeforeCreate(tx *gorm.DB) error {
|
||
// 在 INSERT 之前执行
|
||
u.CreatedAt = time.Now()
|
||
u.UpdatedAt = time.Now()
|
||
|
||
// 对密码做哈希处理
|
||
hashed, _ := bcrypt.GenerateFromPassword([]byte(u.Password), bcrypt.DefaultCost)
|
||
u.Password = string(hashed)
|
||
|
||
// 生成唯一 ID
|
||
if u.UUID == "" {
|
||
u.UUID = generateUUID()
|
||
}
|
||
return nil // 返回错误可中断插入
|
||
}
|
||
|
||
func (u *User) AfterCreate(tx *gorm.DB) error {
|
||
// 在 INSERT 之后执行
|
||
// 例如：发送欢迎邮件、记录审计日志
|
||
log.Printf("用户 %s 创建成功，ID=%d", u.Name, u.ID)
|
||
return nil
|
||
}
|
||
```
|
||
|
||
### 更新阶段
|
||
|
||
```go
|
||
func (u *User) BeforeUpdate(tx *gorm.DB) error {
|
||
// 在 UPDATE 之前执行
|
||
u.UpdatedAt = time.Now()
|
||
|
||
// 检查乐观锁版本号
|
||
var prev User
|
||
tx.Select("version").First(&prev, u.ID)
|
||
if prev.Version != u.Version {
|
||
return errors.New("数据已被其他人修改，请刷新后重试")
|
||
}
|
||
return nil
|
||
}
|
||
|
||
func (u *User) AfterUpdate(tx *gorm.DB) error {
|
||
// 同步缓存
|
||
redis.Set(context.Background(), "user:"+strconv.Itoa(u.ID), u, time.Hour)
|
||
return nil
|
||
}
|
||
```
|
||
|
||
> [!tip] Changed vs Updated
|
||
> - `tx.Statement.Changed("field")`：只要调用过 `Updates(map)` 并包含该字段，就返回 true（无论新旧值是否相同）
|
||
> - `tx.Statement.Updated("field")`：返回值与 Changed 一致，但额外校验「新值 ≠ 旧值」
|
||
> - 如果直接通过结构体赋值再调 `Save()` / `UpdateColumn()`，这些方法都**不会追踪变化**，需用 `Updates` 才有效
|
||
|
||
### 删除阶段
|
||
|
||
```go
|
||
func (u *User) BeforeDelete(tx *gorm.DB) error {
|
||
// 清理关联数据（比如清除 Redis Session）
|
||
sessionIDs, _ := getSessionIDsByUserID(u.ID)
|
||
for _, id := range sessionIDs {
|
||
redis.Del(context.Background(), "session:"+id)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
func (u *User) AfterDelete(tx *gorm.DB) error {
|
||
// 如果用了软删除，这里可以做真正的物理清理（如文件、附件）
|
||
if tx.RowsAffected > 0 {
|
||
deleteUploadedFiles(u)
|
||
}
|
||
return nil
|
||
}
|
||
```
|
||
|
||
### 查询阶段
|
||
|
||
```go
|
||
func (u *User) AfterFind(tx *gorm.DB) error {
|
||
// 在 SELECT 之后执行——每次 Find/First 都会触发
|
||
// 适合用于敏感字段脱敏或格式化处理
|
||
|
||
// 示例：邮箱脱敏
|
||
if len(u.Email) > 4 {
|
||
masked := u.Email[:2] + "***" + u.Email[len(u.Email)-2:]
|
||
fmt.Println("已脱敏:", masked)
|
||
}
|
||
return nil
|
||
}
|
||
```
|
||
|
||
> [!question] AfterFind 的性能影响
|
||
> `AfterFind` 会在每次查询时对所有行都执行——如果一次查出 1000 条记录，钩子会运行 1000 次。不要在 `AfterFind` 中放重逻辑（如 RPC 调用）。
|
||
|
||
## 条件判断：根据操作类型选择行为
|
||
|
||
有时你希望同一个钩子在特定操作下才生效。可以通过 `tx.Statement` 判断当前操作类型：
|
||
|
||
```go
|
||
func (u *User) BeforeUpdate(tx *gorm.DB) error {
|
||
// 只在 Password 被修改时才重新哈希
|
||
if tx.Statement.Changed("Password") {
|
||
hashed, _ := bcrypt.GenerateFromPassword([]byte(u.Password), bcrypt.DefaultCost)
|
||
u.Password = string(hashed)
|
||
}
|
||
return nil
|
||
}
|
||
```
|
||
|
||
> [!tip] Statement 常用方法
|
||
|
||
| 方法 | 作用 |
|
||
|------|------|
|
||
| `Changed(field)` | 该字段是否在 Updates 中被修改 |
|
||
| `Select()` | 获取显式 SELECT 的字段列表 |
|
||
| `Omit()` | 获取 OMIT 的字段列表 |
|
||
| `Deleted()` | 是否是 Delete 操作 |
|
||
| `Updated(field)` | 字段是否被更新且值发生变化 |
|
||
|
||
### Model 级 vs 全局 Callback
|
||
|
||
GORM 支持两种注册方式，优先级为 **Model 级 > 全局**：
|
||
|
||
```go
|
||
// Model 级钩子——实现 gorm.LifecycleHooks 接口（最常用）
|
||
type Order struct{}
|
||
func (Order) BeforeCreate(tx *gorm.DB) error { ... }
|
||
```
|
||
|
||
> [!note] LifecycleHooks 接口
|
||
> GORM v2 定义了以下接口，struct 只要方法签名匹配即自动注册为钩子：
|
||
> - `BeforeCreate(tx *gorm.DB) error`
|
||
> - `AfterCreate(tx *gorm.DB) error`
|
||
> - `BeforeUpdate(tx *gorm.DB) error`
|
||
> - `AfterUpdate(tx *gorm.DB) error`
|
||
> - `BeforeDelete(tx *gorm.DB) error`
|
||
> - `AfterDelete(tx *gorm.DB) error`
|
||
> - `AfterFind(tx *gorm.DB) error`
|
||
>
|
||
> 你也可以使用 `*gorm.State` 替代 `*gorm.DB`（gint-gorm 兼容模式），但在大多数场景下 `*gorm.DB` 更通用。
|
||
|
||
#### 全局 Callback —— 作用于所有模型
|
||
|
||
```go
|
||
// 在 Create SQL 执行之前注册自定义逻辑
|
||
db.Callback().Create().Before("gorm:create").Register("set_created_at", func(tx *gorm.DB) {
|
||
if v, ok := tx.Get("created_at_overwrite"); ok {
|
||
if t, ok := v.(time.Time); ok {
|
||
tx.Statement.SetColumn("CreatedAt", t)
|
||
}
|
||
}
|
||
})
|
||
|
||
// 在 Delete 之后追加逻辑（不阻塞后续 callback）
|
||
db.Callback().Delete().After("gorm:delete").Register("cleanup_cache", func(tx *gorm.DB) {
|
||
// 清理缓存等后置操作
|
||
})
|
||
|
||
// 替换 GORM 内置回调（谨慎使用！）
|
||
db.Callback().Create().Replace("gorm:create", func(tx *gorm.DB) {
|
||
// 完全接管 Create 流程
|
||
})
|
||
|
||
// 移除内置回调
|
||
db.Callback().Create().Remove("gorm:create")
|
||
```
|
||
|
||
> [!warning] 全局钩子注意事项
|
||
> 1. 注册时机必须在 `db.Open()` 之后、首次操作之前
|
||
> 2. 会影响**所有模型**——包括内置的 `gorm.Model`
|
||
> 3. 按阶段排序：`Before(name)` / `After(name)` / `Register(name, fn)` / `Replace(name, fn)` / `Remove(name)`
|
||
> 4. 频繁读写数据库的全局逻辑会拖慢所有模型，建议在钩子内用 `tx.Get()` 做条件过滤
|
||
|
||
## 执行时序
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant App as 应用代码
|
||
participant Hook as GORM 钩子系统
|
||
participant DB as 数据库
|
||
|
||
App->>Hook: db.Create(&user)
|
||
Hook->>Hook: BeforeCreate
|
||
Hook->>DB: INSERT INTO users...
|
||
DB-->>Hook: 返回影响行数
|
||
Hook->>Hook: AfterCreate
|
||
Hook-->>App: 返回结果
|
||
```
|
||
|
||
## 实战：一个完整的业务模型
|
||
|
||
下面展示一个电商订单模型，综合运用多个钩子处理真实场景：
|
||
|
||
```go
|
||
type Order struct {
|
||
gorm.Model
|
||
UserID uint `gorm:"not null;index"`
|
||
Amount decimal.Decimal
|
||
Status string // pending → paid → shipped → completed
|
||
PaidAt *time.Time // 支付时间，nil = 未支付
|
||
Version int // 乐观锁版本号
|
||
CreatedBy string // 创建人标识
|
||
}
|
||
|
||
func (o *Order) BeforeCreate(tx *gorm.DB) error {
|
||
// ① 初始化状态和审计字段
|
||
if o.Status == "" {
|
||
o.Status = "pending"
|
||
}
|
||
o.CreatedBy = getCurrentUserID() // 从 context 获取
|
||
o.Version = 1
|
||
return nil
|
||
}
|
||
|
||
func (o *Order) BeforeUpdate(tx *gorm.DB) error {
|
||
// ② 版本号递增 + 状态机校验
|
||
o.Version++
|
||
|
||
validTransitions := map[string][]string{
|
||
"pending": {"paid"},
|
||
"paid": {"shipped"},
|
||
"shipped": {"completed"},
|
||
}
|
||
newStatus := tx.Statement.Schema.ValueOfField(tx.Statement.Schema.FieldsByName["Status"])
|
||
allowed, ok := validTransitions[o.Status]
|
||
if !ok || !contains(allowed, newStatus.String()) {
|
||
return fmt.Errorf("非法状态转换: %s → %s", o.Status, newStatus)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
func (o *Order) AfterUpdate(tx *gorm.DB) error {
|
||
// ③ 状态变更时发送通知
|
||
if old, ok := tx.Data.(*Order); ok && old.Status != o.Status {
|
||
sendNotification(o.UserID, "订单状态变更为: "+o.Status)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
func (o *Order) AfterDelete(tx *gorm.DB) error {
|
||
// ④ 软删除后清理缓存
|
||
redis.Del(context.Background(), "order:"+strconv.Itoa(int(o.ID)))
|
||
return nil
|
||
}
|
||
|
||
func contains(slice []string, s string) bool {
|
||
for _, v := range slice {
|
||
if v == s {
|
||
return true
|
||
}
|
||
}
|
||
return false
|
||
}
|
||
```
|
||
|
||
> [!question] 为什么 AfterDelete 能拿到被删的数据？
|
||
> 因为 GORM 的软删除是先查再标记 `deleted_at`，AfterDelete 钩子中仍然可以通过 `tx.Statement.ReflectValue` 访问到原始对象数据。
|
||
|
||
## 常用场景速查
|
||
|
||
| 需求 | 推荐方案 | 说明 |
|
||
|------|---------|------|
|
||
| 自动填充 CreatedAt / UpdatedAt | 用 `autoTime` tag 更简单 | 手动实现则放 BeforeCreate / BeforeUpdate |
|
||
| 密码哈希 | BeforeCreate + BeforeUpdate(仅 Changed) | 避免重复哈希 |
|
||
| 乐观锁 | BeforeUpdate(检查 version) | 并发安全的经典方案 |
|
||
| 审计日志 | AfterCreate / AfterUpdate / AfterDelete | 操作完成后记录 |
|
||
| 数据脱敏 | AfterFind | 对外输出前格式化（注意性能） |
|
||
| 关联清理 | BeforeDelete | 删除前解除外部引用 |
|
||
| 全局默认值 | Callback.Register() | 作用于所有模型，需条件过滤 |
|
||
|
||
## 最佳实践
|
||
|
||
> [!checklist] 使用钩子时的 Checklist
|
||
> 1. **永远用 tx 不用 db** — 钩子内部不要调用 `db.Create()` / `db.Raw()`，必须使用传入的 `tx` 参数，否则会导致死锁
|
||
> 2. **AfterFind 中不要修改原对象** — 直接改字段会影响所有调用方；需要脱敏时在接口层另行处理
|
||
> 3. **不要在钩子里发送 HTTP 请求或做耗时 IO** — 会阻塞主流程；改用 channel + goroutine 异步处理
|
||
> 4. **Changed/Updated 只在 Updates 时有效** — Save 是全量写入、Select/Omit 不会触发追踪
|
||
> 5. **批量操作也会逐条触发** — `Create(&[]Model{})` 每条都走钩子；如想跳过用 `db.Session(&gorm.Session{SkipHooks: true}).Create(...)`
|
||
> 6. **钩子返回 nil != 没返回值** — Go 中空指针 nil 不等于 error 零值，中断操作必须 `return errors.New("原因")`
|
||
|
||
## 关联笔记
|
||
|
||
- [[02-模型定义]]
|
||
- [[03-CRUD 操作]]
|
||
- [[08-事务管理]]
|
||
- [[11-批量操作]]
|
||
- [[10-字段标签]]（autoTime / autoCreateTime 等内置标签）
|