As

func As(err error, target any) bool

Go 1.13 新增

As 会在 err 及其包装的错误中，查找第一个与 target 匹配的值。找到后，它会把该值赋给 target 并返回 true；找不到则返回 false。

当错误值可以赋给 target 指向的类型时，视为匹配。如果错误实现了 As(any) bool 并返回成功，也视为匹配；此时自定义 As 方法需要负责给目标赋值。

target 必须是指向错误类型或任意接口类型的非空指针，否则会触发 panic。对于 Go 1.26 及更高版本，标准库建议大多数场景优先使用 AsType。

示例

_, err := os.Open("missing.txt")
var pathError *fs.PathError

if errors.As(err, &pathError) {
    fmt.Println(pathError.Path)
}

输出

missing.txt

AsType

func AsType[E error](err error) (E, bool)

Go 1.26 新增

AsType 在错误树中查找第一个与类型 E 匹配的值。 找到后返回该值和 true；找不到则返回 E 的零值和 false。

当错误值可以断言为 E 时，视为匹配。如果错误针对非空的 *E 目标实现了成功的 As(any) bool 方法，也视为匹配。

示例

_, err := os.Open("missing.txt")

if pathError, ok := errors.AsType[*fs.PathError](err); ok {
    fmt.Println(pathError.Op)
}

输出

open

Is

func Is(err, target error) bool

Go 1.13 新增

Is 用来判断错误树中是否存在与 target 匹配的错误。 target 必须可比较。当错误可能被包装时，使用 Is 通常比直接比较更可靠。

当错误等于 target，或错误实现的 Is(error) bool 方法报告匹配时，视为匹配。自定义 Is 方法只应比较当前错误与目标， 不应自行展开其中任何一方。

示例

_, err := os.Open("missing.txt")
fmt.Println(errors.Is(err, fs.ErrNotExist))

输出

true

Join

func Join(errs ...error) error

Go 1.20 新增

Join 把所有非空参数合并为一个错误。如果所有参数都是 nil，它会返回 nil。合并后的错误信息会把每条错误放在单独一行。

非空结果实现了 Unwrap() []error，因此可以通过 Is、As 或 AsType 查找其中的错误。

示例

readErr := errors.New("read failed")
writeErr := errors.New("write failed")
err := errors.Join(readErr, nil, writeErr)

fmt.Println(err)
fmt.Println(errors.Is(err, readErr))

输出

read failed
write failed
true

New

func New(text string) error

New 返回一个错误，其错误信息就是 text。每次调用都会创建 不同的错误值，即使传入的文字完全相同。如果调用方需要判断一个哨兵错误，应声明并复用同一个包级变量。

示例

first := errors.New("not ready")
second := errors.New("not ready")

fmt.Println(first)
fmt.Println(first == second)

输出

not ready
false

Unwrap

func Unwrap(err error) error

Go 1.13 新增

如果 err 实现了 Unwrap() error， Unwrap 会返回该方法产生的错误；否则返回 nil。

它不会调用 Unwrap() []error，所以不能直接展开 Join 返回的错误。若要搜索完整错误树，应使用 Is、As 或 AsType。

示例

inner := errors.New("disk full")
outer := fmt.Errorf("save file: %w", inner)

fmt.Println(errors.Unwrap(outer))

输出

disk full

ErrUnsupported

var ErrUnsupported = New("unsupported operation")

ErrUnsupported 表示当前系统或实现无法执行某项操作。通常应先补充有用的上下文， 再包装并返回它，而不是直接返回这个值。

调用方可以使用 errors.Is(err, errors.ErrUnsupported) 进行判断。 返回包含此错误的函数，应在文档中说明它可能在哪些情况下出现。

示例

func compress() error {
    return fmt.Errorf("gzip: %w", errors.ErrUnsupported)
}

err := compress()
fmt.Println(errors.Is(err, errors.ErrUnsupported))

输出

true