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

源码剖析：

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 库的基本使用和源码实现，能帮助我们更加熟练地处理错误，提高代码的健壮性和可维护性。

世界人工智能论坛

全面掌握 Go 语言 Errors 标准库：使用指南与源码深度解析

作者yinhua

前言

error 接口

errors 标准库的基本使用

错误创建：New 函数

错误匹配：Is 函数

错误断言：As 函数

包装错误：Join 函数

获取原始错误：Unwrap 函数

errors 标准库源码解析

errorString 结构体

New 函数

Is 函数

As 函数

joinError 结构体

Join 函数

Unwrap 函数

小结

作者 yinhua

相关文章

厉害了！Adobe新出Firefly视频模型，2分钟速成高清大片

突发！OpenAI发布最强模型o1：博士物理92.8分，IOI金牌水平

边缘智能的新时代：端侧大模型的研究进展综述

发表回复取消回复

您错过的

厉害了！Adobe新出Firefly视频模型，2分钟速成高清大片

突发！OpenAI发布最强模型o1：博士物理92.8分，IOI金牌水平

边缘智能的新时代：端侧大模型的研究进展综述

无图NOA：一场对高精地图的祛魅！2024在线高精地图方案的回顾与展望

世界人工智能论坛

作者yinhua

前言

error 接口

errors 标准库的基本使用

错误创建：New 函数

错误匹配：Is 函数

错误断言：As 函数

包装错误：Join 函数

获取原始错误：Unwrap 函数

errors 标准库源码解析

errorString 结构体

New 函数

Is 函数

As 函数

joinError 结构体

Join 函数

Unwrap 函数

小结

作者 yinhua

相关文章

发表回复 取消回复

您错过的

发表回复取消回复