GORM 模型定义与标签#

基础模型#

1
type User struct {
2
  ID        uint           `gorm:"primaryKey"`
3
  Name      string         `gorm:"size:64;not null"`
4
  Email     string         `gorm:"size:255;uniqueIndex;not null"`
5
  Age       int            `gorm:"default:0"`
6
  Profile   UserProfile    // has one
7
  Orders    []Order        // has many
8
  CreatedAt time.Time
9
  UpdatedAt time.Time
10
  DeletedAt gorm.DeletedAt `gorm:"index"`
11
}

GORM 会根据字段名和类型推断列名、主键、时间字段和关联关系。显式标签适合表达数据库约束，不要把所有字段都堆满标签而失去可读性。

`gorm.Model`#

1
type Product struct {
2
  gorm.Model // ID、CreatedAt、UpdatedAt、DeletedAt
3
  Code       string `gorm:"uniqueIndex;not null"`
4
  Price      int64  `gorm:"check:price >= 0"`
5
}

嵌入 gorm.Model 会带来软删除字段。软删除记录通常不会被普通查询返回；需要查看全部记录时使用 Unscoped()。

常用标签#

标签	示例	作用
`primaryKey`	`gorm:"primaryKey"`	主键
`column`	`gorm:"column:user_name"`	指定列名
`type`	`gorm:"type:decimal(18,2)"`	指定数据库类型
`size`	`gorm:"size:128"`	字符串长度
`not null`	`gorm:"not null"`	非空约束
`default`	`gorm:"default:active"`	数据库默认值
`uniqueIndex`	`gorm:"uniqueIndex:uk_email"`	唯一索引
`index`	`gorm:"index:idx_status_created"`	普通索引
`-`	`gorm:"-"`	不映射到数据库
`embedded`	`gorm:"embedded"`	展开嵌入结构字段
`serializer`	`gorm:"serializer:json"`	序列化字段

多个标签用分号分隔：

1
Email string `gorm:"size:255;not null;uniqueIndex:uk_users_email"`

零值与默认值#

1
type User struct {
2
  Name   string `gorm:"default:guest"`
3
  Active bool   `gorm:"default:true"`
4
}

使用 Create 时，GORM 对具有默认值的字段可能跳过 Go 零值，让数据库填充默认值。若业务需要明确写入 false、0 或空字符串，应使用指针、map 或明确的列更新策略，并在测试中确认目标数据库行为。

时间字段#

字段名为 CreatedAt、UpdatedAt 时，GORM 会自动维护时间：

1
type Audit struct {
2
  CreatedAt time.Time
3
  UpdatedAt time.Time
4
}

也可以使用 Unix 时间戳字段，但必须根据字段类型和标签配置，不要同时把同一业务时间映射到多个字段而没有明确来源。

软删除#

1
type User struct {
2
  ID        uint
3
  DeletedAt gorm.DeletedAt `gorm:"index"`
4
}
5

6
db.Delete(&user)            // 设置 DeletedAt，不物理删除
7
db.Unscoped().Find(&users)  // 包含已删除记录
8
db.Unscoped().Delete(&user) // 物理删除，谨慎使用

软删除是查询范围行为，不等同于数据库级别的归档或合规删除；需要定期清理时应设计独立任务并确认恢复策略。

表名与列名#

默认情况下，结构体名会映射为蛇形复数表名，字段名映射为蛇形列名。单个模型可通过 TableName() 覆盖表名：

1
func (User) TableName() string { return "app_user" }

不要在 TableName() 中根据运行时参数返回不同结果；表名应是稳定的模型约定。

索引与约束#

1
type LoginRecord struct {
2
  UserID    uint      `gorm:"index:idx_user_created,priority:1"`
3
  CreatedAt time.Time `gorm:"index:idx_user_created,priority:2"`
4
  IP        string    `gorm:"size:45"`
5
}

索引是否有效取决于查询条件、选择性、排序和数据分布。先根据实际查询建立索引，再用 EXPLAIN 验证，不要给每个字段都加索引。

模型设计建议#

数据库模型、请求 DTO、响应 DTO 分开，避免直接把内部字段暴露给 API。
密码等敏感字段不应出现在日志和 JSON 响应中，可使用 json:"-" 或单独的响应结构。
外键字段和关联字段命名保持一致，例如 UserID 对应 User。
业务状态使用明确的类型或常量，避免在查询中散落魔法字符串。
先确定删除策略，再决定是否使用软删除。

HikariTish

GORM 模型定义与标签#

基础模型#

`gorm.Model`#

常用标签#

零值与默认值#

时间字段#

软删除#

表名与列名#

索引与约束#

模型设计建议#

官方资料#

继续阅读

换条路线

HikariTish

GORM 模型定义与标签#

基础模型#

gorm.Model#

常用标签#

零值与默认值#

时间字段#

软删除#

表名与列名#

索引与约束#

模型设计建议#

官方资料#

分享文章

沿着主题读

换条路线

`gorm.Model`#