GORM 常用 Tag 速查手册
本手册按「功能场景」分类，整理 GORM 开发中高频使用的 Tag，包含 Tag 表达式、作用说明、数据库效果、使用示例，方便快速查阅与实操参考（默认数据库环境为 MySQL）。
一、字段映射与基础属性
用于控制结构体字段与数据库列的映射关系、数据类型等基础配置。
| Tag 表达式 | 作用说明 | 数据库效果（MySQL） | 使用示例 |
|---|---|---|---|
gorm:"column:自定义列名" |
自定义数据库列名，覆盖默认蛇形命名（如 UserID 默认→user_id） |
列名设为「自定义列名」 | ID uint gorm:"column:user_id" |
gorm:"type:数据类型" |
指定数据库字段类型，覆盖 GORM 对 Go 类型的默认推断（如 string 默认→varchar(255)） | 列类型设为指定类型（如 varchar(50)） |
Name string gorm:"type:varchar(50)" |
gorm:"primaryKey" |
标记字段为主键（支持复合主键，多个字段加此 Tag） | 列添加 PRIMARY KEY 约束 |
ID uint gorm:"primaryKey" |
gorm:"autoIncrement" |
标记字段为自增（通常配合主键使用，uint 主键默认自增，非必需显式加） | 列添加 AUTO_INCREMENT |
ID uint gorm:"primaryKey;autoIncrement" |
gorm:"-" |
忽略字段，不映射到数据库（不参与建表、CRUD 操作） | 字段不生成对应列 | Password string gorm:"-" |
二、约束与默认值
用于添加数据库级别的字段约束（非空、唯一）和默认值配置。
| Tag 表达式 | 作用说明 | 数据库效果（MySQL） | 使用示例 |
|---|---|---|---|
gorm:"not null" |
限制字段非空，插入/更新时必须传值（否则数据库报错） | 列添加 NOT NULL 约束 |
Email string gorm:"not null" |
gorm:"default:默认值" |
设置数据库字段默认值（仅插入时生效，未传值则用默认值；注意：非 Go 代码默认值） | 列添加 DEFAULT 默认值（如 DEFAULT 18） |
Age int gorm:"default:18" |
gorm:"unique" |
限制字段值唯一（仅加约束，不主动创建索引，建议优先用 uniqueIndex） |
列添加 UNIQUE 约束 |
Phone string gorm:"unique" |
三、索引配置
用于创建数据库索引，提升查询效率（索引类型对应不同查询场景）。
| Tag 表达式 | 作用说明 | 数据库效果（MySQL） | 使用示例 |
|---|---|---|---|
gorm:"index" |
创建普通索引（非唯一，适用于高频查询字段，如状态、分类） | 生成 INDEX 索引名(列名)（如 INDEX idx_status(status)） |
Status int gorm:"index" |
gorm:"index:自定义索引名" |
创建普通索引并指定索引名（避免默认名混乱，多字段索引必用） | 生成 INDEX 自定义索引名(列1,列2) |
Age int gorm:"index:idx_user_age" |
gorm:"uniqueIndex" |
创建唯一索引（既保证值唯一，又提升查询效率，推荐替代 unique） |
生成 UNIQUE INDEX 索引名(列名) |
Email string gorm:"uniqueIndex" |
gorm:"uniqueIndex:自定义索引名" |
创建唯一索引并指定索引名（多字段唯一约束场景必备） | 生成 UNIQUE INDEX 自定义索引名(列1,列2) |
Username string gorm:"uniqueIndex:idx_username" |
四、时间自动填充
GORM 内置的时间字段自动管理，无需手动赋值（高频用于创建/更新时间）。
| Tag 表达式 | 作用说明 | 数据库效果（MySQL） | 使用示例 |
|---|---|---|---|
gorm:"autoCreateTime" |
插入记录时，自动填充当前时间（仅触发一次，适用于 CreatedAt 字段） |
列添加 DEFAULT CURRENT_TIMESTAMP |
CreatedAt time.Time gorm:"autoCreateTime" |
gorm:"autoUpdateTime" |
插入/更新记录时，自动填充当前时间（每次修改都更新，适用于 UpdatedAt 字段） |
列添加 DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP |
UpdatedAt time.Time gorm:"autoUpdateTime" |
五、特殊功能
处理软删除、字段序列化等特殊业务场景。
| Tag 表达式 | 作用说明 | 数据库效果（MySQL） | 使用示例 |
|---|---|---|---|
gorm:"serializer:json" |
将 Go 结构体/Map 序列化为 JSON 字符串存入数据库，读取时自动反序列化 | 列类型设为 text（存储 JSON 格式字符串） |
Profile map[string]any gorm:"serializer:json" |
gorm:"index"（配合 gorm.DeletedAt） |
为软删除字段创建索引（gorm.DeletedAt 是 GORM 内置软删除类型，非 NULL 表示已删除） |
列添加 INDEX 索引名(deleted_at)，类型为 datetime |
DeletedAt gorm.DeletedAt gorm:"index" |
六、常用 Tag 组合示例
实际开发中常将多个 Tag 组合使用，以下是典型场景的配置示例：
| 业务场景 | 结构体字段配置（Tag 组合） | 说明 |
|---|---|---|
| 自增主键 | ID uint gorm:"primaryKey;autoIncrement;column:user_id" |
自定义列名 user_id，自增主键 |
| 唯一非空的用户邮箱 | Email string gorm:"type:varchar(100);not null;uniqueIndex:idx_user_email" |
限制长度+非空+唯一索引，防重复邮箱 |
| 带默认值的用户状态 | Status int8 gorm:"type:tinyint;default:1;index:idx_user_status" |
用 tinyint 省空间+默认启用+查询索引 |
| 软删除+自动时间 | DeletedAt gorm.DeletedAt gorm:"index"<br>CreatedAt time.Time gorm:"autoCreateTime" ` |
软删除索引+创建时间自动填充 |
七、使用提示
- 优先级规则 ：字段显式
columnTag > 全局命名策略 > 默认蛇形命名。 - 索引注意：高频查询字段加普通索引，唯一值字段加唯一索引，避免过度索引（影响写入性能）。
- 默认值误区 ：
default是数据库级默认值，若 Go 代码传"零值"（如 0、""），会覆盖默认值。 - 调试技巧 ：开启 GORM 日志（
Logger: logger.Default.LogMode(logger.Info)），可查看 Tag 对应的建表 SQL。