全面掌握 Go 語言 Errors 標準庫：使用指南與源碼深度解析
前言
在 Go 語言中，錯誤處理是一個重要的部分。Go 官方提供了一個輕量級的 errors 標準庫，用于創(chuàng)建和處理錯誤。本文將介紹如何使用 Go 的 errors 標準庫，并深入解析其源碼實現(xiàn)。
準備好了嗎？準備一杯你最喜歡的咖啡或茶，隨著本文一探究竟吧。
Go 版本：1.22.0
error 接口
下面的內(nèi)容會提到 error 接口，因此我們有必要先了解一下 error 接口的相關(guān)定義。
在 Go 語言中，error 是一個內(nèi)置接口，它定義了一個 Error 方法。
type error interface {
Error() string
}任何實現(xiàn)了 error 接口的類型，都可以當做 錯誤類型 來使用。
errors 標準庫的基本使用
錯誤創(chuàng)建：New 函數(shù)
errors.New 函數(shù)用于創(chuàng)建并返回一個新的 error 類型的對象。
errors.New 函數(shù)的簽名如下：
func New(text string) error其中：
- 參數(shù)：text 是一個字符串，表示錯誤的描述。
- 返回值：返回一個 error 類型的對象，該對象包含了傳入的文本信息。
下面是 New 函數(shù)的代碼使用示例：
// https://github.com/chenmingyong0423/blog/blob/master/tutorial-code/go/errors/new/main.go
package main
import (
"errors"
"fmt"
)
func main() {
err := errors.New("這是一個錯誤")
fmt.Println(err.Error()) // 這是一個錯誤
}錯誤匹配：Is 函數(shù)
errors.Is 函數(shù)用于判斷兩個 error 是否相等，通常用于檢查一個錯誤鏈中是否包含某個特定的錯誤。當一個錯誤被包裝多層時，該函數(shù)將會遞歸檢查錯誤鏈的每一層，確定是否存在與目標錯誤相等的錯誤。
errors.Is 函數(shù)的簽名如下：
func Is(err, target error) bool- 參數(shù)：
err 為要檢查的錯誤。
target 為目標錯誤。errors.Is 函數(shù)會檢查 err 是否等于 target，或 err 鏈中是否存在一個錯誤等于 target。
- 返回值： 返回一個 bool 類型的值。如果兩個 error 相等，返回 true，否則返回 false。
下面是 Is 函數(shù)的代碼使用示例：
// https://github.com/chenmingyong0423/blog/blob/master/tutorial-code/go/errors/is/main.go
package main
import (
"errors"
"fmt"
)
var (
ErrUserNotFound = errors.New("user not found")
)
func main() {
err := fmt.Errorf("%w: name=%s", ErrUserNotFound, "陳明勇")
if errors.Is(err, ErrUserNotFound) {
fmt.Println("error is ErrUserNotFound")
} else {
fmt.Println(err)
}
}在上述代碼示例中，首先定義了一個錯誤變量 ErrUserNotFound ，用于表示 用戶未找到 的錯誤情況。接著在 main 函數(shù)中，利用 fmt.Errorf 函數(shù)包裝了原始的 ErrUserNotFound 錯誤并添加了上下文信息 name=陳明勇。然后使用 errors.Is 判斷 err 是否等于或包含 ErrUserNotFound。由于在創(chuàng)建 err 時已經(jīng)包含了 ErrUserNotFound 錯誤，因此 errors.Is 函數(shù)會返回 true，程序會輸出 error is ErrUserNotFound。
錯誤斷言：As 函數(shù)
errors.As 函數(shù)用于檢查一個錯誤是否可以被斷言為特定的錯誤類型，斷言成功則將錯誤的值賦給特定的錯誤變量。
errors.As 函數(shù)的簽名如下：
func As(err error, target any) bool- 參數(shù)：
err 為被斷言的錯誤。
target 為目標錯誤，它必須是一個非空指針。
- 返回值：返回一個 bool 類型的值。如果斷言成功，返回 true，否則返回 false。
下面是 As 函數(shù)的代碼使用示例：
// https://github.com/chenmingyong0423/blog/blob/master/tutorial-code/go/errors/as/main.go
package main
import (
"errors"
"fmt"
)
type UserNotError struct {
Name string
}
func (e *UserNotError) Error() string {
return fmt.Sprintf("user not found: name=%s", e.Name)
}
func main() {
var err = &UserNotError{Name: "陳明勇"}
var errUserNotFound = &UserNotError{}
if errors.As(err, &errUserNotFound) {
fmt.Println(errUserNotFound.Name) // 陳明勇
} else {
fmt.Println(err)
}
}在上述代碼示例中，首先自定義一個錯誤類型 UserNotError，實現(xiàn)了 error 接口。接著在 main 函數(shù)里，定義一個類型為 UserNotError 的錯誤實例 err，然后嘗試使用 errors.As 函數(shù)將其類型斷言為 UserNotError 類型，如果斷言成功，則打印 errUserNotFound 的 Name 字段（即 陳明勇）；否則打印 err。
包裝錯誤：Join 函數(shù)
errors.Join 是 Go 1.20 版本新增的一個函數(shù)，該函數(shù)用于包裝（合并）給定的 errs（錯誤集） 并返回一個新的錯誤對象。當 errs 為 nil 時，errors.Join 函數(shù)返回 nil。需要注意的是 errors.Join 在包裝 error 的過程中，會忽略 nil error。
errors.Join 函數(shù)的簽名如下：
func Join(errs ...error) error其中：
- 參數(shù)：errs 為所給定的錯誤集。
- 返回值：返回一個 error 接口類型的對象，其值為包裝后的新 error。
下面是 Join 函數(shù)的代碼使用示例：
// https://github.com/chenmingyong0423/blog/blob/master/tutorial-code/go/errors/join/main.go
package main
import (
"errors"
"fmt"
)
func main() {
err1 := errors.New("error 1")
err2 := errors.New("error 2")
err := errors.Join(err1, err2)
fmt.Println(err)
fmt.Println(errors.Is(err, err1)) // true
fmt.Println(errors.Is(err, err2)) // true
}程序的運行結(jié)果為：
error 1
error 2
true
true在上述代碼示例中，首先定義了兩個不同的 error 錯誤對象：err1 和 err2。接著通過 errors.Join 函數(shù)包裝（合并）err1 和 err2 錯誤，得到一個新的錯誤對象 err。然后輸出錯誤信息，只要 errors.Join 函數(shù)正確包裝了 err1 和 err2，這兩個錯誤的信息將會被輸出。最后通過 errors.Is 函數(shù)檢查錯誤的包含關(guān)系，程序運行結(jié)果與預(yù)期結(jié)果一樣，輸出的結(jié)果都是 true。
獲取原始錯誤：Unwrap 函數(shù)
errors.Unwrap 函數(shù)用于獲取一個包裝過的 error 值的原始 error，它接收一個 err error 參數(shù)。
errors.Unwrap 函數(shù)的簽名如下：
func Unwrap(err error) error其中：
- 參數(shù)：err 為所給定的錯誤。
- 返回值：返回一個 error 類型的對象。其值為解包后的 error。
下面是 Unwrap 函數(shù)的代碼使用示例：
// https://github.com/chenmingyong0423/blog/blob/master/tutorial-code/go/errors/unwrap/main.go
package main
import (
"errors"
"fmt"
)
var (
ErrUserNotFound = errors.New("user not found")
)
func main() {
err := fmt.Errorf("%w: name=%s", ErrUserNotFound, "陳明勇")
fmt.Println(err)
fmt.Println(errors.Unwrap(err))
}程序的運行結(jié)果為：
user not found: name=陳明勇
user not founderrors 標準庫源碼解析
errorString 結(jié)構(gòu)體
type errorString struct {
s string
}
func (e *errorString) Error() string {
return e.s
}errorString 結(jié)構(gòu)體是一個簡單的 error 實現(xiàn)，它只有一個類型為 string 的 s 字段，用于存儲錯誤信息。當調(diào)用 Error() 方法時，該方法將會返回 s 字段的值。
New 函數(shù)
New 函數(shù)用于生成一個新的錯誤對象，其返回值為 errorString 類型的實例。
func New(text string) error {
return &errorString{text}
}Is 函數(shù)
errors.Is 函數(shù)用于判斷兩個 error 是否相等。
func Is(err, target error) bool {
if target == nil {
return err == target
}
// 獲取 target 是否可比較的 bool 值，true 表示可比較，false 表示不可比較
isComparable := reflectlite.TypeOf(target).Comparable()
// 詳細比較
return is(err, target, isComparable)
}源碼剖析：
- nil 值檢查：判斷 target 的值是否為 nil，如果為 nil 則直接比較 err 是否等于 target（也就是是否等于 nil），比較結(jié)果作為 Is 函數(shù)的結(jié)果返回。
- 獲取可比較類型的結(jié)果：使用 reflectlite.TypeOf(target).Comparable() 檢查 target 的類型是否可以比較，如果得到的結(jié)果是 true，表示可比較，否則表示不可比較
- 詳細比較：將 err、target 以及 isComparable 變量作為參數(shù)調(diào)用 is 函數(shù)進行詳細比較。
func is(err, target error, targetComparable bool) bool {
for {
// 如果 target 是一個可比較的類型，直接使用 == 符號進行比較。
if targetComparable && err == target {
return true
}
// 如果 err 實現(xiàn)了 Is 方法，則調(diào)用 Is 方法，如果該方法返回 true，則直接返回 true
if x, ok := err.(interface{ Is(error) bool }); ok && x.Is(target) {
return true
}
// 接口實現(xiàn)檢查
switch x := err.(type) {
// 如果 err 實現(xiàn)了 Unwrap() error 方法
case interface{ Unwrap() error }:
// 調(diào)用 Unwrap 方法獲取新的錯誤
err = x.Unwrap()
// 如果新錯誤為 nil，返回 false
if err == nil {
return false
}
// 如果 err 實現(xiàn)了 Unwrap() []error 方法
case interface{ Unwrap() []error }:
// 遍歷錯誤集
for _, err := range x.Unwrap() {
// 遞歸檢查新錯誤和 target 是否相等
if is(err, target, targetComparable) {
return true
}
}
// 不相等
return false
default:
// 不相等
return false
}
}
}源碼剖析：
- 循環(huán)處理 err：循環(huán)是為了處理錯誤鏈，可能有多個嵌套的錯誤。
- 直接比較錯誤：如果 targetComparable && err == target 成立，則返回 true。
- 檢查是否實現(xiàn)了 Is 方法：通過 err.(interface{ Is(error) bool }) 檢查 err 對象是否實現(xiàn)了 Is(error) bool 方法，如果是，調(diào)用該方法，如果返回 true，則 is 函數(shù)返回 true。
- 接口實現(xiàn)檢查：通過 type swtich 的方式（switch x := err.(type)）檢查 err 對象是否實現(xiàn)了 interface{ Unwrap() error } 或 interface{ Unwrap() []error } 接口：
如果 err 實現(xiàn)了 interface{ Unwrap() error } 接口，則調(diào)用 Unwrap 獲取下一個錯誤，如果新錯誤為 nil，返回 false，否則繼續(xù)循環(huán)比較新錯誤和 target 是否匹配。
如果 err 實現(xiàn)了 interface{ Unwrap() []error } 接口，調(diào)用 x.Unwrap() 方法獲取到新的錯誤集，對集合里的每個錯誤遞歸調(diào)用 is 函數(shù)。如果任意一個錯誤匹配 target，則返回 true。
- 如果 err 既不實現(xiàn) Is 方法，也不實現(xiàn) Unwrap 方法，則返回 false。
總的來說，Is 函數(shù)在檢查 err 是否等于或包含 target 時采用了兩種方法：直接使用 == 符號比較 和 通過調(diào)用 err 對象實現(xiàn)的 Is 方法進行比較。此外，Is 函數(shù)還考慮了錯誤的包裝情況，通過解包 err 來獲取新的錯誤，進而進行新的比較。
As 函數(shù)
errors.As 函數(shù)用于檢查一個錯誤是否可以被斷言為特定的錯誤類型，斷言成功則將錯誤的值賦給特定的錯誤變量。
func As(err error, target any) bool {
// 如果 err 為 nil，直接返回 false
if err == nil {
return false
}
// 如果 target 為 nil，觸發(fā) panic
if target == nil {
panic("errors: target cannot be nil")
}
// 通過反射獲取到 target 的值對象
val := reflectlite.ValueOf(target)
// 獲取 target 的類型
typ := val.Type()
// 如果 target 的類型不是指針或是空指針，觸發(fā) panic
if typ.Kind() != reflectlite.Ptr || val.IsNil() {
panic("errors: target must be a non-nil pointer")
}
// 獲取 target 的類型值
targetType := typ.Elem()
// 如果 target 的類型不是接口類型或者沒有實現(xiàn) error 接口，觸發(fā) panic
if targetType.Kind() != reflectlite.Interface && !targetType.Implements(errorType) {
panic("errors: *target must be interface or implement error")
}
// 詳細比較
return as(err, target, val, targetType)
}源碼剖析：
- nil 值檢查：如果 err 的值為 nil，直接返回 false；如果 target 的值為 nil，則觸發(fā) panic。
- 指針類型檢查：使用 reflectlite.ValueOf(target) 獲取 target 的反射值 val 和類型 typ。檢查 target 是否是一個非空指針。如果 target 的類型不是指針類型或是空指針，觸發(fā) panic。
- 接口檢查：通過 targetType := typ.Elem() 獲取指針指向元素的類型，判斷如果該類型不是接口類型或者沒有實現(xiàn) error 接口，則觸發(fā) panic。
- 詳細比較：將 err、target 和 val 以及 targetType 變量作為參數(shù)調(diào)用 as 函數(shù)進行詳細比較。
func as(err error, target any, targetVal reflectlite.Value, targetType reflectlite.Type) bool {
for {
// 如果 err 的值可以被賦值給 target 指向的變量
if reflectlite.TypeOf(err).AssignableTo(targetType) {
// 將 err 的值賦值給 target 指向的變量
targetVal.Elem().Set(reflectlite.ValueOf(err))
return true
}
// 如果 err 實現(xiàn) As 方法，則調(diào)用這個方法，如果該方法返回 true，則 as 函數(shù)返回 true
if x, ok := err.(interface{ As(any) bool }); ok && x.As(target) {
return true
}
switch x := err.(type) {
// 如果 err 實現(xiàn)了 Unwrap() error 方法
case interface{ Unwrap() error }:
// 調(diào)用 Unwrap 方法獲取新的錯誤
err = x.Unwrap()
// 如果新錯誤為 nil，返回 false
if err == nil {
return false
}
// 如果 err 實現(xiàn)了 Unwrap() []error 方法
case interface{ Unwrap() []error }:
// 遍歷錯誤集
for _, err := range x.Unwrap() {
if err == nil {
continue
}
// 遞歸檢查新錯誤是否可以被斷言為 target
if as(err, target, targetVal, targetType) {
return true
}
}
// 斷言失敗
return false
default:
// 斷言失敗
return false
}
}
}源碼剖析：
- 循環(huán)處理 err：循環(huán)是為了處理錯誤鏈，可能有多個嵌套的錯誤。
- 直接分配檢查：使用 reflectlite.TypeOf(err).AssignableTo(targetType) 判斷 err 的值是否可以分配給 targetType 類型，如果可以，將 err 的值賦值給 target 指向的變量，然后返回 true。
- 檢查是否實現(xiàn)了 As 方法：使用 err.(interface{ As(any) bool }) 檢查 err 是否實現(xiàn)了 As 方法，如果實現(xiàn)，調(diào)用該方法，如果該方法返回 true，則 as 函數(shù)返回 true。
- 接口實現(xiàn)檢查：通過 type swtich 的方式（switch x := err.(type)）檢查 err 對象是否實現(xiàn)了 interface{ Unwrap() error } 或 interface{ Unwrap() []error } 接口：
如果 err 實現(xiàn)了 interface{ Unwrap() error }，則調(diào)用 Unwrap 獲取下一個錯誤，如果新錯誤為 nil, 返回 false，否則并繼續(xù)循環(huán)處理這個新的錯誤。
如果 err 實現(xiàn)了 interface{ Unwrap() []error } 接口，調(diào)用 x.Unwrap() 方法獲取到新的錯誤集，對集合里的每個錯誤遞歸調(diào)用 as 函數(shù)。如果任意一個錯誤可以被斷言為 target，則返回 true。
- 如果 err 既不實現(xiàn) As 方法，也不實現(xiàn) Unwrap 方法，則返回 false。
總的來說，As 函數(shù)在判斷 err 是否可以被斷言為目標類型 target 時，采用了兩種方法：利用反射來檢查類型的可賦值性 和 通過調(diào)用 err 對象實現(xiàn)的 As 方法進行類型斷言。此外，As 函數(shù)也特別處理了 err 和 target 為 nil 的情況，并做出相應(yīng)處理。在處理封裝的錯誤時，As 函數(shù)通過解包 err，提取內(nèi)部錯誤，以進行新的斷言操作。
joinError 結(jié)構(gòu)體
type joinError struct {
errs []error
}
func (e *joinError) Error() string {
// 如果錯誤集只有一個錯誤，直接返回該錯誤的信息
if len(e.errs) == 1 {
return e.errs[0].Error()
}
// 組合所有的錯誤信息，用換行符 \n 分隔。
b := []byte(e.errs[0].Error())
for _, err := range e.errs[1:] {
b = append(b, '\n')
b = append(b, err.Error()...)
}
return unsafe.String(&b[0], len(b))
}
func (e *joinError) Unwrap() []error {
return e.errs
}joinError 結(jié)構(gòu)體用于包裝（合并）多個 error 實例。它包含一個類型為 []error 的 errs 字段，用于存儲多個 error。
- joinError 實現(xiàn)了 error 接口的 Error 方法，用于返回所有錯誤的組合字符串。
如果 errs 切片中只有一個錯誤，直接返回該錯誤的字符串表示。
如果 errs 切片中有多個錯誤，則將它們的字符串表示連接在一起，用換行符 \n 分隔。
- joinError 實現(xiàn)了 Unwrap 方法，用于解包所有合并的錯誤。
Join 函數(shù)
errors.Join 函數(shù)用于包裝（合并）給定的 errs（錯誤集） 并返回一個新的錯誤對象。
func Join(errs ...error) error {
// 定義錯誤數(shù)量的變量
n := 0
// 統(tǒng)計錯誤的數(shù)量
for _, err := range errs {
// 如果錯誤不為 nil，數(shù)量 + 1
if err != nil {
n++
}
}
// 如果錯誤的數(shù)量為 0，返回 nil
if n == 0 {
return nil
}
// 定義 *joinError 變量
e := &joinError{
errs: make([]error, 0, n),
}
// 存儲所有 error 對象
for _, err := range errs {
if err != nil {
e.errs = append(e.errs, err)
}
}
return e
}源碼剖析：
- 統(tǒng)計有效的錯誤對象數(shù)量：遍歷 errs，統(tǒng)計有效的 error 對象數(shù)量。當 error 對象不為 nil 時數(shù)量加 1。統(tǒng)計完成之后，如果有效的 error 對象數(shù)量為 0，則返回 nil。
- 定義 joinError 結(jié)構(gòu)體變量：定義類型為 joinError結(jié)構(gòu)體的變量e，用于存儲所有的 error` 對象。
- 存儲 error 變量：遍歷 errs，存儲值不為 nil 的 error 對象。
- 返回 joinError 結(jié)構(gòu)體變量 e。
總的來說，Join 函數(shù)通過使用 *joinError 的結(jié)構(gòu)體對象封裝了多個錯誤對象，實現(xiàn)了錯誤的包裝（合并）。 在此過程中，Join 函數(shù)排除那些值為 nil 的 error 對象，從而只處理有效的錯誤。
Unwrap 函數(shù)
errors.Unwrap 函數(shù)用于獲取一個包裝過的 error 值的原始 error。
func Unwrap(err error) error {
// 判斷 err 是否實現(xiàn)了 Unwrap 方法
u, ok := err.(interface {
Unwrap() error
})
// 如果沒有實現(xiàn)，返回 nil
if !ok {
return nil
}
// 調(diào)用 Unwrap 方法，將調(diào)用結(jié)果作為返回值返回
return u.Unwrap()
}源碼剖析：
- 檢查是否實現(xiàn)了 Unwrap() error 方法：如果 err 實現(xiàn)了 Unwrap() error，則調(diào)用 Unwrap() 方法獲取到解包的新錯誤，然后返回該錯誤，否則返回 nil。
- 特別注意的是該函數(shù)不能解包通過 Join 函數(shù)合并的錯誤，因為該函數(shù)返回的 error 對象底層的實現(xiàn)是joinError 結(jié)構(gòu)體，該結(jié)構(gòu)體實現(xiàn)的是 Unwrap() []error 方法，而不是 Unwrap() error。
總的來說，Unwrap 函數(shù)通過檢查接收的 err 對象是否實現(xiàn) Unwrap() error 方法來做出相應(yīng)處理。如果實現(xiàn)該方法，返回調(diào)用該方法的結(jié)果，否則，返回 nil。
小結(jié)
本文深入探討了 Go 語言的 errors 標準庫，具體涵蓋了該庫的 基本使用 和 源碼解析。
首先從該庫的基本使用講起，介紹了如何創(chuàng)建錯誤、匹配錯誤、斷言錯誤和包裝錯誤以及獲取原始錯誤。接著，對 errors 標準庫的源碼進行解析，理解各結(jié)構(gòu)體的定義和各函數(shù)的內(nèi)部工作原理。
總而言之，理解和掌握 errors 庫的基本使用和源碼實現(xiàn)，能幫助我們更加熟練地處理錯誤，提高代碼的健壯性和可維護性。
