package errors
import "errors"
Package errors 实现了操作错误的函数。
New 函数创建的错误,其内容仅为一条文本消息。
如果错误 e 的类型具有以下方法之一,则称 e 包装了另一个错误:
Unwrap() error Unwrap() []error
如果 e.Unwrap() 返回一个非 nil 的错误 w 或包含 w 的切片, 则称 e 包装了 w。e.Unwrap() 返回 nil 错误 表示 e 没有包装任何错误。Unwrap 方法返回 包含 nil 错误值的 []error 是无效的。
创建包装错误的一种简便方法是调用 fmt.Errorf 并 对错误参数应用 %w 动词:
wrapsErr := fmt.Errorf("... %w ...", ..., err, ...)
对错误进行连续解包会形成一棵树。Is 和 As 函数通过先检查错误本身,然后依次检查其每个 子节点的树来检查错误的树 (先序、深度优先遍历)。
关于包装的理念以及何时进行包装的更深入讨论, 参见 https://go.dev/blog/go1.13-errors。
Is 检查其第一个参数的树,寻找与第二个参数 匹配的错误。它报告是否找到匹配项。应优先使用 它而不是简单的相等性检查:
if errors.Is(err, fs.ErrExist)
优于
if err == fs.ErrExist
因为如果 err 包装了 io/fs.ErrExist,前者会成功。
AsType 检查其参数的树,寻找类型与其类型参数 匹配的错误。如果成功,则返回该类型对应的值 以及 true。否则,返回该类型的零值 以及 false。以下形式
if perr, ok := errors.AsType[*fs.PathError](err); ok {
fmt.Println(perr.Path)
}
优于
if perr, ok := err.(*fs.PathError); ok {
fmt.Println(perr.Path)
}
因为如果 err 包装了一个 *io/fs.PathError,前者会成功。
Output:Example
package main
import (
"fmt"
"time"
)
// MyError is an error implementation that includes a time and message.
type MyError struct {
When time.Time
What string
}
func (e MyError) Error() string {
return fmt.Sprintf("%v: %v", e.When, e.What)
}
func oops() error {
return MyError{
time.Date(1989, 3, 15, 22, 30, 0, 0, time.UTC),
"the file system has gone away",
}
}
func main() {
if err := oops(); err != nil {
fmt.Println(err)
}
}
1989-03-15 22:30:00 +0000 UTC: the file system has gone away
Index
- Variables
- func As(err error, target any) bool
- func AsType(err error) (E, bool)
- func Is(err, target error) bool
- func Join(errs ...error) error
- func New(text string) error
- func Unwrap(err error) error
Examples
- As
- As (Custom_match)
- AsType
- AsType (Custom_match)
- Is
- Is (Custom_match)
- Join
- New
- New (Errorf)
- New (Unique)
- Unwrap
- package
Variables
var ErrUnsupported = New("unsupported operation")
ErrUnsupported 表示请求的操作无法执行,因为 它不受支持。例如,在使用不支持硬链接的 文件系统时调用 os.Link。
函数和方法不应返回此错误,而应返回一个 包含适当上下文、满足以下条件的错误:
errors.Is(err, errors.ErrUnsupported)
可以通过直接包装 ErrUnsupported 或实现 Is 方法来实现。
函数和方法应记录将会返回包装此错误的 错误的情况。
Functions
func As
func As(err error, target any) bool
As 在 err 的树中查找第一个与 target 匹配的错误,如果找到, 则将 target 设置为该错误值并返回 true。否则,返回 false。
在大多数情况下,优先使用 AsType。As 与 AsType 等价, 但它设置其 target 参数而非返回匹配的错误,且不要求其 target 参数实现 error。
该树由 err 本身,以及通过重复调用其 Unwrap() error 或 Unwrap() []error 方法所得到的错误组成。当 err 包装多个错误时, As 先检查 err,然后对其子节点进行深度优先遍历。
如果错误的具化值可赋值给 target 所指向的值,或者该错误 具有一个方法 As(any) bool 使得 As(target) 返回 true, 则该错误与 target 匹配。在后一种情况下,由 As 方法负责 设置 target。
错误类型可以提供 As 方法,以使其可被视为 另一种错误类型。
如果 target 不是非 nil 指针,指向实现 error 的类型或
任意接口类型,则 As 会 panic。
Output: Custom errors can implement a method "As(any) bool" to match against other error types,
overriding the default matching of errors.As.
Output:Example
package main
import (
"errors"
"fmt"
"io/fs"
"os"
)
func main() {
if _, err := os.Open("non-existing"); err != nil {
var pathError *fs.PathError
if errors.As(err, &pathError) {
fmt.Println("Failed at path:", pathError.Path)
} else {
fmt.Println(err)
}
}
}
Failed at path: non-existing
Example (Custom_match)
package main
import (
"errors"
"fmt"
"io/fs"
)
type MyAsError struct {
err string
}
func (e MyAsError) Error() string {
return e.err
}
func (e MyAsError) As(target any) bool {
pe, ok := target.(**fs.PathError)
if !ok {
return false
}
*pe = &fs.PathError{
Op: "custom",
Path: "/",
Err: errors.New(e.err),
}
return true
}
func main() {
var err error = MyAsError{"an error"}
fmt.Println("Error:", err)
fmt.Printf("TypeOf err: %T\n", err)
var pathError *fs.PathError
ok := errors.As(err, &pathError)
fmt.Println("Error as fs.PathError:", ok)
fmt.Println("fs.PathError:", pathError)
}
Error: an error
TypeOf err: errors_test.MyAsError
Error as fs.PathError: true
fs.PathError: custom /: an error
func AsType
func AsType[E error](err error) (E, bool)
AsType 在 err 的树中查找第一个与类型 E 匹配的错误,如果找到, 则返回该错误值以及 true。否则,返回 E 的零值 以及 false。
该树由 err 本身,以及通过重复调用其 Unwrap() error 或 Unwrap() []error 方法所得到的错误组成。当 err 包装多个 错误时,AsType 先检查 err,然后对其子节点 进行深度优先遍历。
如果类型断言 err.(E) 成立,或者该错误具有一个方法
As(any) bool 使得当 target 为非 nil 的 *E 时
err.As(target) 返回 true,则错误 err 与类型 E 匹配。
在后一种情况下,由 As 方法负责设置 target。
Output: Custom errors can implement a method "As(any) bool" to match against other error types,
overriding the default matching of errors.AsType.
Output:Example
package main
import (
"errors"
"fmt"
"io/fs"
"os"
)
func main() {
if _, err := os.Open("non-existing"); err != nil {
if pathError, ok := errors.AsType[*fs.PathError](err); ok {
fmt.Println("Failed at path:", pathError.Path)
} else {
fmt.Println(err)
}
}
}
Failed at path: non-existing
Example (Custom_match)
package main
import (
"errors"
"fmt"
"io/fs"
)
type MyAsError struct {
err string
}
func (e MyAsError) Error() string {
return e.err
}
func (e MyAsError) As(target any) bool {
pe, ok := target.(**fs.PathError)
if !ok {
return false
}
*pe = &fs.PathError{
Op: "custom",
Path: "/",
Err: errors.New(e.err),
}
return true
}
func main() {
var err error = MyAsError{"an error"}
fmt.Println("Error:", err)
fmt.Printf("TypeOf err: %T\n", err)
pathError, ok := errors.AsType[*fs.PathError](err)
fmt.Println("Error as fs.PathError:", ok)
fmt.Println("fs.PathError:", pathError)
}
Error: an error
TypeOf err: errors_test.MyAsError
Error as fs.PathError: true
fs.PathError: custom /: an error
func Is
func Is(err, target error) bool
Is 报告 err 的树中是否有任何错误与 target 匹配。 target 必须是可比较的。
该树由 err 本身,以及通过重复调用其 Unwrap() error 或 Unwrap() []error 方法所得到的错误组成。当 err 包装多个错误时, Is 先检查 err,然后对其子节点进行深度优先遍历。
如果某个错误等于 target,或者它实现了一个方法 Is(error) bool 使得 Is(target) 返回 true,则认为该错误与 target 匹配。
错误类型可以提供 Is 方法,以使其可被视为等同于一个 已有的错误。例如,如果 MyError 定义了
func (m MyError) Is(target error) bool { return target == fs.ErrExist }
那么 Is(MyError{}, fs.ErrExist) 返回 true。标准库中的示例
参见 syscall.Errno.Is。Is 方法应仅浅层地比较 err 和
target,且不应在两者上调用 Unwrap。
Output: Custom errors can implement a method "Is(error) bool" to match other error values,
overriding the default matching of errors.Is.
Output:Example
package main
import (
"errors"
"fmt"
"io/fs"
"os"
)
func main() {
if _, err := os.Open("non-existing"); err != nil {
if errors.Is(err, fs.ErrNotExist) {
fmt.Println("file does not exist")
} else {
fmt.Println(err)
}
}
}
file does not exist
Example (Custom_match)
package main
import (
"errors"
"fmt"
"io/fs"
)
type MyIsError struct {
err string
}
func (e MyIsError) Error() string {
return e.err
}
func (e MyIsError) Is(err error) bool {
return err == fs.ErrPermission
}
func main() {
var err error = MyIsError{"an error"}
fmt.Println("Error equals fs.ErrPermission:", err == fs.ErrPermission)
fmt.Println("Error is fs.ErrPermission:", errors.Is(err, fs.ErrPermission))
}
Error equals fs.ErrPermission: false
Error is fs.ErrPermission: true
func Join
func Join(errs ...error) error
Join 返回一个包装了给定错误的错误。 任何 nil 错误值都会被丢弃。 如果 errs 中的每个值都是 nil,则 Join 返回 nil。 该错误格式化后为调用 errs 中每个元素的 Error 方法 所得到的字符串的拼接,每个字符串之间以一个 换行符分隔。
Join 返回的非 nil 错误实现了 Unwrap() []error 方法。
可以使用 Is 和 As 检查这些错误。
Output:Example
package main
import (
"errors"
"fmt"
)
func main() {
err1 := errors.New("err1")
err2 := errors.New("err2")
err := errors.Join(err1, err2)
fmt.Println(err)
if errors.Is(err, err1) {
fmt.Println("err is err1")
}
if errors.Is(err, err2) {
fmt.Println("err is err2")
}
fmt.Println(err.(interface{ Unwrap() []error }).Unwrap())
}
err1
err2
err is err1
err is err2
[err1 err2]
func New
func New(text string) error
New 返回一个格式化后为给定文本的错误。
即使文本相同,每次调用 New 也都会返回一个不同的错误值。
Output: The fmt package's Errorf function lets us use the package's formatting
features to create descriptive error messages.
Output: Each call to errors.New returns an unique instance of the error,
even if the arguments are the same. To match against errors
created by errors.New, declare a sentinel error and reuse it.
Output:Example
package main
import (
"errors"
"fmt"
)
func main() {
err := errors.New("emit macho dwarf: elf header corrupted")
if err != nil {
fmt.Print(err)
}
}
emit macho dwarf: elf header corrupted
Example (Errorf)
package main
import (
"fmt"
)
func main() {
const name, id = "bimmler", 17
err := fmt.Errorf("user %q (id %d) not found", name, id)
if err != nil {
fmt.Print(err)
}
}
user "bimmler" (id 17) not found
Example (Unique)
package main
import (
"errors"
"fmt"
)
func OopsNew() error {
return errors.New("an error")
}
var ErrSentinel = errors.New("an error")
func OopsSentinel() error {
return ErrSentinel
}
func main() {
err1 := OopsNew()
err2 := OopsNew()
fmt.Println("Errors using distinct errors.New calls:")
fmt.Printf("Is(%q, %q) = %v\n", err1, err2, errors.Is(err1, err2))
err3 := OopsSentinel()
err4 := OopsSentinel()
fmt.Println()
fmt.Println("Errors using a sentinel error:")
fmt.Printf("Is(%q, %q) = %v\n", err3, err4, errors.Is(err3, err4))
}
Errors using distinct errors.New calls:
Is("an error", "an error") = false
Errors using a sentinel error:
Is("an error", "an error") = true
func Unwrap
func Unwrap(err error) error
Unwrap 返回对 err 调用 Unwrap 方法的结果,如果 err 的类型 包含一个返回 error 的 Unwrap 方法。 否则,Unwrap 返回 nil。
Unwrap 仅调用形式为 "Unwrap() error" 的方法。
特别地,Unwrap 不会解包由 Join 返回的错误。
Output:Example
package main
import (
"errors"
"fmt"
)
func main() {
err1 := errors.New("error1")
err2 := fmt.Errorf("error2: [%w]", err1)
fmt.Println(err2)
fmt.Println(errors.Unwrap(err2))
}
error2: [error1]
error1