all-in-kingsoft/hhs/GORM/02-模型定义.md

---
tags: [GORM, Go, ORM, 模型, struct tag, 字段映射, 主键, 表名]
create time: 2026-04-28 00:00
---

# 模型定义

## 概述

模型（Model）是 GORM 操作的核心入口——一个普通的 Go struct 被 GORM「看见」后，就可以直接进行数据库操作。本章讲解如何通过 struct tag、命名约定和接口来自定义 GORM 对模型的解读。

## 什么是 Model？

> [!definition] Model
> Model 是一个包含以下任一条件的 struct：
> 1. 有主键字段
> 2. 定义了 `TableName()` 方法
> 3. 被 `AutoMigrate`、`Create`、`Where` 等方法引用

```go
type User struct {
    ID   uint   `gorm:"primaryKey"`
    Name string `gorm:"size:64;not null"`
}
// 这就是一个最简单的 GORM Model
```

> [!tip] 核心原则
> GORM 的本质是一个「约定优于配置」的 ORM。struct 只是普通的 Go 结构体，`gorm:"..."` tag 告诉 GORM 如何将它映射到数据库——不修改运行时行为，只在构建 SQL 和建表时生效。这意味着你可以将同一个 struct 同时用于 HTTP 请求体和数据库模型（通过暴露合适的字段）。

## 表名规则

GORM 通过三层优先级推导表名：`db.Table()` → `TableName()` 方法 → struct 名蛇形复数。自定义表名时还涉及 `NamingStrategy` 全局配置、value/pointer receiver 选择、分表策略等细节——详见子文档：

> [!abstract] 子文档
> - [[02-模型定义/表名规则]] — 默认策略、TableName()、db.Table()、NamingStrategy、分表实战、决策指南

## 字段 Tag 详解

### 完整 Tag 语法

```
gorm:"column:name;type:bigint;not null;default:0;uniqueIndex;index;comment:用户ID"
```

| Tag 关键字 | 作用 | 示例 |
|------------|------|------|
| `column` | 映射列名 | `column:user_id` |
| `type` | 列类型覆盖 | `type:varchar(128)` |
| `not null` | NOT NULL 约束 | `not null` |
| `default` | 默认值 | `default:'unknown'` |
| `primaryKey` | 主键 | `primaryKey` |
| `autoIncrement` | 自增 | `autoIncrement` |
| `uniqueIndex` | 唯一索引 | `uniqueIndex:idx_name` |
| `index` | 普通索引 | `index:idx_status` |
| `comment` | 注释（MySQL） | `comment:用户名` |
| `<-` | 字段写入控制 | `<-:true` / `<-:false` / `<-:create` / `<-:update` |
| `->` | 读取控制（只读 = 只从 DB 读出） | `->:true` / `->:false`（不读取回 struct） |
| `<-` + `->` | 组合控制读写 | `<-:false;->:true`（只读，不可写入） |
| `-` | 忽略此字段 | `-` |

### 写入权限控制

```go
type Product struct {
    ID        uint      `gorm:"primaryKey;autoIncrement"`
    Name      string    `gorm:"not null;<-:create"`          // 仅创建时可写入
    Price     float64   `gorm:"not null;<-:true;->:true"`    // 读写均可（默认）
    CreatedAt time.Time `gorm:"<-:create;->:true;autoTime"`  // 仅创建时自动填充
    UpdatedAt time.Time `gorm:"<-:update;->:true;autoTime"`  // 仅更新时自动填充
    ViewCount int       `gorm:"->:false;<-:false"`           // 完全忽略（非 DB 字段）
}
```

> [!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 类型 | 说明 |
|---------|-------------|------|
| `int`, `int64` | BIGINT | GORM 默认以 `int64` 处理 |
| `uint`, `uint64` | BIGINT UNSIGNED | — |
| `string` | VARCHAR(n) | 需手动指定 size |
| `bool` | TINYINT(1) / BOOLEAN | — |
| `float64` | DOUBLE | — |
| `time.Time` | DATETIME / TIMESTAMP | 配合 `autoTime` tag |
| `[]byte` | BLOB / BYTEA | 二进制数据 |
| `json.RawMessage` | JSON | JSON 序列化字段 |

### `autoTime` 自动时间戳

```go
type Article struct {
    ID        uint      `gorm:"primaryKey"`
    Title     string    `gorm:"size:128;not null"`
    CreatedAt time.Time `gorm:"autoTime;createTime"`  // 首次插入时自动填入当前时间，后续 UPDATE 不会修改
    UpdatedAt time.Time `gorm:"autoTime;updateTime"`  // 每次 UPDATE 时自动更新为当前时间
}
```

> [!tip] `autoTime` + `createTime` / `updateTime` 的分工
> - 只写 `autoTime`（旧写法）：GORM 在 INSERT 和 UPDATE 时都更新时间字段。
> - `autoTime` + `createTime`：INSERT 时设置 `CreatedAt`，UPDATE 不碰它——这才是创建时间的正确语义。
> - `autoTime` + `updateTime`：UPDATE 时设置 `UpdatedAt`，INSERT 时同样会设初始值。

## 主键策略

### 默认策略：ID uint

```go
type User struct {
    ID   uint   // GORM 默认将名为 ID 的字段视为主键
    Name string
}
```

### UUID 主键

```go
import "github.com/google/uuid"

type Order struct {
    ID   uuid.UUID `gorm:"type:char(36);primaryKey"`
    Code string    `gorm:"uniqueIndex;not null"`
}

// 在 Create 前生成 UUID
order.ID = uuid.New()
db.Create(&order)
```

> [!tip] 为什么选 UUID 做主键？
> 自增 ID 存在 URL 泄露、ID 猜测等安全风险。UUID v4 完全随机，不会暴露数据量级。代价是索引碎片化更严重——InnoDB 的聚簇索引以主键排序，随机插入会导致页分裂，吞吐量下降约 30%。如果性能敏感可考虑 [ULID](https://github.com/ulid/spec)（有序且随机），或雪花算法生成的 `int64`。

> [!abstract] 子文档
> - [[02-模型定义/UUID主键策略]] — UUID 版本选型（v4/v7）、BeforeCreate 自动生成、存储优化（char(36) vs binary(16)）、InnoDB 页分裂原理、ULID / Snowflake 替代方案、决策流程

### 复合主键

```go
type OrderItem struct {
    OrderID   uint `gorm:"primaryKey"`   // 多个 primaryKey tag 构成复合主键
    ProductID uint `gorm:"primaryKey"`
    Quantity  int  `gorm:"not null"`
}
// 生成表结构：PRIMARY KEY (order_id, product_id)
```

> [!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 提供三组接口让 struct 自行控制与数据库的交互方式。详见子文档：

> [!abstract] 子文档
> - [[02-模型定义/自定义类型作为字段]] — ValueScanner 深度用法（JSON、枚举、IP 压缩、加密存储）、GORMDataType 类型覆盖、Resolver API、AutoMigrate 推导流程、常见坑点

### ValueScanner 模式（推荐）

实现 `driver.Valuer`（写回 DB）和 `sql.Scanner`（从 DB 读出）两个接口：

```go
type JSONMap map[string]interface{}

// Value：Go → DB（序列化）
func (j JSONMap) Value() (driver.Value, error) {
    if j == nil {
        return nil, nil
    }
    return json.Marshal(j) // 存入时转为 JSON 字符串
}

// 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
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
    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 J fill:#F59E0B,color:#fff
    style L fill:#A0AEC0,color:#fff
```

## 关联笔记

- [[01-安装与初始化]]
- [[03-CRUD 操作]]
- [[12-自定义字段类型]]