Golang errors包快速上手

更新時(shí)間：2025年05月23日 10:15:01 作者：戀喵大鯉魚

errors 包是用于處理錯(cuò)誤的標(biāo)準(zhǔn)庫(kù), errors 包提供的功能比較簡(jiǎn)單,使用起來非常方便,下面就來介紹一下,感興趣的可以了解一下

1.變量

errors 包只定義了一個(gè)全局變量 ErrUnsupported。

var ErrUnsupported = New("unsupported operation")

ErrUnsupported 表示請(qǐng)求的操作不能執(zhí)行，因?yàn)樗皇苤С?。例如，調(diào)用os.Link()當(dāng)使用的文件系統(tǒng)不支持硬鏈接時(shí)。

函數(shù)和方法不應(yīng)該返回這個(gè)錯(cuò)誤，而應(yīng)該返回一個(gè)包含適當(dāng)上下文的錯(cuò)誤，滿足：

errors.Is(err, errors.ErrUnsupported)

要么直接包裝 ErrUnsupported，要么實(shí)現(xiàn)一個(gè) Is 方法。

函數(shù)和方法應(yīng)該說明何種情況下會(huì)返回包含 ErrUnsupported 的錯(cuò)誤。

2.類型

error 是一個(gè)內(nèi)建的接口類型，任何類型只要實(shí)現(xiàn)了 Error() string 方法，就實(shí)現(xiàn)了 error 接口，這意味著該類型的實(shí)例可以被當(dāng)作一個(gè) error 來處理。

// The error built-in interface type is the conventional interface for
// representing an error condition, with the nil value representing no error.
type error interface {
    Error() string
}

3.函數(shù)

3.1 New

errors.New 用于創(chuàng)建一個(gè)新的錯(cuò)誤對(duì)象。它接收一個(gè)字符串作為錯(cuò)誤消息，并返回一個(gè)錯(cuò)誤對(duì)象。

func New(text string) error

我們可以看下其具體實(shí)現(xiàn)：

// New returns an error that formats as the given text.
// Each call to New returns a distinct error value even if the text is identical.
func New(text string) error {
    return &errorString{text}
}

// errorString is a trivial implementation of error.
type errorString struct {
    s string
}

func (e *errorString) Error() string {
    return e.s
}

可以看到，New 返回的是實(shí)現(xiàn)了 error 接口的具體類型 *errorString。

3.2 Is

簡(jiǎn)介

errors.Is 函數(shù)是一個(gè)用于錯(cuò)誤處理的核心工具，用于檢查錯(cuò)誤鏈（error chain）中是否存在某個(gè)特定的錯(cuò)誤實(shí)例。

它是 Go 1.13 版本引入的錯(cuò)誤處理增強(qiáng)功能之一，與 errors.As 和 errors.Unwrap 共同提供了更靈活的錯(cuò)誤處理機(jī)制。

函數(shù)簽名

func Is(err, target error) bool

err: 要檢查的錯(cuò)誤。
target: 我們想要確認(rèn)的錯(cuò)誤。
返回值: 如果錯(cuò)誤鏈中任一錯(cuò)誤與目標(biāo)錯(cuò)誤相同，則返回 true。

核心功能

遞歸解包錯(cuò)誤鏈errors.Is 會(huì)通過 Unwrap() 或Unwrap() []error方法逐層解包錯(cuò)誤鏈，檢查每一層錯(cuò)誤是否與 target 匹配。
值相等性檢查檢查錯(cuò)誤的“值”是否與 target 相等。默認(rèn)使用 == 操作符比較，但若錯(cuò)誤類型實(shí)現(xiàn)了 Is(error) bool 方法，則優(yōu)先調(diào)用該方法進(jìn)行判斷（允許自定義相等邏輯）。
支持自定義錯(cuò)誤匹配邏輯如果自定義錯(cuò)誤類型需要定義特殊的相等規(guī)則（例如比較結(jié)構(gòu)體字段而非指針地址），可以實(shí)現(xiàn) Is(error) bool 方法。

示例代碼

package main

import (
    "errors"
    "fmt"
)

var ErrNotFound = errors.New("not found")

func main() {
    err := fmt.Errorf("context: %w", ErrNotFound)
    if errors.Is(err, ErrNotFound) {
        fmt.Println("錯(cuò)誤鏈中包含 ErrNotFound")
    }

    errNotFoundNew := errors.New("not found")
    fmt.Println(errors.Is(errNotFoundNew, ErrNotFound)) // false
}

運(yùn)行輸出：

錯(cuò)誤鏈中包含 ErrNotFound
false

因?yàn)?err 是基于 ErrNotFound 包裝出來的，所以 Is 判斷返回 true。

因?yàn)?errNotFoundNew 是一個(gè)新的 error，雖然錯(cuò)誤內(nèi)容與 ErrNotFound 相同，但是二者是兩個(gè)獨(dú)立的 error 對(duì)象，所以 Is 判斷返回 false。

使用場(chǎng)景

檢查預(yù)定義錯(cuò)誤例如判斷錯(cuò)誤是否為 io.EOF 或 os.ErrNotExist：

if errors.Is(err, io.EOF) {
    // 處理文件結(jié)束邏輯
}

自定義錯(cuò)誤匹配當(dāng)需要根據(jù)錯(cuò)誤的某些字段（而非指針地址）匹配時(shí)，自定義 Is 方法：

type ValidationError struct { Field string }
func (e *ValidationError) Is(target error) bool {
    t, ok := target.(*ValidationError)
    return ok && e.Field == t.Field
}

處理多層錯(cuò)誤鏈自動(dòng)遍歷包裹錯(cuò)誤（如 fmt.Errorf + %w 生成的錯(cuò)誤鏈）：

err := fmt.Errorf("layer2: %w", fmt.Errorf("layer1: %w", originalErr))
if errors.Is(err, originalErr) { // 直接檢查最底層錯(cuò)誤
    // 匹配成功
}

與 == 操作符的區(qū)別：

默認(rèn)行為：如果錯(cuò)誤類型未實(shí)現(xiàn) Is 方法，errors.Is 默認(rèn)使用 == 比較錯(cuò)誤值和 target。但對(duì)于指針類型的錯(cuò)誤（如 &MyError{}），== 比較的是指針地址而非值內(nèi)容。
自定義邏輯：通過實(shí)現(xiàn) Is 方法，可以控制錯(cuò)誤的匹配邏輯（如比較結(jié)構(gòu)體字段）。

注意事項(xiàng)

優(yōu)先實(shí)現(xiàn) Is 方法：如果自定義錯(cuò)誤需要支持值匹配（而非指針匹配），必須實(shí)現(xiàn) Is 方法。
target可以是nil：如果 target 為 nil，errors.Is 僅在 err 也為 nil 時(shí)返回 true。
性能錯(cuò)誤鏈較長(zhǎng)時(shí)，遞歸解包可能導(dǎo)致輕微性能開銷，但通常可忽略。

小結(jié)

errors.Is 是 Go 錯(cuò)誤處理的基石之一，它通過遞歸解包錯(cuò)誤鏈，提供了一種安全、統(tǒng)一的方式來檢查特定錯(cuò)誤的存在。結(jié)合以下實(shí)踐可最大化其效用：

對(duì)需要值匹配的自定義錯(cuò)誤實(shí)現(xiàn) Is 方法。
優(yōu)先使用 errors.Is 而非 == 直接比較錯(cuò)誤（確保兼容錯(cuò)誤鏈）。
與 errors.As 分工：Is 用于值匹配，As 用于類型提取。

3.3 As

簡(jiǎn)介

Golang 中的 errors.As 函數(shù)是一個(gè)用于錯(cuò)誤處理的重要工具，它提供了一種類型安全的方式，用于檢查錯(cuò)誤樹中是否存在某個(gè)特定類型的錯(cuò)誤，并提取該類型的錯(cuò)誤實(shí)例。

它是 Go 1.13 引入的錯(cuò)誤處理增強(qiáng)功能之一，與 errors.Is 和 errors.Unwrap 共同構(gòu)成了更靈活的錯(cuò)誤處理機(jī)制。

函數(shù)簽名

func As(err error, target any) bool

err: 要檢查的錯(cuò)誤樹。
target: 一個(gè)指向目標(biāo)類型的指針，用于存儲(chǔ)結(jié)果。
返回值: 如果錯(cuò)誤樹中存在指定的類型，則返回 true，并且 target 參數(shù)會(huì)被設(shè)置為相應(yīng)的錯(cuò)誤值。

核心功能

errors.As 會(huì)遞歸遍歷錯(cuò)誤樹（通過 Unwrap() 或 Unwrap() []error 方法解包錯(cuò)誤），檢查是否存在與 target 類型匹配的錯(cuò)誤。如果找到，它會(huì)將匹配的錯(cuò)誤值賦值給 target，并返回 true。

如果錯(cuò)誤的具體值可分配給 target 所指向的值，或者如果錯(cuò)誤有一個(gè)方法As(any) bool使得As(target)返回true，則錯(cuò)誤匹配 target。在后一種情況下，As 方法負(fù)責(zé)將錯(cuò)誤值設(shè)置到 target。

與 errors.Is 的區(qū)別：

errors.Is(err, target)：檢查錯(cuò)誤樹中是否存在值等于 target 的錯(cuò)誤（值比較）。
errors.As(err, &target)：檢查錯(cuò)誤樹中是否存在類型與 target 匹配的錯(cuò)誤（類型斷言）。

示例代碼

package main

import (
    "errors"
    "fmt"
)

// 自定義錯(cuò)誤類型
type MyError struct {
    Code    int
    Message string
}

func (e *MyError) Error() string {
    return fmt.Sprintf("code: %d, msg: %s", e.Code, e.Message)
}

func main() {
    err := &MyError{Code: 404, Message: "Not Found"}
    wrappedErr := fmt.Errorf("wrapper: %w", err) // 包裹錯(cuò)誤

    var myErr *MyError
    if errors.As(wrappedErr, &myErr) {
        fmt.Println("Found MyError:", myErr.Code, myErr.Message)
        // 輸出: Found MyError: 404 Not Found
    }
}

在這個(gè)例子中：

自定義錯(cuò)誤類型 MyError 實(shí)現(xiàn)了 error 接口。
通過 fmt.Errorf 和 %w 包裹原始錯(cuò)誤，形成錯(cuò)誤樹。
errors.As 檢查包裹后的錯(cuò)誤樹，找到 MyError 類型的錯(cuò)誤實(shí)例，并將其賦值給 myErr。

使用場(chǎng)景

提取特定錯(cuò)誤類型的詳細(xì)信息當(dāng)錯(cuò)誤類型包含額外字段（如錯(cuò)誤碼、上下文信息）時(shí)，可以通過 errors.As 提取這些信息。
處理標(biāo)準(zhǔn)庫(kù)中的錯(cuò)誤類型例如，檢查一個(gè)錯(cuò)誤是否是 os.PathError 類型，以獲取文件路徑相關(guān)的詳細(xì)信息：

var pathErr *os.PathError
if errors.As(err, &pathErr) {
    fmt.Println("Failed at path:", pathErr.Path)
}

多層級(jí)錯(cuò)誤解包無需手動(dòng)調(diào)用 Unwrap() 遍歷錯(cuò)誤鏈，errors.As 會(huì)自動(dòng)處理嵌套錯(cuò)誤。

注意事項(xiàng)

target 必須是指針target 必須是一個(gè)指向接口或具體類型的指針。例如：

var target *MyError        // 正確（具體類型指針）
var target error = &MyError{} // 正確（接口類型指針）

類型必須匹配target 的類型需要與錯(cuò)誤鏈中某個(gè)錯(cuò)誤的具體類型完全一致（或接口類型）。
性能如果錯(cuò)誤樹非常長(zhǎng)，errors.As 可能需要遍歷整個(gè)樹，但實(shí)際場(chǎng)景中性能影響通?？珊雎?。

小結(jié)

errors.As 是 Go 錯(cuò)誤處理中類型斷言的最佳實(shí)踐，它簡(jiǎn)化了從錯(cuò)誤鏈中提取特定類型錯(cuò)誤的操作。結(jié)合 errors.Is 和錯(cuò)誤包裹（fmt.Errorf + %w），可以構(gòu)建清晰、可維護(hù)的錯(cuò)誤處理邏輯。

3.4 Unwrap

簡(jiǎn)介

errors.Unwrap 是 Go 1.13 引入的錯(cuò)誤處理函數(shù)，用于獲取被包裝（wrapped）錯(cuò)誤的原始錯(cuò)誤。它是 Go 錯(cuò)誤處理機(jī)制中錯(cuò)誤鏈（error chain）支持的核心部分。

函數(shù)簽名

func Unwrap(err error) error

解包錯(cuò)誤：如果 err 實(shí)現(xiàn)了 Unwrap() error 方法，則返回該方法的結(jié)果。
無包裝時(shí)：如果錯(cuò)誤不支持解包或已經(jīng)是底層錯(cuò)誤，返回 nil。
簡(jiǎn)單直接：僅解包一層，不會(huì)遞歸解包整個(gè)錯(cuò)誤鏈。

核心功能

解包錯(cuò)誤鏈用于從包裹錯(cuò)誤（如通過 fmt.Errorf 和 %w 生成的錯(cuò)誤）中提取下一層錯(cuò)誤。
支持自定義錯(cuò)誤類型。若自定義錯(cuò)誤類型實(shí)現(xiàn)了 Unwrap() error 方法，errors.Unwrap 可自動(dòng)調(diào)用它來解包錯(cuò)誤。

使用示例

err := fmt.Errorf("wrapper: %w", io.EOF)

unwrapped := errors.Unwrap(err)
fmt.Println(unwrapped == io.EOF) // 輸出: true
fmt.Println(unwrapped)          // 輸出: EOF
errors.Unwrap 通常與 fmt.Errorf 的 %w 動(dòng)詞配合使用：
func process() error {
    if err := step1(); err != nil {
        return fmt.Errorf("step1 failed: %w", err)
    }
    // ...
}

err := process()
if errors.Unwrap(err) != nil {
    // 處理原始錯(cuò)誤
}

標(biāo)準(zhǔn)接口：要求被解包的錯(cuò)誤實(shí)現(xiàn) Unwrap() error 方法
非遞歸：只解包一層，要解包整個(gè)錯(cuò)誤鏈需要循環(huán)調(diào)用
與 errors.Is/As 配合：errors.Is 和 errors.As 內(nèi)部會(huì)自動(dòng)處理錯(cuò)誤鏈

使用場(chǎng)景

逐層檢查錯(cuò)誤鏈通過循環(huán)調(diào)用 errors.Unwrap 遍歷所有嵌套錯(cuò)誤：

currentErr := err
for currentErr != nil {
    fmt.Println(currentErr)
    currentErr = errors.Unwrap(currentErr)
}

結(jié)合 errors.Is** 和 **errors.As雖然 errors.Is 和 errors.As 會(huì)自動(dòng)遍歷錯(cuò)誤鏈，但在需要手動(dòng)提取特定層級(jí)錯(cuò)誤時(shí)，可用 Unwrap 配合使用。
自定義錯(cuò)誤類型的分層處理為自定義錯(cuò)誤實(shí)現(xiàn) Unwrap() 方法，使其能融入錯(cuò)誤鏈機(jī)制。

注意事項(xiàng)

僅解包一層每次調(diào)用 errors.Unwrap 只返回直接包裹的下層錯(cuò)誤。需循環(huán)調(diào)用以遍歷整個(gè)鏈。
依賴 Unwrap() 方法只有實(shí)現(xiàn)了 Unwrap() error 方法的錯(cuò)誤才能被正確解包。例如：

fmt.Errorf 使用 %w 包裹的錯(cuò)誤會(huì)自動(dòng)實(shí)現(xiàn)此方法。
自定義錯(cuò)誤需顯式實(shí)現(xiàn) Unwrap() error。

空值處理如果 err 為 nil，或未實(shí)現(xiàn) Unwrap，或 Unwrap 返回 nil，則函數(shù)返回 nil。

小結(jié)

errors.Unwrap 是處理錯(cuò)誤鏈的基礎(chǔ)工具，適用于需要手動(dòng)逐層解包錯(cuò)誤的場(chǎng)景。結(jié)合 errors.Is 和 errors.As 可以實(shí)現(xiàn)更高效和安全的錯(cuò)誤檢查。在實(shí)際開發(fā)中，優(yōu)先使用 errors.Is 和 errors.As 來操作錯(cuò)誤鏈，僅在需要直接訪問特定層級(jí)錯(cuò)誤時(shí)使用 errors.Unwrap。

3.5 Join

簡(jiǎn)介

Golang 中的 errors.Join 函數(shù)是 Go 1.20 版本引入的一個(gè)錯(cuò)誤處理工具，用于將多個(gè)錯(cuò)誤合并為一個(gè)包裝錯(cuò)誤（wrapped error）。

它特別適用于需要同時(shí)處理多個(gè)錯(cuò)誤（例如并發(fā)操作中多個(gè)協(xié)程返回錯(cuò)誤）的場(chǎng)景。

函數(shù)簽名

func Join(errs ...error) error

參數(shù) errs …error：一個(gè)可變參數(shù)列表，接收多個(gè) error 類型的值。
返回值如果輸入的 errs 中存在至少一個(gè)非 nil 的錯(cuò)誤，則返回一個(gè)合并后的包裝錯(cuò)誤；否則返回 nil。

核心功能

合并多個(gè)錯(cuò)誤errors.Join 會(huì)將所有非 nil 的錯(cuò)誤合并為一個(gè)包裝錯(cuò)誤。合并后的錯(cuò)誤可以通過 errors.Unwrap 獲取所有原始錯(cuò)誤的切片。
兼容 errors.Is和 errors.As合并后的錯(cuò)誤支持通過 errors.Is 和 errors.As 檢查或提取其中的特定錯(cuò)誤。例如：

errors.Is(err, target)：如果合并后的錯(cuò)誤鏈中存在與 target 匹配的錯(cuò)誤，返回 true。
errors.As(err, &target)：可以提取合并錯(cuò)誤鏈中的第一個(gè)匹配類型的錯(cuò)誤。

錯(cuò)誤信息拼接合并后的錯(cuò)誤信息是多個(gè)原始錯(cuò)誤信息的拼接，以換行符分隔。例如：

err1 := errors.New("error 1")
err2 := errors.New("error 2")
joinedErr := errors.Join(err1, err2)
fmt.Println(joinedErr)
// 輸出:
// error 1
// error 2
示例代碼
package main

import (
    "errors"
    "fmt"
    "io/fs"
    "os"
)

func main() {
    err1 := errors.New("file not found")

    // 創(chuàng)建一個(gè) fs.PathError 錯(cuò)誤
    pathErr := &fs.PathError{
        Op:   "open",
        Path: "/etc/passwd",
        Err:  os.ErrPermission,
    }
    err2 := fmt.Errorf("operation failed: %w", pathErr)

    // 合并多個(gè)錯(cuò)誤
    joinedErr := errors.Join(err1, err2)

    // 打印合并后的錯(cuò)誤信息
    fmt.Println("Joined error:")
    fmt.Println(joinedErr)

    // 檢查是否包含特定錯(cuò)誤
    if errors.Is(joinedErr, err1) {
        fmt.Println("Found 'file not found' error")
    }

    // 提取錯(cuò)誤鏈中的某個(gè)類型
    var targetErr *fs.PathError
    if errors.As(joinedErr, &targetErr) {
        fmt.Println("Found PathError:", targetErr)
    }
}

運(yùn)行輸出：

Joined error:
file not found
operation failed: open /etc/passwd: permission denied
Found 'file not found' error
Found PathError: open /etc/passwd: permission denied

使用場(chǎng)景

并發(fā)操作中的錯(cuò)誤收集在多個(gè)協(xié)程并發(fā)執(zhí)行時(shí)，可以使用 errors.Join 收集所有協(xié)程返回的錯(cuò)誤：

func processTasks(tasks []Task) error {
    var wg sync.WaitGroup
    var mu sync.Mutex
    var errs []error

    for _, task := range tasks {
        wg.Add(1)
        go func(t Task) {
            defer wg.Done()
            if err := t.Run(); err != nil {
                mu.Lock()
                errs = append(errs, err)
                mu.Unlock()
            }
        }(task)
    }

    wg.Wait()
    return errors.Join(errs...)
}

批量操作中的錯(cuò)誤匯總例如，處理多個(gè)文件或請(qǐng)求時(shí)，統(tǒng)一返回所有錯(cuò)誤：

func batchProcess(files []string) error {
    var errs []error
    for _, file := range files {
        if err := processFile(file); err != nil {
            errs = append(errs, fmt.Errorf("process %s: %w", file, err))
        }
    }
    return errors.Join(errs...)
}

兼容已有錯(cuò)誤處理邏輯合并后的錯(cuò)誤仍然可以被 errors.Is 和 errors.As 處理，無需修改現(xiàn)有代碼。

注意事項(xiàng)

Go 版本要求errors.Join 僅在 Go 1.20 及以上版本可用。
空參數(shù)處理如果所有輸入錯(cuò)誤均為 nil，errors.Join 返回 nil。
錯(cuò)誤解包使用 errors.Unwrap 解包合并后的錯(cuò)誤時(shí)，會(huì)返回一個(gè) []error 切片（包含所有非 nil 錯(cuò)誤）。
錯(cuò)誤順序合并后的錯(cuò)誤順序與輸入?yún)?shù)的順序一致，但 errors.Is 和 errors.As 會(huì)按順序檢查所有錯(cuò)誤。

小結(jié)

errors.Join 提供了一種簡(jiǎn)潔的方式將多個(gè)錯(cuò)誤合并為一個(gè)，特別適用于需要匯總多個(gè)錯(cuò)誤信息的場(chǎng)景（如并發(fā)編程或批量處理）。通過結(jié)合 errors.Is 和 errors.As，可以靈活地檢查或提取合并后的錯(cuò)誤鏈中的特定錯(cuò)誤。它是 Go 錯(cuò)誤處理工具箱中的重要補(bǔ)充，進(jìn)一步提升了錯(cuò)誤管理的便利性。