字段标签

字段标签是 GORM 控制字段行为的核心机制。通过标签，你可以指定字段类型、约束、索引等属性。

标签语法

标签写在结构体字段后面，格式是 gorm:"标签1;标签2:值"：

type User struct {
    Name string `gorm:"type:varchar(100);not null;uniqueIndex"`
}

多个标签用分号分隔，标签和值用冒号分隔。

常用标签

column

指定数据库列名：

type User struct {
    Name string `gorm:"column:user_name"`  // 列名 user_name
}

type

指定数据库类型：

type User struct {
    Name string `gorm:"type:varchar(50)"`
    Bio  string `gorm:"type:text"`
    Age  int    `gorm:"type:smallint"`
}

size

指定字符串长度：

type User struct {
    Name  string `gorm:"size:50"`   // varchar(50)
    Email string `gorm:"size:100"`  // varchar(100)
}

primaryKey

指定主键：

type User struct {
    UserID uint `gorm:"primaryKey"`
    Name   string
}

autoIncrement

自增字段：

type User struct {
    ID   uint `gorm:"primaryKey;autoIncrement"`
    Name string
}

default

默认值：

type User struct {
    Name   string `gorm:"default:'匿名'"`
    Age    int    `gorm:"default:18"`
    Active bool   `gorm:"default:true"`
}

字符串默认值要加引号。

not null

非空约束：

type User struct {
    Name  string `gorm:"not null"`
    Email string `gorm:"not null"`
}

unique

唯一约束：

type User struct {
    Email string `gorm:"unique"`  // 唯一约束
}

index 和 uniqueIndex

创建索引：

type User struct {
    Name  string `gorm:"index"`         // 普通索引
    Email string `gorm:"uniqueIndex"`   // 唯一索引
}

复合索引：

type User struct {
    FirstName string `gorm:"index:idx_name"`
    LastName  string `gorm:"index:idx_name"`
}

这会创建一个名为 idx_name 的复合索引。

带选项的索引：

type User struct {
    Name string `gorm:"index:idx_name,option:BTREE"`
}

comment

字段注释：

type User struct {
    Status int `gorm:"comment:用户状态:0-禁用,1-启用"`
}

约束标签

foreignKey

外键约束：

type Order struct {
    ID     uint
    UserID uint
    User   User `gorm:"foreignKey:UserID"`
}

references

外键引用：

type Order struct {
    ID     uint
    UserID uint
    User   User `gorm:"foreignKey:UserID;references:ID"`
}

constraint

约束选项：

type Order struct {
    ID     uint
    UserID uint
    User   User `gorm:"constraint:OnDelete:CASCADE;"`
}

读写控制标签

只写

type User struct {
    Password string `gorm:"<-:create"`  // 只在创建时可写
}

只读

type User struct {
    ViewCount int `gorm:"->:false"`  // 只读，不写入数据库
}

忽略

type User struct {
    Confirm string `gorm:"-"`  // 完全忽略
}

选择性忽略

type User struct {
    Name     string `gorm:"<-:create"`  // 创建时可写
    UpdateBy string `gorm:"<-:update"`  // 更新时可写
}

序列化标签

type User struct {
    Settings map[string]string `gorm:"serializer:json"`
    Tags     []string          `gorm:"serializer:json"`
}

标签组合示例

一个完整的字段定义：

type User struct {
    ID        uint      `gorm:"primaryKey;autoIncrement;comment:用户ID"`
    Name      string    `gorm:"type:varchar(50);not null;index;comment:用户名"`
    Email     string    `gorm:"type:varchar(100);uniqueIndex;not null;comment:邮箱"`
    Password  string    `gorm:"type:varchar(255);not null;comment:密码"`
    Age       int       `gorm:"type:tinyint unsigned;default:0;comment:年龄"`
    Status    int       `gorm:"type:tinyint;default:1;comment:状态"`
    Bio       string    `gorm:"type:text;comment:个人简介"`
    CreatedAt time.Time `gorm:"autoCreateTime;comment:创建时间"`
    UpdatedAt time.Time `gorm:"autoUpdateTime;comment:更新时间"`
}

时间相关标签

autoCreateTime

创建时自动设置：

type User struct {
    CreatedAt time.Time `gorm:"autoCreateTime"`
}

autoUpdateTime

更新时自动更新：

type User struct {
    UpdatedAt time.Time `gorm:"autoUpdateTime"`
}

时间戳格式

type User struct {
    CreatedAt int64 `gorm:"autoCreateTime:milli"`  // 毫秒时间戳
    UpdatedAt int64 `gorm:"autoUpdateTime:nano"`  // 纳秒时间戳
}

嵌入标签

嵌入其他结构体：

type BaseModel struct {
    ID        uint `gorm:"primaryKey"`
    CreatedAt time.Time
    UpdatedAt time.Time
}

type User struct {
    BaseModel `gorm:"embedded"`
    Name      string
}

嵌入时加前缀：

type User struct {
    BaseModel `gorm:"embedded;embeddedPrefix:base_"`
    Name      string
}
// 结果: base_id, base_created_at, base_updated_at

小结

常用标签速查：

标签是 GORM 的精髓，熟练使用标签可以精确控制数据库结构。