全面掌握 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

其中：

下面是 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

下面是 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: )
 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

下面是 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: , 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

其中：

下面是 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

其中：

下面是 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: )
 fmt.Println(err)
 fmt.Println(errors.Unwrap(err))
}

程序的運行結果爲：

user not found: name=陳明勇
user not found

errors 標準庫源碼解析

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

源碼剖析：

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

源碼剖析：

總的來說，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)
}

源碼剖析：

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

源碼剖析：

總的來說，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。

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
}

源碼剖析：

總的來說，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 函數通過檢查接收的 err 對象是否實現 Unwrap() error 方法來做出相應處理。如果實現該方法，返回調用該方法的結果，否則，返回 nil。

小結

本文深入探討了 Go 語言的 errors 標準庫，具體涵蓋了該庫的 基本使用 和 源碼解析。

首先從該庫的基本使用講起，介紹瞭如何創建錯誤、匹配錯誤、斷言錯誤和包裝錯誤以及獲取原始錯誤。接着，對 errors 標準庫的源碼進行解析，理解各結構體的定義和各函數的內部工作原理。

總而言之，理解和掌握 errors 庫的基本使用和源碼實現，能幫助我們更加熟練地處理錯誤，提高代碼的健壯性和可維護性。

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/Av9iOvoe6LRs5WEzeT6RYQ

猜你喜歡