從 v1.14 升級到 v1.15
令人興奮的新功能 🎉
功能增強 🚀
- HTTP 支持返回 Stream
- HTTP 支持設置超時
- HTTP 支持設置自定義恢復方法
- Request 支持設置 Filter
- Request 增加 BindQuery 方法
- Validation 支持 Regex 規則
- Schedule 支持控制日誌輸出
- Schedule 新增 Shutdown 方法
- Mail 支持 Mailable 模版
- Log 錯誤日誌輸出的 trace 支持點擊跳轉
- Log 支持打印 Context 中的鍵值
- 支持直接設置 DSN 連接資料庫
- Orm 的 Create 方法支持使用 map 創建
- Orm 新增配置項
- Orm 新增 Restore 方法
- Orm 日誌集成 Log 模組
- Postgres 和 Sqlserver 驅動支持 Schema
- 新增 about 命令
- 新增 db:show 命令
- 新增 db:table 命令
- 優化 Artisan 輸出樣式
- Auth 新增 ID 方法
- 多個 Auth.Guard 可以設置自己的 TTL
破壞性變化 🛠
- Postgresql 驅動名稱更改為 Postgres
- 修改 Orm.Transaction 方法回調參數類型
- 優化 Orm 的 Delete 與 ForceDelete 方法
- 優化 Cache 的 Decrement 與 Increment 方法
- 優化 Artisan 的 Call 方法
- Testing.Database 的 Clear 方法重命名為 Shutdown
- 優化 Testing.Database 的 Build 方法
- 優化 Request.Input* 方法
- 優化 validation.PrepareForValidation 方法
- 優化 Queue 模塊的 Worker 方法
v1.15.3
v1.15.4
同時升級:goravel/gin: v1.3.3, goravel/fiber: v1.3.3
- 修復 PrepareForValidation 中 ctx 為 nil 的問題
- 修復 Fiber 驅動高並發下 Orm WithContext 方法報錯的問題
- 優化打包體積
- 優化 model ID 多重嵌套時的問題
- 添加 artisan 命令別名
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
- 修復 facades.Testing().Docker().Database() 異常的問題
- 修復 fiber 驅動 ctx.Request().Ip() 獲取 IP 無效的問題
- Orm 中 WhereBetween 相關方法不支持字符串的問題
v1.15.9
- 修復 Orm 中 Cursor 方法在某些情況下內存泄露的問題
- 修復 Schedule 中使用秒級任務時 OnOneServer 異常的問題
- make:migration 命令生成的遷移文件中默認 Timestamps 改為 TimestampsTz
v1.15.10
v1.15.11
- Fix bcc and cc cannot be set expectly when sending mail
- Fix sending mail via queue returns incorrect error
- Fix the orm create events can be triggered when creating multiple records
升級指南
預估升級時間: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
中的配置:
-- "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"
-- Content(mail.Content{Subject: "Subject", Html: "<h1>Hello Goravel</h1>"})
++ Content(mail.Html("<h1>Hello Goravel</h1>")).Subject("Subject")
如果使用了 From
方法:
-- 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
方法:
-- 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 語言遷移:
- 修改
config/database.go
中的配置;
-- "migrations": "migrations",
++ "migrations": map[string]any{
++ "driver": "default",
++ "table": "migrations",
++ },
- 使用
go run . artisan make:migration {NAME}
命令創建遷移文件;
在生成的文件的 Up
, Down
方法中,分別執行原 SQL 遷移文件中的遷移、回滾語句,注意使用 facades.Schema().HasTable
方法判斷表是否存在:
func (r *M20241207095921CreateUsersTable) Up() error {
if !facades.Schema().HasTable("users") {
return facades.Schema().Sql({SQL})
}
return nil
}
- 將遷移文件註冊到
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())
++ }
備份現有
migrations
表數據,然後刪除migrations
表;執行
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
validator, err := ctx.Request().Validate(map[string]string{
"code": `required|regex:^\d{4,6}$`,
})
排程支援控制日誌輸出
goravel/framework: v1.15.0
當 app.debug
為 false
時,僅輸出 error
級別日誌。
排程新增 Shutdown 方法
goravel/framework: v1.15.0
Shutdown
方法可用於優雅地停止排程。
郵件支援 Mailable 模板
goravel/framework: v1.15.0
錯誤日誌輸出中的追蹤支援跳轉
goravel/framework: v1.15.0
在錯誤日誌輸出中,點擊追蹤將跳轉到錯誤發生的代碼行。
日誌支援在上下文中打印鍵值對
goravel/framework: v1.15.0
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
配置項是針對特定情況的,正常使用時不必,未被默認添加到配置文件中。
// 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
命令,可以查看框架的版本、配置等信息。
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
之前,多個 Guards 共享 jwt.ttl
配置。 現在你可以通過在 config/auth.go
文件中為每個 Guard 單獨設置 TTL。 如果不設置,則默認使用 jwt.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 驅動程序,則需要修改配置文件: 如果你正在使用 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*
方法傳遞第二個參數(默認值)時,如果 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()
Go 遷移支持 Boolean 字段
goravel/framework: v1.15.3
table.Boolean("is_admin")
Go 遷移支持自定義字段
goravel/framework: v1.15.3
如果你正在使用框架尚不支持的字段類型,可以通過 Column
方法自定義字段類型:
table.Column("geometry", "geometry")
優化 Artisan log 輸出規則
goravel/framework: v1.15.3
之前,Artisan log 只輸出錯誤級別的日誌,現在所有級別的日誌將被輸出。 如果你想禁用控制台打印日誌且正在使用 single
或 daily
日誌驅動,請將 logging.channels.single.print
或 logging.channels.daily.print
配置設置為 false
。
修復 PrepareForValidation 中 ctx 為 nil 的問題
goravel/framework: v1.15.4
goravel/gin: v1.3.3
goravel/fiber: v1.3.3
修復前,ctx
在 PrepareForValidation
方法中始終為 nil
,現在將正確傳遞 ctx
作為參數。 如果你正在使用 validation.PrepareForValidation
方法,請相應修改。
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_header
、http.drivers.fiber.enable_trusted_proxy_check
和 http.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