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