GORM介绍及入门指南

GORM

本文后半部分来源于GORM官方文档。

GORM的介绍

什么是GORM？

GORM 是一个适用于 Go 语言的 ORM（对象关系映射）库。ORM 的目的是让开发者能够通过面向对象的方式与数据库交互，而不是直接编写 SQL 语句。GORM 使得操作数据库更加高效和便捷，同时保留了 Go 语言的简洁性和灵活性。

GORM 的特点

1. 简单易用的 API：GORM 提供了简单且直观的 API，开发者可以通过链式调用来完成数据库操作。无论是插入、查询、更新还是删除操作，GORM 都提供了统一且易于理解的方法。
2. 自动迁移：自动迁移功能允许开发者定义数据模型，然后 GORM 会根据这些模型自动创建或更新数据库表结构。这大大简化了数据库的管理和维护工作。
3. 多数据库支持：GORM 支持多种常见的数据库系统，包括 MySQL、PostgreSQL、SQLite 和 SQL Server 等。开发者可以根据需要选择合适的数据库，而无需担心 ORM 的兼容性问题。
4. 关系映射：GORM 支持定义和处理数据库表之间的关系，包括一对一、一对多和多对多关系。通过简单的配置，开发者可以轻松管理复杂的数据关系。
5. 灵活的查询功能：GORM 提供了强大的查询功能，支持条件查询、链式查询和原生 SQL 查询。开发者可以根据需求灵活构建复杂的查询语句。
6. 事务支持：事务是一种确保数据库操作一致性的机制。GORM 提供了对事务的完整支持，开发者可以在需要时使用事务来保证数据操作的原子性。
7. 钩子函数：GORM 支持钩子函数（Hooks），允许开发者在特定操作前后执行自定义逻辑。例如，可以在插入数据前进行数据验证，或者在删除数据后进行日志记录。

GORM 的使用场景

GORM 适用于各种类型的 Go 语言项目，特别是在需要频繁与数据库交互的应用中，例如：

• Web 应用程序
• 微服务架构
• 数据分析系统
• 内容管理系统（CMS）
• 电子商务平台

GORM官方文档：

官方文档：GORM官方文档

GORM入门指南

1. 简单使用

1. GORM的安装

go get -u gorm.io/gorm
go get -u gorm.io/driver/mysql

2.数据库连接

GORM 官方支持的数据库类型有：MySQL, PostgreSQL, SQLite, SQL Server 和 TiDB

import (
  "gorm.io/driver/mysql"
  "gorm.io/gorm"
)

func main() {
  // 参考 https://github.com/go-sql-driver/mysql#dsn-data-source-name 获取详情
  dsn := "user:pass@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
  db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
}

3. 快速入门

package main

import (
  "gorm.io/gorm"
  "gorm.io/driver/sqlite"
)

type Product struct {
  gorm.Model
  Code  string
  Price uint
}

func main() {
  dsn := "root:123456@tcp(127.0.0.1:3309)/try_gorm?charset=utf8mb4&parseTime=True&loc=Local"
  db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
	if err != nil {
		panic(err)
	}

  // 迁移 schema
  db.AutoMigrate(&Product{})

  // Create
  db.Create(&Product{Code: "D42", Price: 100})

  // Read
  var product Product
  db.First(&product, 1) // 根据整型主键查找
  db.First(&product, "code = ?", "D42") // 查找 code 字段值为 D42 的记录

  // Update - 将 product 的 price 更新为 200
  db.Model(&product).Update("Price", 200)
  // Update - 更新多个字段
  db.Model(&product).Updates(Product{Price: 200, Code: "F42"}) // 仅更新非零值字段
  db.Model(&product).Updates(map[string]interface{}{"Price": 200, "Code": "F42"})

  // Delete - 删除 product
  db.Delete(&product, 1)
}

2. 声明模型

GORM 通过将 Go 结构体（Go structs） 映射到数据库表来简化数据库交互。 了解如何在GORM中定义模型，是充分利用GORM全部功能的基础。

模型定义

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

考虑以下 user 模型的示例：

type User struct {
  ID           uint           // Standard field for the primary key
  Name         string         // 一个常规字符串字段
  Email        *string        // 一个指向字符串的指针, allowing for null values
  Age          uint8          // 一个未签名的8位整数
  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      // 创建时间（由GORM自动管理）
  UpdatedAt    time.Time      // 最后一次更新时间（由GORM自动管理）
}

在此模型中：

• 具体数字类型如 uint、string和 uint8 直接使用。
• 指向 *string 和 *time.Time 类型的指针表示可空字段。
• 来自 database/sql 包的 sql.NullString 和 sql.NullTime 用于具有更多控制的可空字段。
• CreatedAt 和 UpdatedAt 是特殊字段，当记录被创建或更新时，GORM 会自动向内填充当前时间。

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

约定

1. 主键：GORM 使用一个名为ID 的字段作为每个模型的默认主键。
2. 表名：默认情况下，GORM 将结构体名称转换为 snake_case 并为表名加上复数形式。 例如，一个 User 结构体在数据库中的表名变为 users 。
3. 列名：GORM 自动将结构体字段名称转换为 snake_case 作为数据库中的列名。
4. 时间戳字段：GORM使用字段 CreatedAt 和 UpdatedAt 来自动跟踪记录的创建和更新时间。

遵循这些约定可以大大减少您需要编写的配置或代码量。 但是，GORM也具有灵活性，允许您根据自己的需求自定义这些设置。 您可以在GORM的约定文档中了解更多关于自定义这些约定的信息。

gorm.Model

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

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

• 将其嵌入在您的结构体中: 您可以直接在您的结构体中嵌入 gorm.Model ，以便自动包含这些字段。 这对于在不同模型之间保持一致性并利用GORM内置的约定非常有用，请参考嵌入结构。

• 包含的字段：

  • ID ：每个记录的唯一标识符（主键）。
  • CreatedAt ：在创建记录时自动设置为当前时间。
  • UpdatedAt：每当记录更新时，自动更新为当前时间。
  • DeletedAt：用于软删除（将记录标记为已删除，而实际上并未从数据库中删除）。

高级选项

字段级权限控制

可导出的字段在使用 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 迁移会忽略该字段
}

创建/更新时间追踪（纳秒、毫秒、秒、Time）

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"`      // 使用时间戳秒数填充创建时间
}

嵌入结构体

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

type User struct {
  gorm.Model
  Name string
}
// 等效于
type User struct {
  ID        uint           `gorm:"primaryKey"`
  CreatedAt time.Time
  UpdatedAt time.Time
  DeletedAt gorm.DeletedAt `gorm:"index"`
  Name string
}

对于正常的结构体字段，你也可以通过标签 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
}

并且，您可以使用标签 embeddedPrefix 来为 db 中的字段名添加前缀，例如：

type Blog struct {
  ID      int
  Author  Author `gorm:"embedded;embeddedPrefix:author_"`
  Upvotes int32
}
// 等效于
type Blog struct {
  ID          int64
  AuthorName string
  AuthorEmail string
  Upvotes     int32
}

字段标签

声明模型时可以选择使用标签，GORM 支持以下标签： 标签不区分大小写，但首选 camelCase 。如果使用多个标签，则应使用分号 ( ; ) 分隔它们。对解析器具有特殊含义的字符可以使用反斜杠 ( \ ) 进行转义，从而将它们用作参数值。

标签名	说明
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	迁移时为字段添加注释

关联标签

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