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