GORM 结构体字段标签（Struct Tags）详解

一、GORM 模型字段标签基础语法

GORM 使用 struct tag 定义字段行为：

type User struct { FieldName DataType `gorm:"tag1:value1;tag2:value2" json:"field_name"` }

优先级（从高到低）：

1. gorm:"..."主控制标签（数据库行为）

2. 其他标签（json、form 等）

3. 结构体字段名作为默认列名（SnakeCase）

二、字段标签分类与详解（最重要部分）

1. 基本字段标签

(1) column（指定数据库列名）

gorm:"column:user_name"

(2) type（指定数据库字段类型）

gorm:"type:varchar(100)"

(3) primaryKey（主键）

gorm:"primaryKey"

(4) autoIncrement（自增）

与 primaryKey 组合常用。

gorm:"primaryKey;autoIncrement"

(5) unique / uniqueIndex（唯一约束）

gorm:"unique" // 单字段唯一 gorm:"uniqueIndex" // 创建唯一索引 gorm:"uniqueIndex:idx_name" // 复合唯一索引

(6) index（普通索引）

gorm:"index" // 单字段索引 gorm:"index:idx_name" // 指定索引名 gorm:"index:idx_name,priority:1" // 复合索引顺序

(7) size（字符串长度）

gorm:"size:255"

(8) default（默认值）

gorm:"default:0" gorm:"default:'unknown'"

(9) not null（非空）

gorm:"not null"

(10) <- / ->（字段读写权限）

控制 GORM 是否对该字段进行写入或读取：

gorm:"<-:create" // 仅创建时写入 gorm:"<-:update" // 仅更新时写入 gorm:"<-:false" // 禁止写入 gorm:"->:false" // 查询不读该字段 gorm:"-:" // 读写都禁用 gorm:"-" // 完全忽略该字段

2. 时间相关标签（CreateAt/UpdatedAt）

(1) autoCreateTime（创建自动填充）

gorm:"autoCreateTime" gorm:"autoCreateTime:milli" // 毫秒 gorm:"autoCreateTime:nano" // 纳秒

(2) autoUpdateTime（更新自动填充）

gorm:"autoUpdateTime" gorm:"autoUpdateTime:milli" gorm:"autoUpdateTime:nano"

3. 外键 / 关联关系标签

(1) foreignKey（外键字段）

gorm:"foreignKey:UserID"

(2) references（指定关联的字段）

gorm:"references:ID"

(3) constraint（外键约束）

gorm:"constraint:OnUpdate:CASCADE,OnDelete:SET NULL;"

(4) many2many（多对多中间表）

gorm:"many2many:user_roles"

(5) polymorphic（多态关联）

gorm:"polymorphic:Owner"

4. Serializer（序列化字段）

适用于 JSON、MsgPack 等类型存储。

(1) 保存为 JSON

gorm:"serializer:json"

示例：

type User struct { Hobbies []string `gorm:"serializer:json"` }

5. Embedded / EmbeddedPrefix（嵌入字段）

(1) embedded（字段嵌入，不创建嵌套）

gorm:"embedded"

(2) embeddedPrefix（嵌入字段添加前缀）

gorm:"embeddedPrefix:user_"

6. comment（字段注释）

gorm:"comment:'用户年龄'"

三、字段标签使用示例（非常完整）

下面是一个实际业务级别的模型，涵盖各种标签。

type User struct { ID uint `gorm:"primaryKey;autoIncrement;comment:'主键ID'"` UserName string `gorm:"column:user_name;type:varchar(50);uniqueIndex;not null;comment:'用户名'"` Email string `gorm:"type:varchar(100);index:idx_email;not null;comment:'邮箱地址'"` Age int `gorm:"default:0;comment:'年龄'"` Profile UserProfile `gorm:"embedded;embeddedPrefix:profile_"` Tags []string `gorm:"serializer:json;comment:'标签(JSON)'"` CreatedAt time.Time `gorm:"autoCreateTime"` UpdatedAt time.Time `gorm:"autoUpdateTime"` DeletedAt gorm.DeletedAt `gorm:"index"` } type UserProfile struct { Address string `gorm:"type:varchar(200)"` Avatar string `gorm:"type:varchar(255)"` }

四、关联模型完整示例

1. 一对多（User 有多个 Orders）

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

2. 多对多（Users 共享 Roles）

type User struct { ID uint Roles []Role `gorm:"many2many:user_roles"` } type Role struct { ID uint Name string }

五、GORM 中 Tag 的常见坑和注意事项

1. default 只在建表时生效，不影响运行时零值

如果字段是 0 或 ""，GORM 不会主动应用 default。

解决方法：

Age *int `gorm:"default:18"`

2. 字段必须导出（首字母大写）GORM 才能识别

3. 没有not null时，GORM 不会自动加默认非空

4. JSON serializer 必须使用 slice 或 map，不支持 struct 直接存储 unless implement Scanner/Valuer

5. uniqueIndex 必须在 AutoMigrate 后才能生效

六、总结表：最常用的 GORM Tag 清单