vault backup: 2026-04-28 20:12:15
This commit is contained in:
+207
-30
@@ -25,6 +25,9 @@ type User struct {
|
||||
// 这就是一个最简单的 GORM Model
|
||||
```
|
||||
|
||||
> [!tip] 核心原则
|
||||
> GORM 的本质是一个「约定优于配置」的 ORM。struct 只是普通的 Go 结构体，`gorm:"..."` tag 告诉 GORM 如何将它映射到数据库——不修改运行时行为，只在构建 SQL 和建表时生效。这意味着你可以将同一个 struct 同时用于 HTTP 请求体和数据库模型（通过暴露合适的字段）。
|
||||
|
||||
## 表名规则
|
||||
|
||||
### 默认命名策略
|
||||
@@ -35,14 +38,21 @@ GORM 使用 `Table` 方法来推导表名：
|
||||
|----------|------|
|
||||
| 默认 | struct 名的蛇形复数形式（`User` → `users`） |
|
||||
| 实现 `TableName() string` | 返回的字符串 |
|
||||
| 使用 `db.Table("xxx")` | 查询时使用的表名（不会修改 Model 的 TableName） |
|
||||
| 使用 `db.Table("xxx")` | 本次查询使用的表名（不会修改 Model 的 TableName） |
|
||||
|
||||
> [!tip] `TableName()` vs `db.Table()`：何时用哪个？
|
||||
> - **结构性差异**（多环境、分库分表）→ 用 `TableName()`，因为这是模型级别的约定。
|
||||
> - **临时覆盖**（一个复杂查询需要 JOIN 不同视图）→ 用 `db.Table()`，它只影响当前链式调用，不污染模型定义。
|
||||
|
||||
```go
|
||||
func (User) TableName() string {
|
||||
return "sys_user" // 显式指定表名
|
||||
return "sys_user" // 显式指定表名；value receiver 即可，无需接收者变量
|
||||
}
|
||||
```
|
||||
|
||||
> [!note] 为什么用 value receiver `(User)` 而非 `*User`？
|
||||
> `TableName()` 只需要返回一个字符串，不需要访问任何字段。GORM 内部会先尝试值接收者方法，找不到再尝试指针接收者——所以用 `(User)` 既能被值对象调用也能被指针对象调用，灵活性更好。
|
||||
|
||||
> [!tip] 多环境表名
|
||||
> 不同环境下表名前缀不同？可以用环境变量 + `TableName()` 实现动态切换：
|
||||
> ```go
|
||||
@@ -74,7 +84,8 @@ gorm:"column:name;type:bigint;not null;default:0;uniqueIndex;index;comment:用
|
||||
| `index` | 普通索引 | `index:idx_status` |
|
||||
| `comment` | 注释（MySQL） | `comment:用户名` |
|
||||
| `<-` | 字段写入控制 | `<-:true` / `<-:false` / `<-:create` / `<-:update` |
|
||||
| `->` | 只读/只写 | `->:true`（只读） `/ <-:false`（不写入） |
|
||||
| `->` | 读取控制（只读 = 只从 DB 读出） | `->:true` / `->:false`（不读取回 struct） |
|
||||
| `<-` + `->` | 组合控制读写 | `<-:false;->:true`（只读，不可写入） |
|
||||
| `-` | 忽略此字段 | `-` |
|
||||
|
||||
### 写入权限控制
|
||||
@@ -93,6 +104,47 @@ type Product struct {
|
||||
> [!example] 方向记忆法
|
||||
> `<-` 表示数据**流向数据库**（写入），`->` 表示数据**从数据库流出**（读取）。箭头方向就是数据的方向。
|
||||
|
||||
### 嵌入 Struct（组合优于继承）
|
||||
|
||||
Go 不支持类的继承，但可以通过结构体嵌套实现代码复用：
|
||||
|
||||
```go
|
||||
// 方式一：显式嵌入公共字段
|
||||
type AuditRecord struct {
|
||||
CreatedBy string `gorm:"size:64"` // 创建人
|
||||
UpdatedBy string `gorm:"size:64"` // 最后修改人
|
||||
}
|
||||
|
||||
type User struct {
|
||||
ID uint `gorm:"primaryKey"`
|
||||
Name string `gorm:"size:64;not null"`
|
||||
AuditRecord // 匿名嵌入——Go 将 AuditRecord 的字段提升为 User 的直接字段
|
||||
}
|
||||
|
||||
// 方式二：使用 gorm.Model（推荐 🌟）
|
||||
type Article struct {
|
||||
gorm.Model // 自动包含 ID、CreatedAt、UpdatedAt、DeletedAt
|
||||
Title string `gorm:"size:128;not null"`
|
||||
Content string `gorm:"type:text"`
|
||||
}
|
||||
```
|
||||
|
||||
> [!note] 为什么推荐 `gorm.Model`？
|
||||
> `gorm.Model` 是 GORM 预定义的 struct，包含四个最常见字段：
|
||||
> ```go
|
||||
> type Model struct {
|
||||
> ID any `gorm:"primaryKey"` // 主键，类型为 any (v2.27+)
|
||||
> CreatedAt time.Time // 创建时间
|
||||
> UpdatedAt time.Time // 更新时间
|
||||
> DeletedAt gorm.DeletedAt // 软删除时间戳
|
||||
> }
|
||||
> ```
|
||||
> 嵌入后即可拥有完整的审计追踪 + 软删除能力，无需每个 struct 重复声明。
|
||||
|
||||
> [!question] 思考
|
||||
> 如果 `User` 同时嵌入了 `AuditRecord` 和 `gorm.Model`，而两者都有 `CreatedBy` 字段，会发生什么？
|
||||
> **答**：编译报错——Go 不允许歧义字段访问。此时应只保留一个来源，或改为普通成员变量而非嵌入：`Audit AuditRecord`。
|
||||
|
||||
## 字段类型映射
|
||||
|
||||
| Go 类型 | 推荐 DB 类型 | 说明 |
|
||||
@@ -112,13 +164,15 @@ type Product struct {
|
||||
type Article struct {
|
||||
ID uint `gorm:"primaryKey"`
|
||||
Title string `gorm:"size:128;not null"`
|
||||
CreatedAt time.Time `gorm:"autoTime;createTime"` // 创建时自动填充
|
||||
UpdatedAt time.Time `gorm:"autoTime;updateTime"` // 更新时自动填充
|
||||
CreatedAt time.Time `gorm:"autoTime;createTime"` // 首次插入时自动填入当前时间，后续 UPDATE 不会修改
|
||||
UpdatedAt time.Time `gorm:"autoTime;updateTime"` // 每次 UPDATE 时自动更新为当前时间
|
||||
}
|
||||
```
|
||||
|
||||
> [!note] createTime / updateTime
|
||||
> 这两个子 tag 是 GORM v2 的增强功能，配合 `autoTime` 使用。单独 `autoTime` 只更新时间，加上 `createTime` 后才会在插入时设置 CreatedAt。
|
||||
> [!tip] `autoTime` + `createTime` / `updateTime` 的分工
|
||||
> - 只写 `autoTime`（旧写法）：GORM 在 INSERT 和 UPDATE 时都更新时间字段。
|
||||
> - `autoTime` + `createTime`：INSERT 时设置 `CreatedAt`，UPDATE 不碰它——这才是创建时间的正确语义。
|
||||
> - `autoTime` + `updateTime`：UPDATE 时设置 `UpdatedAt`，INSERT 时同样会设初始值。
|
||||
|
||||
## 主键策略
|
||||
|
||||
@@ -146,56 +200,179 @@ order.ID = uuid.New()
|
||||
db.Create(&order)
|
||||
```
|
||||
|
||||
> [!tip] 为什么选 UUID 做主键？
|
||||
> 自增 ID 存在 URL 泄露、ID 猜测等安全风险。UUID v4 完全随机，不会暴露数据量级。代价是索引碎片化更严重——InnoDB 的聚簇索引以主键排序，随机插入会导致页分裂，吞吐量下降约 30%。如果性能敏感可考虑 [ULID](https://github.com/ulid/spec)（有序且随机），或雪花算法生成的 `int64`。
|
||||
|
||||
### 复合主键
|
||||
|
||||
```go
|
||||
type OrderItem struct {
|
||||
OrderID uint `gorm:"primaryKey"`
|
||||
OrderID uint `gorm:"primaryKey"` // 多个 primaryKey tag 构成复合主键
|
||||
ProductID uint `gorm:"primaryKey"`
|
||||
Quantity int `gorm:"not null"`
|
||||
}
|
||||
// 生成表结构：PRIMARY KEY (order_id, product_id)
|
||||
```
|
||||
|
||||
> [!tip] 复合主键注意事项
|
||||
> 使用复合主键时，`First()` 和 `Take()` 将无法工作（因为它们期望单主键），必须使用 `Where()` 精确定位。
|
||||
> [!warning] 复合主键的注意事项
|
||||
> - `First()` 和 `Take()` 无法工作（它们期望单主键），必须用 `Where("order_id=? AND product_id=?", ...)` 精确定位。
|
||||
> - `AutoMigrate` 对复合主键支持有限，建议手动建表或在迁移后验证 schema。
|
||||
> - 关联查询时外键也需要对应多列——通常此时改用单独的 `id` 作为主键 + 唯一索引代替复合主键更为方便。
|
||||
|
||||
## 软删除
|
||||
|
||||
GORM 的软删除通过 `DeletedAt` 字段实现——被"删除"的记录实际上只是将该字段设为当前时间，数据仍然保留在数据库中。
|
||||
|
||||
```go
|
||||
type User struct {
|
||||
gorm.Model // DeletedAt 已包含在此中
|
||||
}
|
||||
|
||||
// "删除"一条记录（实际是 UPDATE SET deleted_at = NOW()）
|
||||
db.Delete(&user) // sql: UPDATE users SET deleted_at=... WHERE id=?
|
||||
|
||||
// 查询时自动排除已删除记录
|
||||
db.Find(&users) // WHERE deleted_at IS NULL
|
||||
|
||||
// 查询全部（包括已删除）
|
||||
db.Unscoped().Find(&users)
|
||||
|
||||
// 真正物理删除
|
||||
db.Unscoped().Delete(&user)
|
||||
```
|
||||
|
||||
> [!important] 软删除的设计哲学
|
||||
> 软删除不是银弹。适合用于「可能需要恢复」的业务场景（如组织架构、订单流程）。但对于有唯一性约束的字段，软删除后会导致冲突——因为旧记录的该行仍占着唯一值。此时需自行设计隔离策略，例如添加 `is_deleted INT DEFAULT 0` 替代 GORM 内置方案。
|
||||
|
||||
> [!question] 为什么软删除用时间戳而非 BOOLEAN？
|
||||
> 时间戳记录了确切的删除时刻，便于后续审计和问题排查；而 BOOLEAN 只能告诉你「是否删除」，丢失了时序信息。同时，`NULL` 表示未删除，语义更加清晰。
|
||||
|
||||
## 自定义类型作为字段
|
||||
|
||||
当内置类型不够用时，可以实现 GORM 接口：
|
||||
当内置类型不够用时，GORM 提供三组接口让 struct 自行控制与数据库的交互方式。
|
||||
|
||||
### ValueScanner 模式（推荐）
|
||||
|
||||
实现 `driver.Valuer`（写回 DB）和 `sql.Scanner`（从 DB 读出）两个接口：
|
||||
|
||||
```go
|
||||
type MyType int
|
||||
type JSONMap map[string]interface{}
|
||||
|
||||
func (m MyType) GORMDataType() string {
|
||||
return "INT"
|
||||
// Value：Go → DB（序列化）
|
||||
func (j JSONMap) Value() (driver.Value, error) {
|
||||
if j == nil {
|
||||
return nil, nil
|
||||
}
|
||||
return json.Marshal(j) // 存入时转为 JSON 字符串
|
||||
}
|
||||
|
||||
func (m MyType) Value() (driver.Value, error) {
|
||||
return int(m), nil // ScannerValuer 接口的 Value 方法
|
||||
// Scan：DB → Go（反序列化）
|
||||
func (j *JSONMap) Scan(value interface{}) error {
|
||||
if value == nil {
|
||||
*j = nil
|
||||
return nil
|
||||
}
|
||||
return json.Unmarshal(value.([]byte), &j)
|
||||
}
|
||||
|
||||
type Setting struct {
|
||||
ID uint `gorm:"primaryKey"`
|
||||
Key string `gorm:"size:64;uniqueIndex;not null"`
|
||||
Value JSONMap `gorm:"type:json"` // 存入 MySQL JSON 列
|
||||
}
|
||||
```
|
||||
|
||||
### GORMDataType 覆盖类型推导
|
||||
|
||||
如果你只需要告诉 GORM「这个类型对应什么数据库类型」，无需处理序列化逻辑：
|
||||
|
||||
```go
|
||||
type Priority int8 // 优先级：1-紧急 2-高 3-普通 4-低
|
||||
|
||||
func (Priority) GORMDataType() string {
|
||||
return "TINYINT UNSIGNED" // 覆盖 GORM 默认的 INT 推导
|
||||
}
|
||||
|
||||
type Task struct {
|
||||
ID uint `gorm:"primaryKey"`
|
||||
Title string `gorm:"size:128;not null"`
|
||||
Priority Priority `gorm:"not null;default:3"`
|
||||
}
|
||||
```
|
||||
|
||||
> [!tip] 该用哪个接口？
|
||||
> - 需要 **序列化成特定格式**（如 JSON、压缩字符串）→ 实现 `driver.Valuer` + `sql.Scanner`
|
||||
> - 只需 **覆盖列类型**，不做特殊转换 → 实现 `GORMDataType()`
|
||||
> - 两者可同时实现——`GORMDataType` 决定建表类型，`Value/Scan` 决定读写时的数据转换。
|
||||
|
||||
## 数据校验与生命周期钩子
|
||||
|
||||
struct tag 适合声明式约束，但更复杂的业务逻辑需要 GORM 提供的生命周期回调：
|
||||
|
||||
```go
|
||||
type User struct {
|
||||
ID uint `gorm:"primaryKey"`
|
||||
Email string `gorm:"size:128;uniqueIndex;not null"`
|
||||
Password string `gorm:"size:128;not null"`
|
||||
IsActive bool `gorm:"default:true"`
|
||||
CreatedAt time.Time
|
||||
}
|
||||
|
||||
// BeforeCreate：在 INSERT 之前执行（可用于加密密码、生成唯一码等）
|
||||
func (u *User) BeforeCreate(tx *gorm.DB) error {
|
||||
// 基础校验
|
||||
if !strings.Contains(u.Email, "@") {
|
||||
return errors.New("invalid email format") // 返回错误中断操作
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// AfterFind：在 SELECT 之后执行（可用于解密敏感字段）
|
||||
func (u *User) AfterFind(tx *gorm.DB) error {
|
||||
// 例如：对查询结果做脱敏处理
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
> [!summary] 常用钩子一览
|
||||
> | 钩子 | 触发时机 | 典型用途 |
|
||||
> |------|----------|----------|
|
||||
> | `BeforeCreate` | `Create` 之前 | 字段默认值、加密、校验 |
|
||||
> | `AfterCreate` | `Create` 之后 | 发送通知、记录日志 |
|
||||
> | `BeforeUpdate` | `Update` 之前 | 乐观锁版本检查 |
|
||||
> | `AfterUpdate` | `Update` 之后 | 同步缓存、审计追踪 |
|
||||
> | `BeforeDelete` | `Delete` 之前 | 关联级联清理 |
|
||||
> | `AfterDelete` | `Delete` 之后 | 软删除相关辅助操作 |
|
||||
> | `AfterFind` | `Find/First` 之后 | 字段解密、格式化输出 |
|
||||
|
||||
> [!note] 校验的最佳实践
|
||||
> struct tag 的 `not null` / `uniqueIndex` 仅在 **建表** 时生效。运行时 GORM 不会自动校验这些数据——如果需要应用层校验，优先使用独立的 validator 库（如 `github.com/go-playground/validator`），而不是依赖生命周期钩子做业务校验。
|
||||
|
||||
## 模型设计流程图
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[定义 struct] --> B{有无 ID 字段?}
|
||||
B -->|有| C["ID 作主键<br/>uint/int64"]
|
||||
B -->|无| D{自定义 TableName?}
|
||||
D -->|实现了| E[按 TableName 返回值]
|
||||
D -->|未实现| F["struct 名蛇形复数"]
|
||||
C --> G[添加字段 tag]
|
||||
graph TD
|
||||
A[定义 struct] --> B{有无 ID<br/>字段?}
|
||||
B -->|有| C[ID 自动作主键]
|
||||
B -->|无| D{实现 TableName?}
|
||||
D -->|已实现| E[使用返回值<br/>作为表名]
|
||||
D -->|未实现| F[struct 名 →<br/>蛇形复数形式]
|
||||
C --> G{需要自定义列名或<br/>类型?}
|
||||
E --> G
|
||||
G --> H{需要特殊类型?}
|
||||
H -->|是| I[实现 GORMDataType / Valuer]
|
||||
H -->|否| J[完成]
|
||||
I --> J
|
||||
|
||||
F --> G
|
||||
G -->|是| H[添加 gorm tag]
|
||||
G -->|否| I{是否需要软删除?}
|
||||
H --> I
|
||||
I -->|是| J[嵌入 gorm.Model<br/>或使用 DeletedAt]
|
||||
I -->|否| K{内置类型够用?}
|
||||
J --> K
|
||||
K -->|是| L[完成 ✓]
|
||||
K -->|否| M[实现 Value / Scan<br/>接口]
|
||||
M --> L
|
||||
style A fill:#4FC08D,color:#fff
|
||||
style C fill:#3B82F6,color:#fff
|
||||
style I fill:#EAB308,color:#fff
|
||||
style J fill:#A0AEC0,color:#fff
|
||||
style J fill:#F59E0B,color:#fff
|
||||
style L fill:#A0AEC0,color:#fff
|
||||
```
|
||||
|
||||
## 关联笔记
|
||||
|
||||
Reference in New Issue
Block a user