3. 模型定义基础：结构体标签详解（gorm标签）、主键、表名映射、列名映射

在 GORM 中，模型（Model）是 Go 结构体与数据库表之间的桥梁。通过结构体字段上的 gorm 标签，开发者可以精确控制字段到列的映射关系、主键选择、表名规则以及约束条件。本节将系统讲解这些核心标签的用法与最佳实践。

3.1 结构体标签总览

GORM 使用 Go 结构体标签（Struct Tag）来定义 ORM 元数据。标签格式为 gorm:"key1:value1;key2:value2"，多个键值对之间用分号分隔。下表列出最常用的标签键及其作用域：

3.2 主键定义与组合主键

GORM 默认将名为 ID 的字段作为主键。若需自定义主键字段，使用 primaryKey 标签。支持单字段主键和组合主键（复合主键）。

// 单字段主键
type User struct {
  UserID    uint   `gorm:"primaryKey;autoIncrement:true"`
  Name      string
}

// 组合主键（复合主键）
type OrderItem struct {
  OrderID   uint   `gorm:"primaryKey"`
  ProductID uint   `gorm:"primaryKey"`
  Quantity  int
}

组合主键在迁移时会创建联合主键约束，适用于多对多关联表或业务主键场景。注意：组合主键不支持 autoIncrement。

3.3 表名映射

GORM 默认表名规则为结构体名的蛇形复数。例如 UserProfile → user_profiles。可通过以下三种方式自定义表名：

// 方式一：实现 TableName 接口
type User struct {
  ID   uint
  Name string
}

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

// 方式二：临时指定表名（不影响迁移）
db.Table("t_user").Where("name = ?", "Alice").Find(&users)

// 方式三：全局配置（在初始化时设置）
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
  NamingStrategy: schema.NamingStrategy{
    TablePrefix:   "t_",      // 表名前缀
    SingularTable: true,       // 禁用复数表名
  },
})

3.4 列名映射与字段控制

通过 column 标签可显式指定列名。此外，GORM 提供多个标签控制字段行为：

type Product struct {
  ID          uint    `gorm:"primaryKey;autoIncrement;column:product_id"`
  Code        string  `gorm:"column:sku_code;size:50;not null;uniqueIndex:idx_sku"`
  Price       float64 `gorm:"type:decimal(10,2);default:0.00"`
  Description string  `gorm:"type:text;comment:商品描述"`
  IsActive    bool    `gorm:"column:is_active;default:true"`
  CreatedAt   time.Time
  UpdatedAt   time.Time
  DeletedAt   gorm.DeletedAt `gorm:"index"` // 软删除字段
}

字段控制标签还包括：

• -：忽略该字段，不参与迁移和读写（例如 gorm:"-"）
• ->：只读字段，仅用于查询，不写入
• <-：只写字段，仅用于创建/更新，不查询
• <-:create：仅在创建时写入
• <-:update：仅在更新时写入

type AuditLog struct {
  ID        uint
  Action    string `gorm:"->"`           // 只读
  SecretKey string `gorm:"<-:create"`    // 仅在创建时写入
  Internal  string `gorm:"-"`            // 完全忽略
}

3.5 模型定义与迁移关系图

下图展示了结构体标签如何驱动数据库迁移过程：

3.6 冒烟回归测试中的模型定义要点

在冒烟回归测试场景中，模型定义需要额外关注以下事项：

• 测试表隔离：通过 TableName() 返回 test_xxx 格式，避免污染业务表
• 字段精简：测试模型只包含被测试功能涉及的字段，减少迁移复杂度
• 主键明确：始终显式声明 primaryKey，避免依赖默认 ID 字段
• 软删除控制：若测试涉及软删除，必须包含 gorm.DeletedAt 字段
• 索引验证：在测试模型中保留 uniqueIndex 和 index 标签，验证索引创建是否正确

// 冒烟回归测试专用模型示例
type TestUser struct {
  ID        uint           `gorm:"primaryKey;autoIncrement"`
  Name      string         `gorm:"column:user_name;size:100;not null"`
  Email     string         `gorm:"column:email;size:255;uniqueIndex:idx_test_email"`
  Age       int            `gorm:"column:age;default:0"`
  CreatedAt time.Time
  UpdatedAt time.Time
  DeletedAt gorm.DeletedAt `gorm:"index"`
}

// 表名隔离：添加 test_ 前缀
func (TestUser) TableName() string {
  return "test_users"
}

3.7 常见陷阱与避坑指南