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

零 Golang教程评论86字数 10470阅读34分54秒阅读模式

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

前言

在 Go 语言中,错误处理是一个重要的部分。Go 官方提供了一个轻量级的 errors 标准库,用于创建和处理错误。本文将介绍如何使用 Go 的 errors 标准库,并深入解析其源码实现。

准备好了吗?准备一杯你最喜欢的咖啡或茶,随着本文一探究竟吧。文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

请在此添加图片描述文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

Go 版本:1.22.0文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

error 接口

下面的内容会提到 error 接口,因此我们有必要先了解一下 error 接口的相关定义。文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

在 Go 语言中,error 是一个内置接口,它定义了一个 Error 方法。文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

go

代码解读
复制代码
type error interface {
    Error() string
}

任何实现了 error 接口的类型,都可以当做 错误类型 来使用。文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

errors 标准库的基本使用

错误创建:New 函数

errors.New 函数用于创建并返回一个新的 error 类型的对象。文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

errors.New 函数的签名如下:文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

go

代码解读
复制代码
func New(text string) error

其中:文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

  • 参数text 是一个字符串,表示错误的描述。
  • 返回值:返回一个 error 类型的对象,该对象包含了传入的文本信息。

下面是 New 函数的代码使用示例:文章源自灵鲨社区-https://www.0s52.com/bcjc/golangjc/17050.html

go

代码解读
复制代码
// 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 函数的签名如下:

go

代码解读
复制代码
func Is(err, target error) bool
  • 参数
    • err 为要检查的错误。
    • target 为目标错误。errors.Is 函数会检查 err 是否等于 target,或 err 链中是否存在一个错误等于 target
  • 返回值: 返回一个 bool 类型的值。如果两个 error 相等,返回 true,否则返回 false

下面是 Is 函数的代码使用示例:

go

代码解读
复制代码
// 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 函数的签名如下:

go

代码解读
复制代码
func As(err error, target any) bool
  • 参数
    • err 为被断言的错误。
    • target 为目标错误,它必须是一个非空指针。
  • 返回值:返回一个 bool 类型的值。如果断言成功,返回 true,否则返回 false

下面是 As 函数的代码使用示例:

go

代码解读
复制代码
// 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 函数的签名如下:

go

代码解读
复制代码
func Join(errs ...error) error

其中:

  • 参数errs 为所给定的错误集。
  • 返回值:返回一个 error 接口类型的对象,其值为包装后的新 error

下面是 Join 函数的代码使用示例:

go

代码解读
复制代码
// 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
}

程序的运行结果为:

bash

代码解读
复制代码
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 函数的签名如下:

go

代码解读
复制代码
func Unwrap(err error) error

其中:

  • 参数err 为所给定的错误。
  • 返回值:返回一个 error 类型的对象。其值为解包后的 error

下面是 Unwrap 函数的代码使用示例:

go

代码解读
复制代码
// 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))
}

程序的运行结果为:

bash

代码解读
复制代码
user not found: name=陈明勇
user not found

errors 标准库源码解析

errorString 结构体

go

代码解读
复制代码
type errorString struct {
	s string
}

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

errorString 结构体是一个简单的 error 实现,它只有一个类型为 string 的 s 字段,用于存储错误信息。当调用 Error() 方法时,该方法将会返回 s 字段的值。

New 函数

New 函数用于生成一个新的错误对象,其返回值为 errorString 类型的实例。

go

代码解读
复制代码
func New(text string) error {
    return &errorString{text}
}

Is 函数

errors.Is 函数用于判断两个 error 是否相等。

go

代码解读
复制代码
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,表示可比较,否则表示不可比较
  • 详细比较:将 errtarget 以及 isComparable 变量作为参数调用 is 函数进行详细比较。

go

代码解读
复制代码
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 函数用于检查一个错误是否可以被断言为特定的错误类型,断言成功则将错误的值赋给特定的错误变量。

go

代码解读
复制代码
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
  • 详细比较:将 errtarget 和 val 以及 targetType 变量作为参数调用 as 函数进行详细比较。

go

代码解读
复制代码
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 结构体

go

代码解读
复制代码
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(错误集) 并返回一个新的错误对象。

go

代码解读
复制代码
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

go

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

零
  • 转载请务必保留本文链接:https://www.0s52.com/bcjc/golangjc/17050.html
    本社区资源仅供用于学习和交流,请勿用于商业用途
    未经允许不得进行转载/复制/分享

发表评论