gorm(1) 入门

GORM(1) 入门

---

说明

此博客仅供个人学习，大部分内容为官网 GORM指南 中的内容转载，还有博主一些的个人理解与代码说明；

介绍

Golang写的，开发人员友好的ORM库；

• 全功能 ORM
• 关联 (Has One，Has Many，Belongs To，Many To Many，多态，单表继承)
• Create，Save，Update，Delete，Find 中钩子方法
• 支持 Preload、Joins 的预加载
• 事务，嵌套事务，Save Point，Rollback To Saved Point
• Context、预编译模式、DryRun 模式
• 批量插入，FindInBatches，Find/Create with Map，使用 SQL 表达式、Context Valuer 进行 CRUD
• SQL 构建器，Upsert，数据库锁，Optimizer/Index/Comment Hint，命名参数，子查询
• 复合主键，索引，约束
• Auto Migration
• 自定义 Logger
• 灵活的可扩展插件 API：Database Resolver（多数据库，读写分离）、Prometheus…
• 每个特性都经过了测试的重重考验
• 开发者友好

简而言之就是go后端编写数据库语句并执行的工具；

---

安装

在工作空间中创建一个新的文件夹，使用

go mod init gorm/example

初始化；

cmd中输入

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

安装gorm；

温馨提示

对于下方的代码，若import部分产生红色预警，请使用

go mod tidy

将包引入本地中；

---

快速开始

package main

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

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

func main() {
  db, err := gorm.Open(sqlite.Open("test.db"), &gorm.Config{})
  if err != nil {
    panic("failed to connect database")
  }

  // 迁移 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)
}

仅供演示;

---

模型定义

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

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

举例：

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 标签支持序列化也很重要。 此功能增强了数据存储和检索的灵活性，特别是对于需要自定义序列化逻辑的字段。

约定

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

​ 遵循这些约定可以大大减少您需要编写的配置或代码量。 但是，GORM也具有灵活性，允许您根据自己的需求自定义这些设置。 您可以在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 允许您用标签控制字段级别的权限。这样您就可以让一个字段的权限是只读、只写、只创建、只更新或者被忽略；

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.Model这个gorm包定义的匿名字段），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
}

字段标签

声明 model 时，tag 是可选的，GORM 支持以下 tag： tag 名大小写不敏感，但建议使用 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 官方支持的数据库类型有：MySQL, PostgreSQL, SQLite, SQL Server 和 TiDB；

MySQL

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{})
}

对于DSN数据源名称配置（即上面代码的dsn变量）具有通用格式：

[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...&paramN=valueN]

最完整形式的DSN：

username:password@protocol(address)/dbname?param=value

通俗的理解：

数据库用户名:数据库密码@协议(地址:端口)/数据库名?参数键1=参数值1&参数键2=参数值2

一般设置参数charset，用于设置客户端-服务端交互的字符集；

设置parseTime，是否匹配date或是dateTime的时间格式，布尔类型；

设置loc，设置时间的时区，可以定义为Local即本地所在ip当地的时间，但此定义权限小于mysql配置中的时区设置；

还可以使用go内置包"database/sql"建立sql数据库连接，再使用

mysql.New(mysql.Config{
Conn: sqlDB,
})

获取gorm.Dialector实例；

sqlDB, err := sql.Open("mysql", "mydb_dsn")
gormDB, err := gorm.Open(mysql.New(mysql.Config{
  Conn: sqlDB,
}), &gorm.Config{})

---

插入操作

演示

gorm官网中并没有举例出可运行的实例，博主我在此展示一个可运行的插入操作：

package main

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

type Student struct {
	gorm.Model
	Name string
	Sex  string
}

func main() {
    dsn := "数据库用户名:你自己的密码@tcp(localhost:3306)/test?charset=utf8mb4&parseTime=True&loc=Local"
	db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
	if err != nil {
		log.Fatalf("连接报错 %v",err)
	}
    db.AutoMigrate(&Student{})
	student := Student{Name: "lxh",Sex: "男"}
	result := db.Create(&student)
	if result.Error != nil {
		log.Fatal(result.Error)
	} else {
		fmt.Printf("共插入%d条数据", result.RowsAffected)
	}
}

首先定义了一个Student结构体，用于映射数据库表；

包含gorm.Model匿名体；

使用

gorm.Open()

连接数据库;

先使用数据库工具navicat在本地创建了一个test库；

对于建表，可以使用

db.AutoMigrate(&Student{})

在test库中自动创建名为students的表格，结构与Student结构体对应；

当然也可以不使用此语句，自己在数据库中手动创建students表，因为约定大于一切，注意表名需要加上复数s，如果go中结构体为studentTable，则数据库中表对应为student_tables；

定义列名

均为小写，a_b格式，约定大于一切！

使用db.Create()插入一个结构体数据，只需要定义gorm.Model之外的属性，gorm.Model的ID默认为主键（在数据库工具中设置为自动递增），CreatedAt默认创建时插入，UpdatedAt默认更改时刷新，DeletedAt默认删除时更新,约定大于一切;

当然也可以不用gorm.Model，只是演示一下，可以自己定义主键与创建更新时间；

例如对于结构体

type User struct {
	ID          string
	Name        string
	Password    string
	GmtCreated  time.Time
	GmtModified time.Time
}

用指定字段创建记录

创建记录并为指定字段赋值:

db.Select("Name", "Age", "CreatedAt").Create(&user)
// INSERT INTO `users` (`name`,`age`,`created_at`) VALUES ("jinzhu", 18, "2020-07-04 11:05:21.775")

创建记录并忽略传递给 ‘Omit’ 的字段值:

db.Omit("Name", "Age", "CreatedAt").Create(&user)
// INSERT INTO `users` (`birthday`,`updated_at`) VALUES ("2020-01-01 00:00:00.000", "2020-07-04 11:05:21.775")

批量插入

要高效地插入大量记录，请将切片传递给Create方法。 GORM 将生成一条 SQL 来插入所有数据，以返回所有主键值，并触发 Hook 方法。 当这些记录可以被分割成多个批次时，GORM会开启一个事务</0>来处理它们；

var users = []User{{Name: "jinzhu1"}, {Name: "jinzhu2"}, {Name: "jinzhu3"}}
db.Create(&users)

for _, user := range users {
  user.ID // 1,2,3
}

你可以通过db.CreateInBatches方法来指定批量插入的批次大小：

var users = []User{{Name: "jinzhu_1"}, ...., {Name: "jinzhu_10000"}}

// batch size 100
db.CreateInBatches(users, 100)

创建钩子

GROM允许用户通过实现这些接口 BeforeSave, BeforeCreate, AfterSave, AfterCreate来自定义钩子。 这些钩子方法会在创建一条记录时被调用，比如说设置id为随机值，关于钩子的生命周期请参阅Hooks。

func (u *User) BeforeCreate(tx *gorm.DB) (err error) {
  u.UUID = uuid.New()

    if u.Role == "admin" {
        return errors.New("invalid role")
    }
    return
}

如果你想跳过Hooks方法，可以使用SkipHooks会话模式，例子如下

DB.Session(&gorm.Session{SkipHooks: true}).Create(&user)

DB.Session(&gorm.Session{SkipHooks: true}).Create(&users)

DB.Session(&gorm.Session{SkipHooks: true}).CreateInBatches(users, 100)

根据 Map 创建

GORM支持通过 map[string]interface{} 与 []map[string]interface{}{}来创建记录。

db.Model(&User{}).Create(map[string]interface{}{
  "Name": "jinzhu", "Age": 18,
})

// batch insert from `[]map[string]interface{}{}`
db.Model(&User{}).Create([]map[string]interface{}{
  {"Name": "jinzhu_1", "Age": 18},
  {"Name": "jinzhu_2", "Age": 20},
})

注意当使用map来创建时，钩子方法不会执行，关联不会被保存且不会回写主键。

其他

对于使用 SQL 表达式、Context Valuer 创建记录与高级选项，博主看不懂，大家想进一步了解的可以直接访问官网哈创建 | GORM - The fantastic ORM library for Golang, aims to be developer friendly.