声明模型

GORM 通过将 Go 结构体（Go structs） 映射到数据库表来简化数据库交互。

1 模型定义

模型是使用普通结构体定义的。 这些结构体可以包含具有基本Go类型、指针或这些类型的别名，甚至是自定义类型（只需要实现 database/sql 包中的Scanner和Valuer接口）。

GORM模型定义参考下面的示例：

type User struct {
  ID           uint           // Standard field for the primary key
  Name         string         // A regular string field
  Email        *string        // A pointer to a string, allowing for null values
  Age          uint8          // An unsigned 8-bit integer
  Birthday     *time.Time     // A pointer to time.Time, can be null
  MemberNumber sql.NullString // Uses sql.NullString to handle nullable strings
  ActivatedAt  sql.NullTime   // Uses sql.NullTime for nullable time fields
  CreatedAt    time.Time      // Automatically managed by GORM for creation time
  UpdatedAt    time.Time      // Automatically managed by GORM for update time
  ignored      string         // fields that aren't exported are ignored
}

在此模型中：

• 具体数字类型如 uint、string和 uint8 直接使用。

• 指向 *string 和 *time.Time 类型的指针表示可空字段。

• 来自 database/sql 包的 sql.NullString 和 sql.NullTime 用于具有更多控制的可空字段。

• CreatedAt 和 UpdatedAt 是特殊字段，当记录被创建或更新时，GORM 会自动向内填充当前时间。

• 未导出的字段会被忽略

除了 GORM 中模型声明的基本特性外，强调下通过 serializer 标签支持序列化也很重要。 此功能增强了数据存储和检索的灵活性，特别是对于需要自定义序列化逻辑的字段。详细说明请参见 Serializer。

2 约定

2.1 使用ID作为主键

默认情况下，GORM会使用ID作为表的主键

type User struct {
  ID   string // 默认情况下，名为 `ID` 的字段会作为表的主键
  Name string // 可以使用标签定义主键`gorm:"primarykey"`，此时会忽略ID，可以给多个字段设置标签设置为复合主键，
}

2.2 复数表名

GORM使用结构体的 蛇形命名 并加上复数作为表名。

• User -〉 users

• GormUserName -〉gorm_user_names

可以实现 Tabler 接口来更改默认表名

type Tabler interface {
    TableName() string
}

// TableName 会将 User 的表名重写为 `profiles`
func (User) TableName() string {
  return "profiles"
}

注意： TableName 不支持动态变化，它会被缓存下来以便后续使用。想要使用动态表名，你可以使用 Scopes，例如：

func UserTable(user User) func (tx *gorm.DB) *gorm.DB {
  return func (tx *gorm.DB) *gorm.DB {
    if user.Admin {
      return tx.Table("admin_users")
    }

    return tx.Table("users")
  }
}

db.Scopes(UserTable(user)).Create(&user)

2.3 临时指定表名

可以使用 Table 方法临时指定表名，例如：

// 根据 User 的字段创建 `deleted_users` 表
db.Table("deleted_users").AutoMigrate(&User{})

// 从另一张表查询数据
var deletedUsers []User
db.Table("deleted_users").Find(&deletedUsers)
// SELECT * FROM deleted_users;

db.Table("deleted_users").Where("name = ?", "jinzhu").Delete(&User{})
// DELETE FROM deleted_users WHERE name = 'jinzhu';

2.4 命名策略

GORM 允许用户通过覆盖默认的命名策略来更改默认的命名约定，该策略用于构建表名、列名、连接表名、外键关系名、检查器名、索引名。请查看 配置 以获取详细信息。

2.5 列名

根据约定，数据表的列名使用的是 struct 字段名的 蛇形命名

type User struct {  
  ID        uint      // 列名是 `id`  
  Name      string    // 列名是 `name`  
  Birthday  time.Time // 列名是 `birthday`  
  CreatedAt time.Time // 列名是 `created_at`  
}

可以使用 column 标签或 命名策略 来覆盖列名

type Animal struct {  
  AnimalID int64     `gorm:"column:beast_id"`         // 将列名设为 `beast_id`  
  Birthday time.Time `gorm:"column:day_of_the_beast"` // 将列名设为 `day_of_the_beast`  
  Age      int64     `gorm:"column:age_of_the_beast"` // 将列名设为 `age_of_the_beast`  
}

2.6 CreatedAt

对于有 CreatedAt 字段的模型，创建记录时，如果该字段值为零值，则将该字段的值设为当前时间

db.Create(&user) // 将 `CreatedAt` 设为当前时间

user2 := User{Name: "jinzhu", CreatedAt: time.Now()}
db.Create(&user2) // user2 的 `CreatedAt` 不会被修改

// 想要修改该值，可以使用 `Update`
db.Model(&user).Update("CreatedAt", time.Now())

你可以通过将 autoCreateTime 标签置为 false 来禁用时间戳追踪，例如：

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

2.7 UpdatedAt

对于有 UpdatedAt 字段的模型，更新记录时，将该字段的值设为当前时间。创建记录时，如果该字段值为零值，则将该字段的值设为当前时间

db.Save(&user) // 将 `UpdatedAt` 设为当前时间  
  
db.Model(&user).Update("name", "jinzhu") // 会将 `UpdatedAt` 设为当前时间  
  
db.Model(&user).UpdateColumn("name", "jinzhu") // `UpdatedAt` 不会被修改  
  
user2 := User{Name: "jinzhu", UpdatedAt: time.Now()}  
db.Create(&user2) // 创建记录时，user2 的 `UpdatedAt` 不会被修改  
  
user3 := User{Name: "jinzhu", UpdatedAt: time.Now()}  
db.Save(&user3) // 更新时，user3 的 `UpdatedAt` 会修改为当前时间

你可以通过将 autoUpdateTime 标签置为 false 来禁用时间戳追踪，例如：

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

3 grom.Model

GORM提供了一个预定义的结构体，名为gorm.Model，其中包含常用字段：

// gorm.Model 的定义
type Model struct {
  ID        uint           `gorm:"primaryKey"`
  CreatedAt time.Time
  UpdatedAt time.Time
  DeletedAt gorm.DeletedAt `gorm:"index"`
}

4 字段级权限控制

可导出的字段在使用 GORM 进行 CRUD 时拥有全部的权限，此外，GORM 允许用标签控制字段级别的权限。这样就可以让一个字段的权限是只读、只写、只创建、只更新或者被忽略

注意： 使用 GORM Migrator 创建表时，不会创建被忽略的字段

type User struct {
  Name string `gorm:"<-:create"` // 允许读和创建
  Name string `gorm:"<-:update"` // 允许读和更新
  Name string `gorm:"<-"`        // 允许读和写（创建和更新）
  Name string `gorm:"<-:false"`  // 允许读，禁止写
  Name string `gorm:"->"`        // 只读（除非有自定义配置，否则禁止写）
  Name string `gorm:"->;<-:create"` // 允许读和写
  Name string `gorm:"->:false;<-:create"` // 仅创建（禁止从 db 读）
  Name string `gorm:"-"`  // 通过 struct 读写会忽略该字段
  Name string `gorm:"-:all"`        // 通过 struct 读写、迁移会忽略该字段
  Name string `gorm:"-:migration"`  // 通过 struct 迁移会忽略该字段
}

5 创建/更新时间追踪

GORM 约定使用 CreatedAt、UpdatedAt 追踪创建/更新时间。如果定义了这种字段，GORM 在创建、更新时会自动填充 当前时间

要使用不同名称的字段，可以配置 autoCreateTime、autoUpdateTime 标签。

如果您想要保存 UNIX（毫/纳）秒时间戳，而不是 time，您只需简单地将 time.Time 修改为 int 即可

type User struct {
  CreatedAt time.Time // 在创建时，如果该字段值为零值，则使用当前时间填充
  UpdatedAt int       // 在创建时该字段值为零值或者在更新时，使用当前时间戳秒数填充
  Updated   int64 `gorm:"autoUpdateTime:nano"` // 使用时间戳纳秒数填充更新时间
  Updated   int64 `gorm:"autoUpdateTime:milli"` // 使用时间戳毫秒数填充更新时间
  Created   int64 `gorm:"autoCreateTime"`      // 使用时间戳秒数填充创建时间
}

6 嵌入结构体

对于匿名字段，GORM 会将其字段包含在父结构体中，例如：

type Author struct {
  Name  string
  Email string
}

type Blog struct {
  Author
  ID      int
  Upvotes int32
}
// equals
type Blog struct {
  ID      int64
  Name    string
  Email   string
  Upvotes int32
}

对于正常的结构体字段，你也可以通过标签 embedded 将其嵌入，例如：

type Author struct {
    Name  string
    Email string
}

type Blog struct {
  ID      int
  Author  Author `gorm:"embedded"` // 不使用会创建嵌套关系
  Upvotes int32
}
// 等效于
type Blog struct {
  ID    int64
  Name  string
  Email string
  Upvotes  int32
}

7 字段标签

在声明模型时，标签是可选的，GORM 支持以下标签：标签不区分大小写，但推荐使用驼峰式命名。如果使用多个标签，它们应该由分号（;）分隔。具有特殊意义的字符可以用反斜杠

标签名	说明
column	指定 db 列名
type	列数据类型，推荐使用兼容性好的通用类型，例如：所有数据库都支持 bool、int、uint、float、string、time、bytes 并且可以和其他标签一起使用，例如：not null、size, autoIncrement… 像 varbinary(8) 这样指定数据库数据类型也是支持的。在使用指定数据库数据类型时，它需要是完整的数据库数据类型，如：MEDIUMINT UNSIGNED not NULL AUTO_INCREMENT
serializer	指定将数据序列化或反序列化到数据库中的序列化器, 例如: serializer:json/gob/unixtime
size	定义列数据类型的大小或长度，例如 size: 256
primaryKey	将列定义为主键
unique	将列定义为唯一键
default	定义列的默认值
precision	指定列的精度
scale	指定列大小
not null	指定列为 NOT NULL
autoIncrement	指定列为自动增长
autoIncrementIncrement	自动步长，控制连续记录之间的间隔
embedded	嵌套字段
embeddedPrefix	嵌入字段的列名前缀
autoCreateTime	创建时追踪当前时间，对于 int 字段，它会追踪时间戳秒数，您可以使用 nano/milli 来追踪纳秒、毫秒时间戳，例如：autoCreateTime:nano
autoUpdateTime	创建/更新时追踪当前时间，对于 int 字段，它会追踪时间戳秒数，您可以使用 nano/milli 来追踪纳秒、毫秒时间戳，例如：autoUpdateTime:milli
index	根据参数创建索引，多个字段使用相同的名称则创建复合索引，查看 索引 获取详情
uniqueIndex	与 index 相同，但创建的是唯一索引
check	创建检查约束，例如 check:age > 13，查看 约束 获取详情
<-	设置字段写入的权限， <-:create 只创建、<-:update 只更新、<-:false 无写入权限、<- 创建和更新权限
->	设置字段读的权限，->:false 无读权限
-	忽略该字段，- 表示无读写，-:migration 表示无迁移权限，-:all 表示无读写迁移权限
comment	迁移时为字段添加注释

8 关联标签

GORM 允许通过标签为关联配置外键、约束、many2many 表，详情请参考 关联模式

9 时间处理

如果在字段中想使用 time.Time 必须注意几个问题：

1. 查询中数据库中返回的是string， 解决方法为在DNS中添加 ?parseTime=true 连接参数

2. 当前事情时间存入的时候ORM处理为UTC时间

   1. 使用的时候需要保证大家对时区的理解是一致的，多数采用UTC

   2. 保证写入时间和读取时间理解一致

3. 使用时间戳 -》UTC时间 -〉Local() 推荐