跳轉到內容

從 v1.14 升級到 v1.15

令人興奮的新功能 🎉

功能增強 🚀

破壞性變化 🛠

v1.15.3

v1.15.4

同時升級:goravel/gin: v1.3.3, goravel/fiber: v1.3.3

v1.15.5

同時升級:goravel/redis: v1.3.1, goravel/fiber: v1.3.4

v1.15.6

v1.15.7

v1.15.8

同時升級:goravel/fiber: v1.3.6

v1.15.9

v1.15.10

v1.15.11

升級指南

預估升級時間:10 分鐘

隨著 Golang v1.21 不再被維護,Goravel v1.15 默認支持 Golang 版本由 1.21 升級為 1.22。 請在 go.mod 文件中更新版本。

1. 更新依賴

go get github.com/goravel/framework@v1.15.9

// 如果使用 gin
go get github.com/goravel/gin@v1.3.3

// 如果使用 fiber
go get github.com/goravel/fiber@v1.3.6

// 如果使用 redis
go get github.com/goravel/redis@v1.3.1

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

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

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

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

// 如果使用 Cloudinary
go get 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 中的配置:

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

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

需相應修改:優化 Request.Input* 方法

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

需相應修改:優化 validation.PrepareForValidation 方法

13. 如果正在使用 Mail 模組

修改 Subject 的設置方式:

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

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

如果使用了 From 方法:

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

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

如果使用了 Queue 方法:

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

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

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

需相應修改:優化 validation.PrepareForValidation 方法

功能介紹

Migration 支持使用 Go 語言遷移

之前框架僅支持 SQL 遷移。 當你想切換數據庫時,不同數據庫之間的 SQL 語法差異使得遷移過程極其困難。 此外,遷移文件中也無法執行代碼,在進行數據修復時,無法進行邏輯判斷。

現在,框架支持使用 Go 語言直接生成遷移文件,使開發者能輕鬆編寫複雜的遷移邏輯。 然而,在當前版本中,尚未實現對表字段的修改,只支持創建表、刪除表和創建索引等操作。 如果想要進行修改,需要使用 Sql 方法直接執行 SQL 語句。 未來版本將支持修改表字段的功能。

在 v1.15 版本中,框架同時支持 Go 語言遷移(默認)和 SQL 遷移,但 SQL 遷移將在 v1.16 版本中移除。

由 SQL 遷移切換到 Go 語言遷移

如果你正在使用 SQL 遷移,可以通過以下步驟切換到 Go 語言遷移:

  1. 修改 config/database.go 中的配置;
go
-- "migrations": "migrations",
++ "migrations": map[string]any{
++		"driver": "default",
++		"table":  "migrations",
++ },
  1. 使用 go run . artisan make:migration {NAME} 命令創建遷移文件;

在生成的文件的 Up, Down 方法中,分別執行原 SQL 遷移文件中的遷移、回滾語句,注意使用 facades.Schema().HasTable 方法判斷表是否存在:

go
func (r *M20241207095921CreateUsersTable) Up() error {
  if !facades.Schema().HasTable("users") {
    return facades.Schema().Sql({SQL})
  }

  return nil
}
  1. 將遷移文件註冊到 database/kernel.go 文件中;

新建 database/kernel.go 文件,並註冊遷移文件與 Seeder:

go
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{},
  }
}
  1. 修改 app/providers/database_service_provider.go 文件以完成註冊,並將原本在此註冊的 Seeder 移動到 database/kernel.go::Seeders
go
-- 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())
++ }
  1. 備份現有 migrations 表數據,然後刪除 migrations 表;

  2. 執行 go run . artisan migrate 命令進行遷移,遷移完成後,將生成新的 migrations 表。

查看文檔

測試支援 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 支援設置自定義回復方法

goravel/framework: v1.15.0

查看文檔

Request 支援設置過濾器

goravel/framework: v1.15.0

查看文檔

Request 新增 BindQuery 方法

goravel/framework: v1.15.0

支援使用 ctx.Request().BindQuery() 直接綁定來自鏈接的參數。

查看文檔

驗證支援 Regex 規則

goravel/framework: v1.15.0

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

排程支援控制日誌輸出

goravel/framework: v1.15.0

app.debugfalse 時,僅輸出 error 級別日誌。

排程新增 Shutdown 方法

goravel/framework: v1.15.0

Shutdown 方法可用於優雅地停止排程。

查看文檔

郵件支援 Mailable 模板

goravel/framework: v1.15.0

查看文檔

錯誤日誌輸出中的追蹤支援跳轉

goravel/framework: v1.15.0

在錯誤日誌輸出中,點擊追蹤將跳轉到錯誤發生的代碼行。

日誌支援在上下文中打印鍵值對

goravel/framework: v1.15.0

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

// 輸出:
[2024-12-15 16:36:58] local.info: Hello Goravel
上下文: map[a:b]

支援直接設置 DSN 來連接數據庫

goravel/framework: v1.15.0

查看文檔

Orm 的 Create 方法支援使用 map 創建

goravel/framework: v1.15.0

查看文檔

Orm 新增配置項

goravel/framework: v1.15.0

配置項是針對特定情況的,正常使用時不必,未被默認添加到配置文件中。

go
// config/database.go
"{driver_name}": map[string]any{
  "driver":   "{driver_name}",
  "host":     config.Env("DB_HOST", "127.0.0.1"),
  ...
++ "schema": "goravel",// 設置連接的默認架構,只適用於 Postgres 和 Sqlserver
++ "no_lower_case": false,// 設置是否將表名轉換為小寫
++ "name_replacer": strings.NewReplacer("id", "ID"),// 設置欄位名稱替換
},

Orm 新增 Restore 方法

goravel/framework: v1.15.0

新增 Restore 方法,可用於恢復軟刪除的數據,並添加 Restored, Restoring 事件。

查看文檔

Orm 的日誌集成日誌模塊

goravel/framework: v1.15.0

之前 Orm 的日誌輸出是直接輸出到控制台,現在 Orm 的日誌輸出將集成到日誌模塊,並可以同時打印到控制台和日誌文件。

Postgres 和 Sqlserver 驅動支援 Schema

goravel/framework: v1.15.0

查看文檔

新增 about 命令

goravel/framework: v1.15.0

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

bash
go run . artisan about

新增 db:show 命令

goravel/framework: v1.15.0

新增 db:show 命令,可以查看資料庫連接信息。

bash
go run . artisan db:show

新增 db:table 命令

goravel/framework: v1.15.0

新增 db:table 命令,可以查看指定表的結構。

bash
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

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

多個 Auth.Guard 可以設置自己的 TTL

goravel/framework: v1.15.0

之前,多個 Guards 共享 jwt.ttl 配置。 現在你可以通過在 config/auth.go 文件中為每個 Guard 單獨設置 TTL。 如果不設置,則默認使用 jwt.ttl 配置。 如果不設置,則默認使用 jwt.ttl 配置。

go
// 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 驅動程序,則需要修改配置文件: 如果你正在使用 Postgresql 驅動,則需要修改配置文件:

go
// 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,如果你正在使用該方法,請相應修改。

go
-- 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

如果你正在向 DeleteForceDelete 方法傳入 ID 刪除數據,請改為使用 Where 方法:

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

DeleteForceDelete 方法支持不傳入參數刪除數據:

go
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

DecrementIncrement 方法的入參和出參類型由 int 修改為 int64

go
-- 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。如果你正在使用該方法,請處理該錯誤返回。 現在會返回錯誤,如果你正在使用該方法,請處理錯誤。

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

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

goravel/framework: v1.15.0

為了保持方法名稱與其他模組一致,我們將 Clear 方法重命名為 Shutdown

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

優化 Testing.Database 的 Build 方法

goravel/framework: v1.15.0

之前,調用 Build 方法時,數據庫遷移將自動執行。 升級後,你需要手動調用 Migrate 方法進行遷移,使數據庫控制更靈活。

go
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 獲取數據,現在將依次查找 BodyQueryParam。 并且之前向 Request.Input* 方法傳遞第二個參數(默認值)時,如果 key 存在,但置為空,將返回默認值。 現在將返回空字符串,因為空字符串也是一種有效值,只有當 key 不存在時,才返回默認值。 之前在向 Request.Input* 方法傳遞第二個參數(默認值)時,如果 key 存在但為空,將返回默認值。 現在將返回空字符串,因為空字符串也是有效值,只有當 key 不存在時,才返回默認值。

你需要檢查所有使用 Request.Input* 方法的地方,確保傳遞的參數正確且返回值符合預期。

優化 validation.PrepareForValidation 方法

goravel/framework: v1.15.0

修改入參的類型,增加 http.Context 參數:

go
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 方法不需要設置參數時,可以保持為空:

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

當需要設置參數時,參數由指針改為實例:

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

Go 遷移支持 Boolean 字段

goravel/framework: v1.15.3

go
table.Boolean("is_admin")

Go 遷移支持自定義字段

goravel/framework: v1.15.3

如果你正在使用框架尚不支持的字段類型,可以通過 Column 方法自定義字段類型:

go
table.Column("geometry", "geometry")

優化 Artisan log 輸出規則

goravel/framework: v1.15.3

之前,Artisan log 只輸出錯誤級別的日誌,現在所有級別的日誌將被輸出。 如果你想禁用控制台打印日誌且正在使用 singledaily 日誌驅動,請將 logging.channels.single.printlogging.channels.daily.print 配置設置為 false

修復 PrepareForValidation 中 ctx 為 nil 的問題

goravel/framework: v1.15.4

goravel/gin: v1.3.3

goravel/fiber: v1.3.3

修復前,ctxPrepareForValidation 方法中始終為 nil,現在將正確傳遞 ctx 作為參數。 如果你正在使用 validation.PrepareForValidation 方法,請相應修改。

go
import (
  github.com/goravel/framework/validation
  contarctsvalidate "github.com/goravel/framework/contracts/validation"
)

-- validation.PrepareForValidation(func(ctx http.Context, data contarctsvalidate.Data) error {
++ validation.PrepareForValidation(ctx, func(ctx http.Context, data contarctsvalidate.Data) error {

修復 Fiber 驅動高併發下 Orm WithContext 方法報錯的問題

goravel/framework: v1.15.4

goravel/fiber: v1.3.3

詳見:#866

優化打包體積

goravel/framework: v1.15.4

詳見:#865

優化 model ID 多重嵌套時的問題

goravel/framework: v1.15.4

詳見:#898

添加 artisan 命令別名

goravel/framework: v1.15.4

// Before
go run  . artisan key:generate

// After
./artisan key:generate

修復使用 Redis 驅動時 Throttle 無效的問題

goravel/framework: v1.15.5

goravel/redis: v1.3.1

當使用 Redis 驅動時,Throttle 無法正常存儲,導致限制失效。

問題:#625

修復使用 Fiber 驅動時 Fallback 無法工作的問題

goravel/framework: v1.15.5

goravel/fiber: v1.3.4

當使用 Fiber 驅動時,如果設置了 Fallback,其他路由將無法正常工作。

問題:#624

修復 Orm WithContext 方法在併發執行時報錯的問題

goravel/framework: v1.15.6

當使用WithContext方法來設置Context時,報告在並行執行中出現錯誤。

升級 Carbon

goravel/framework: v1.15.7

dromara/carbon v2.5.5 或更高版本引入了新特性,導致一些框架功能異常。 注意:dromara/carbon v2.6 或更高版本尚不支援,將在 Goravel v1.16 中支援。

修復 facades.Testing().Docker().Database() 報錯的問題

goravel/framework: v1.15.8

問題:#672

修復 fiber 驅動 ctx.Request().Ip() 方法無法正常工作的問題

goravel/fiber: v1.3.6

之前,ctx.Request().Ip()方法總是返回127.0.0.1。 修復後,新增配置項 http.drivers.fiber.proxy_headerhttp.drivers.fiber.enable_trusted_proxy_checkhttp.drivers.fiber.trusted_proxies,用於設置代理頭和可信的代理 IP 地址。

問題:#678

Orm 中 WhereBetween 方法不支援字符串的問題

goravel/framework: v1.15.8

問題:#1036

修復 Orm 中 Cursor 方法在某些情況下內存泄漏的問題

goravel/framework: v1.15.9

當獲取 rows 時,chan 未獲得正確關閉,導致內存泄漏。

修復 Schedule 中使用秒級任務時 OnOneServer 異常的問題

goravel/framework: v1.15.9

問題:#690

使生成的遷移文件中默認的 Timestamp 更改為 TimestampsTz

goravel/framework: v1.15.9

問題:#699

修復 Orm Query 在重複使用時 Where 條件可能混淆的問題

goravel/framework: v1.15.10

問題:#732

Fix bcc and cc cannot be set expectly when sending mail

goravel/framework: v1.15.11

Issue: #737

Fix sending mail via queue returns incorrect error

goravel/framework: v1.15.11

PR: #1148

Fix the orm create events can be triggered when creating multiple records

goravel/framework: v1.15.11

Issue: #738

基於 MIT 许可發佈