从 v1.14 升级到 v1.15

升级指南

预计升级时间：10 分钟

随着 Golang v1.21 不再被维护，Goravel v1.15 默认支持 Golang 版本由 1.21 升级为 1.22，请在 go.mod 文件中更新版本。

1. 更新依赖

go get -u github.com/goravel/framework@v1.15.2

// 如果使用 gin
go get -u github.com/goravel/gin@v1.3.2

// 如果使用 fiber
go get -u github.com/goravel/fiber@v1.3.2

// 如果使用 redis
go get -u github.com/goravel/redis@v1.3.0

// 如果使用 S3
go get -u github.com/goravel/s3@v1.3.2

// 如果使用 Oss
go get -u github.com/goravel/oss@v1.3.2

// 如果使用 Cos
go get -u github.com/goravel/cos@v1.3.2

// 如果使用 Minio
go get -u github.com/goravel/minio@v1.3.2

// 如果使用 Cloudinary
go get -u github.com/goravel/cloudinary@v1.3.1

go mod tidy

2. 如果正在使用 Postgres 数据库

需相应修改：Postgresql 驱动名称更改为 Postgres

3. 如果正在使用 Orm.Transaction 方法

需相应修改：修改 Orm.Transaction 方法回调参数类型

4. 如果正在使用 Orm 的 Delete 或 ForceDelete 方法

需相应修改：优化 Orm 的 Delete 与 ForceDelete 方法

5. 如果正在使用 Cache 的 Decrement 或 Increment 方法

需相应修改：优化 Cache 的 Decrement 与 Increment 方法

6. 如果正在使用 Queue 模块的 Worker 方法

需相应修改：优化 Queue 模块的 Worker 方法

7. 如果正在使用 Artisan 的 Call 方法

需相应修改：优化 Artisan 的 Call 方法

8. 如果正在使用 Testing.Database 的 Clear 方法

需相应修改：Testing.Database 的 Clear 方法重命名为 Shutdown

9. 如果正在使用 Testing.Database 的 Build 方法

需相应修改：优化 Testing.Database 的 Build 方法

10. 如果正在使用 Migration 模块

修改 config/database.go 中的配置：

-- "migrations": "migrations",
++ "migrations": map[string]any{
++    "driver": "sql",
++    "table":  "migrations",
++ },

11. 如果正在使用 Request.Input* 方法

需相应修改：优化 Request.Input* 方法

12. 如果正在使用 validation.PrepareForValidation 方法

需相应修改：优化 validation.PrepareForValidation 方法

13. 如果正在使用 Mail 模块

修改 Subject 的设置方式：

-- import "github.com/goravel/framework/contracts/mail"
++ import "github.com/goravel/framework/mail"

-- facades.Mail().Content(mail.Content{Subject: "Subject", Html: "<h1>Hello Goravel</h1>"})
++ facades.Mail().Content(mail.Html("<h1>Hello Goravel</h1>")).Subject("Subject")

如果使用了 From 方法：

-- import "github.com/goravel/framework/contracts/mail"
++ import "github.com/goravel/framework/mail"

-- facades.Mail().From(mail.From{Address: testFromAddress, Name: testFromName})
++ facades.Mail().From(mail.Address(testFromAddress, testFromName))

如果使用了 Queue 方法：

-- import "github.com/goravel/framework/contracts/mail"
++ import "github.com/goravel/framework/mail"

-- facades.Mail().Queue(mail.Queue{Connection: "high", Queue: "mail"})
++ facades.Mail().Queue(mail.Queue().Connection("high").Queue("mail"))

功能介绍

Migration 支持使用 Go 语言迁移

之前框架仅支持 SQL 迁移，当想要切换数据库时，由于不同数据库间的 SQL 语法差异，将使迁移过程极其困难。此外，迁移文件中也无法执行代码，在进行数据修复时，无法进行逻辑判断。

现在框架支持直接使用 Go 语言生成迁移文件，方便开发者编写复杂的迁移逻辑。但在当前版本中，尚未实现对表字段的修改功能，仅支持创建表、删除表、创建索引等操作。如果想进行修改，需要使用 Sql 方法直接执行 SQL 语句。修改表字段的功能将在后续版本中支持。

在 v1.15 版本中，框架同时支持 Go 语言迁移（默认）和 SQL 迁移，但 SQL 迁移将在 v1.16 版本中移除。

由 SQL 迁移切换到 Go 语言迁移

如果你正在使用 SQL 迁移，可以通过以下步骤切换到 Go 语言迁移：

修改 config/database.go 中的配置

-- "migrations": "migrations",
++ "migrations": map[string]any{
++    "driver": "default",
++    "table":  "migrations",
++ },

使用 go run . artisan make:migration {NAME} 命令创建迁移文件

在生成的文件的 Up, Down 方法中，分别执行原 SQL 迁移文件中的迁移、回滚语句：

return facades.Schema().Sql({SQL})

注册迁移文件到 database/kernel.go 文件

新建 database/kernel.go 文件，并注册迁移文件与 Seeder：

package database

import (
  "github.com/goravel/framework/contracts/database/schema"
  "github.com/goravel/framework/contracts/database/seeder"

  "goravel/database/migrations"
  "goravel/database/seeders"
)

type Kernel struct {
}

func (kernel Kernel) Migrations() []schema.Migration {
  return []schema.Migration{
    &migrations.M20241207095921CreateUsersTable{},
  }
}

func (kernel Kernel) Seeders() []seeder.Seeder {
  return []seeder.Seeder{
    &seeders.DatabaseSeeder{},
  }
}

修改 app/providers/database_service_provider.go 文件完成注册，请将原本在此注册的 Seeder 移动到 database/kernel.go::Seeders

-- func (receiver *DatabaseServiceProvider) Boot(app foundation.Application) {
--   facades.Seeder().Register([]seeder.Seeder{
--     &seeders.DatabaseSeeder{},
--   })
-- }
++ func (receiver *DatabaseServiceProvider) Boot(app foundation.Application) {
++   kernel := database.Kernel{}
++   facades.Schema().Register(kernel.Migrations())
++   facades.Seeder().Register(kernel.Seeders())
++ }

查看文档

Testing 支持 HTTP 测试

goravel/framework: v1.15.0

框架新增 Testing.Http 模块，支持对 HTTP 请求进行测试，可以模拟请求、获取响应、断言响应等。

查看文档

HTTP 支持返回 Stream

goravel/framework: v1.15.0

查看文档

HTTP 支持设置超时时间

goravel/framework: v1.15.0

可以通过在 config/http.go 文件中配置 http.request_timeout 设置超时时间，默认为 3 秒。

HTTP 支持设置自定义 recovery 方法

goravel/framework: v1.15.0

查看文档

HTTP Response 支持 Abort

goravel/framework: v1.15.0

查看文档

Request 支持设置 Filter

goravel/framework: v1.15.0

查看文档

Request 增加 BindQuery 方法

goravel/framework: v1.15.0

支持使用 ctx.Request().BindQuery() 直接绑定链接中的参数。

查看文档

Validation 支持 Regex 规则

goravel/framework: v1.15.0

validator, err := ctx.Request().Validate(map[string]string{
  "code": `required|regex:^\d{4,6}$`,
})

Schedule 支持控制日志输出

goravel/framework: v1.15.0

当 app.debug 为 false 时，将只输出 error 级别日志。

Schedule 新增 Shutdown 方法

使得可以优雅的关闭 Schedule。

goravel/framework: v1.15.0

查看文档

Mail 支持 Mailable 模版

goravel/framework: v1.15.0

查看文档

Log 错误日志输出的 trace 支持点击跳转

goravel/framework: v1.15.0

在错误日志输出中，点击 trace 可以跳转到错误发生的代码行。

Log 支持打印 Context 中的键值

goravel/framework: v1.15.0

ctx.WithValue("a", "b")
facades.Log().WithContext(ctx).Info("Hello Goravel")

// Output: 
[2024-12-15 16:36:58] local.info: Hello Goravel 
Context: map[a:b]

支持直接设置 DSN 连接数据库

goravel/framework: v1.15.0

查看文档

Orm 的 Create 方法支持使用 map 创建

goravel/framework: v1.15.0

查看文档

Orm 新增配置项

goravel/framework: v1.15.0

配置项是针对特定情况的，正常使用时不必须，没有被默认添加到配置文件中。

// config/database.go
"{driver_name}": map[string]any{
  "driver":   "{driver_name}",
  "host":     config.Env("DB_HOST", "127.0.0.1"),
  ...
++ "schema": "goravel",// Set the default schema for the connection, only for postgres and sqlserver
++ "no_lower_case": false,// Set whether to convert the table name to lowercase
++ "name_replacer": strings.NewReplacer("id", "ID"),// Set the columns name replacement
},

Orm 新增 Restore 方法

goravel/framework: v1.15.0

新增 Restore 方法，可以用于恢复软删除的数据，并添加 Restored, Restoring 事件。

查看文档

Orm 日志集成 Log 模块

goravel/framework: v1.15.0

之前 Orm 的日志输出是直接输出到控制台，现在 Orm 的日志输出将集成到 Log 模块，可以同时打印到控制台和日志文件。

Postgres 和 Sqlserver 驱动支持 Schema

goravel/framework: v1.15.0

查看文档

新增 about 命令

goravel/framework: v1.15.0

新增 about 命令，可以查看框架的版本、配置等信息。

go run . artisan about

新增 db:show 命令

goravel/framework: v1.15.0

新增 db:show 命令，可以查看数据库中的所有表。

go run . artisan db:show

新增 db:table 命令

goravel/framework: v1.15.0

新增 db:table 命令，可以查看指定表的结构。

go run . artisan db:table
go run . artisan db:table users

优化 Artisan 输出样式

goravel/framework: v1.15.0

优化 Artisan 输出样式，增加颜色，使输出更加美观。

Auth 新增 ID 方法

goravel/framework: v1.15.0

id, err := facades.Auth(ctx).ID()

多个 Auth.Guard 可以设置自己的 TTL

goravel/framework: v1.15.0

之前多个 Guard 公用 jwt.ttl 配置，现在你可以通过在 config/auth.go 文件中为每个 Guard 单独设置 TTL，如果不设置，则默认使用 jwt.ttl 配置。

// config/auth.go
"guards": map[string]any{
  "user": map[string]any{
    "driver": "jwt",
++  "ttl": 60,
  },
},

Postgresql 驱动名称更改为 Postgres

goravel/framework: v1.15.0

Postgresql 驱动的名称已更改为 postgres，如果您正在使用 Postgresql 驱动程序，则需要修改配置文件：

// config/database.go
"postgres": map[string]any{
  -- "driver":   "postgresql",
  ++ "driver":   "postgres",
  "host":     config.Env("DB_HOST", "127.0.0.1"),
}

修改 Orm.Transaction 方法回调参数类型

goravel/framework: v1.15.0

facades.Orm().Transaction() 方法的回调参数类型由 func(tx orm.Transaction) error 改为 func(tx orm.Query) error，如果你正在使用该方法，请相应修改。

-- facades.Orm().Transaction(func(tx orm.Transaction) error {
++ facades.Orm().Transaction(func(tx orm.Query) error {
  var user models.User

  return tx.Find(&user, user.ID)
})

优化 Orm 的 Delete 与 ForceDelete 方法

goravel/framework: v1.15.0

如果你正在向 Delete 或 ForceDelete 方法传入 ID 删除数据，请改为使用 Where 方法：

-- facades.Orm().Query().Delete(&models.User{}, 10)
++ facades.Orm().Query().Where("id", 10).Delete(&models.User{})

-- facades.Orm().Query().Delete(&models.User{}, []uint{1, 2, 3})
++ facades.Orm().Query().WhereIn("id", []uint{1, 2, 3}).Delete(&models.User{})

-- facades.Orm().Query().ForceDelete(&models.User{}, 10)
++ facades.Orm().Query().ForceDelete("id", 10).Delete(&models.User{})

Delete 和 ForceDelete 方法支持不传入参数删除数据：

res, err := facades.Orm().Query().Model(&models.User{}).Where("id", 1).Delete()
res, err := facades.Orm().Query().Table("users").Where("id", 1).Delete()

优化 Cache 的 Decrement 与 Increment 方法

goravel/framework: v1.15.0

Decrement 和 Increment 方法的入参与出参类型由 int 修改为 int64：

-- Decrement(key string, value ...int) (int, error)
++ Decrement(key string, value ...int64) (int64, error)

-- Increment(key string, value ...int) (int, error)
++ Increment(key string, value ...int64) (int64, error)

优化 Artisan 的 Call 方法

goravel/framework: v1.15.0

之前 facades.Artisan().Call() 方法执行时遇到错误将会直接 panic，现在将返回错误，如果你正在使用该方法，请处理该错误返回。

err := facades.Artisan().Call("command:name")

Testing.Database 的 Clear 方法重命名为 Shutdown

goravel/framework: v1.15.0

为了保持方法名称与其他模块一致，我们将 Clear 方法重命名为 Shutdown。

database, err := facades.Testing().Docker().Database()
-- err := database.Clear()
++ err := database.Shutdown()

优化 Testing.Database 的 Build 方法

goravel/framework: v1.15.0

之前在调用 Build 方法时，会自动进行数据库迁移，升级后，需要手动调用 Migrate 方法进行迁移，数据库控制更加灵活。

database, err := facades.Testing().Docker().Database()
err := database.Build()
++ err := database.Migrate()

优化 Request.Input* 方法

goravel/framework: v1.15.0

goravel/gin: v1.3.0

goravel/fiber: v1.3.0

之前 Request.Input* 方法仅能获取 Body 中的数据，现在将依次查找 Body、 Query、Param。并且之前向 Request.Input* 方法传递第二个参数(默认值)时，如果 key 存在，但置为空，将返回默认值，现在将返回空字符串，因为空字符串也是一种有效值，只有当 key 不存在时，才返回默认值。

你需要检查所有使用 Request.Input* 方法的地方，确保传递的参数正确与返回值符合预期。

优化 validation.PrepareForValidation 方法

goravel/framework: v1.15.0

修改入参的类型，增加 http.Context 参数：

import github.com/goravel/framework/validation

-- validator, err := facades.Validation().Make(input, rules, validation.PrepareForValidation(func(data validationcontract.Data) error {
++ validator, err := facades.Validation().Make(input, rules, validation.PrepareForValidation(func(ctx http.Context, data validationcontract.Data) error {
  if name, exist := data.Get("name"); exist {
  return data.Set("name", name)
  }

  return nil
}))

优化 Queue 模块的 Worker 方法

goravel/framework: v1.15.0

当 Worker 方法不需要设置参数时，可以保持为空：

-- facades.Queue().Worker(nil).Run()
++ facades.Queue().Worker().Run()

当需要设置参数时，参数由指针改为实例：

-- facades.Queue().Worker(&queue.Args{Connection: "redis").Run()
++ facades.Queue().Worker(queue.Args{Connection: "redis").Run()