3. 模型定义基础：结构体标签、表名映射与字段类型

在 GORM 中，模型（Model）是 Go 结构体与数据库表之间的桥梁。通过结构体标签（Tag）和约定方法，开发者可以精确控制表名、字段类型、主键、自增 ID 以及时间字段的自动管理。本章将系统讲解这些核心映射规则，帮助你写出清晰、可维护的模型定义。

3.1 结构体标签（gorm 标签）

GORM 使用 gorm 标签来定义字段级别的映射规则。标签格式为 gorm:"key1:value1;key2:value2"，多个键值对之间用分号分隔。

3.2 表名映射

GORM 默认将结构体名转换为蛇形复数形式作为表名。例如 UserInfo 对应 user_infos。当需要自定义表名时，有三种方式：

1. 实现 Tabler 接口： 定义 TableName() string 方法，返回自定义表名。
2. 使用 Table() 方法： 在查询时动态指定表名。
3. 全局表名前缀： 通过 gorm.Config 的 NamingStrategy 设置前缀。

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

func (User) TableName() string {
  return "t_user"  // 自定义表名
}

// 方式二：动态指定表名
db.Table("t_user").Where("name = ?", "张三").Find(&users)

// 方式三：全局前缀
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
  NamingStrategy: schema.NamingStrategy{
    TablePrefix: "t_",  // 所有表名自动添加 t_ 前缀
  },
})

3.3 字段类型映射

GORM 自动将 Go 数据类型映射到数据库字段类型。下表列出常见映射关系：

当需要精确控制字段类型时，使用 type 标签覆盖默认映射：

type Product struct {
  ID          uint   `gorm:"primaryKey;autoIncrement"`
  Name        string `gorm:"type:varchar(200);not null;comment:商品名称"`
  Price       float64 `gorm:"type:decimal(10,2);default:0.00"`
  Description string `gorm:"type:text"`
  Status      int8   `gorm:"type:tinyint(1);default:1;comment:状态 1-上架 0-下架"`
}

3.4 主键与自增 ID

GORM 默认将名为 ID 的字段作为主键，并自动启用自增。如果字段名不是 ID，需要显式使用 primaryKey 标签。

// 默认主键（自动识别）
type User struct {
  ID   uint   // 自动成为主键并自增
  Name string
}

// 自定义主键字段名
type Order struct {
  OrderID uint   `gorm:"primaryKey;autoIncrement;column:order_id"`
  Amount  float64
}

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

3.5 时间字段自动管理

GORM 通过约定字段名自动管理创建时间和更新时间。当结构体包含 CreatedAt 和 UpdatedAt 字段时，GORM 会在插入和更新时自动填充当前时间。

type User struct {
  ID        uint      `gorm:"primaryKey;autoIncrement"`
  Name      string    `gorm:"type:varchar(100);not null"`
  CreatedAt time.Time `gorm:"autoCreateTime"`  // 创建时自动填充
  UpdatedAt time.Time `gorm:"autoUpdateTime"`  // 更新时自动填充
  DeletedAt gorm.DeletedAt `gorm:"index"`      // 软删除字段
}

时间字段的自动管理支持三种模式：

3.6 完整模型示例

综合以上知识点，下面是一个生产级别的模型定义示例：

package model

import (
  "time"
  "gorm.io/gorm"
)

// User 用户模型
type User struct {
  ID        uint           `gorm:"primaryKey;autoIncrement;column:id"`
  Username  string         `gorm:"type:varchar(50);not null;unique;index:idx_username;comment:用户名"`
  Email     string         `gorm:"type:varchar(100);not null;unique;comment:邮箱"`
  Age       int8           `gorm:"type:tinyint(3);default:0;comment:年龄"`
  Avatar    string         `gorm:"type:varchar(255);default:'';comment:头像URL"`
  Status    int8           `gorm:"type:tinyint(1);default:1;comment:状态 1-正常 0-禁用"`
  CreatedAt time.Time      `gorm:"autoCreateTime;comment:创建时间"`
  UpdatedAt time.Time      `gorm:"autoUpdateTime;comment:更新时间"`
  DeletedAt gorm.DeletedAt `gorm:"index;comment:删除时间"`
}

// TableName 自定义表名
func (User) TableName() string {
  return "t_user"
}

3.7 常见错误与避坑指南