错误处理

是什么，为什么存在

Go 把失败作为值从函数中返回。常见签名会同时返回有效结果和 error，例如 (Order, error)。按照约定，nil 表示成功，非 nil 错误表示操作失败。

内置接口刻意保持简洁：错误只需实现 Error() string 方法。errors.New 创建的字符串错误、应用定义的结构化类型，以及 fmt.Errorf 生成的包装器，都能满足同一个接口。调用方可以通过 error 处理它们，无需知道每种具体实现。

显式返回让可预期的失败留在正常控制流中。无效输入、记录不存在、取消和网络超时都不需要展开调用栈。函数签名说明操作可能失败，调用位置则清楚展示下一步如何处理。

几乎每个 Go 包都会出现这种模式。文件操作、解析函数、数据库调用、HTTP 客户端和并发 worker 都会返回错误。难点通常不是写出 if err != nil，而是为真正能作出决定的那一层保留足够信息。

错误也是 API 契约的一部分。一个包可能只承诺成功或失败，也可能公开稳定的 哨兵错误（sentinel error） 、返回有文档说明的具体类型，或者提供判断函数。调用方只能依赖包文档明确承诺的属性。

应该选择足以支持实际判断的最小契约：

工作原理

预声明的 error 接口只有一个方法：Error() string。格式化错误时会调用该方法，但字符串并不定义错误的身份。两个无关的值可能产生相同消息；包装器也可能在保留底层原因的同时改变消息。

返回 (T, error) 的函数失败时，通常会返回 T 的零值。调用方要先检查错误，再使用结果。这是一项约定，不是类型系统强制的规则，因此函数文档必须说明部分结果是否仍然可用。

大多数调用位置都遵循简短的卫语句流程：

1. 调用操作，接收结果和错误。
2. 如果错误非 nil，就处理错误，或添加有用上下文后返回。
3. 只有成功路径才能继续使用结果。

发现失败的那一层知道直接原因。解析器知道哪个 token 无效；存储适配器知道哪个文件或查询失败。更高层知道当时执行的业务操作。错误包装让每一层都能添加自己的上下文，而不抹掉前面的事实。

fmt.Errorf("load account %q: %w", id, err) 会创建一个包装 err 的新错误。重复包装会形成 错误链（error chain） 。每个包装器都贡献一段消息，而 errors.Is 和 errors.As 仍能检查链中更深的错误。

当判断依赖某个错误值，或某个类型定义的自定义匹配规则时，使用 errors.Is(err, target)。它会检查整条链，因此经过一层或多层 %w 包装后仍能找到哨兵错误。直接使用 == 只能看到最外层的值，包装后就无法匹配。

当你需要某种错误类型及其结构化字段时，使用 errors.As(err, &target)。目标必须是一个非 nil 指针，指向实现了 error 的类型或某个接口类型。匹配成功后，As 会把找到的值赋给目标。

errors.Join 会把多个非 nil 错误合成一个值。结果通过 Unwrap() []error 公开所有子错误，errors.Is 或 errors.As 会遍历每个分支。如果所有输入都是 nil，Join 会返回 nil。

错误应由能够采取行动的那一层处理。库通常返回错误；HTTP 边界可以把它转换为状态码；命令可以打印一次再退出；重试循环可以先检查错误再决定是否重试。在每个中间返回位置都记录日志，通常只会为同一次失败产生多条重复记录。

示例

返回并检查错误

第一个示例解析数量。parseQuantity 会把输入值加入转换失败的上下文，main 则把成功路径和失败路径分开。

失败时返回 0，因为不存在有效数量。调用方不会把这个零值当作数据使用，而是先检查 err。%w 会保留 strconv 错误，供后续代码按需检查。

匹配被包装的哨兵错误

调用方只需要稳定类别、不需要额外字段时，哨兵错误很合适。导出的哨兵错误通常以 Err 开头，其文档应说明哪些操作可能返回或包装它。

package main

import (
	"errors"
	"fmt"
)

var ErrProductNotFound = errors.New("product not found")

func productPrice(sku string) (int, error) {
	prices := map[string]int{"PEN-1": 250}
	price, ok := prices[sku]
	if !ok {
		return 0, fmt.Errorf("lookup %q: %w", sku, ErrProductNotFound)
	}
	return price, nil
}

func quote(sku string, quantity int) (int, error) {
	price, err := productPrice(sku)
	if err != nil {
		return 0, fmt.Errorf("quote %q: %w", sku, err)
	}
	return price * quantity, nil
}

func main() {
	_, err := quote("PEN-9", 2)
	fmt.Println("error:", err)
	fmt.Println("not found:", errors.Is(err, ErrProductNotFound))
}

error: quote "PEN-9": lookup "PEN-9": product not found
not found: true

两层代码都为消息添加了上下文，但仍能发现 ErrProductNotFound。err == ErrProductNotFound 这样的直接比较会得到 false，因为 err 是最外层包装器。errors.Is 问的才是调用方真正关心的语义问题。

提取结构化错误

如果调用方除了类别还需要读取字段，就应使用自定义类型。这个 FieldError 会指出被拒绝的字段和值，同时包装表示更宽泛类别的哨兵错误。

package main

import (
	"errors"
	"fmt"
	"strings"
)

var ErrInvalidField = errors.New("invalid field")

type FieldError struct {
	Field string
	Value string
	Err   error
}

func (e *FieldError) Error() string {
	return fmt.Sprintf("%s=%q: %v", e.Field, e.Value, e.Err)
}

func (e *FieldError) Unwrap() error { return e.Err }

func validateEmail(email string) error {
	if !strings.Contains(email, "@") {
		return &FieldError{"email", email, ErrInvalidField}
	}
	return nil
}

func main() {
	err := validateEmail("alex.example.com")
	var fieldErr *FieldError
	fmt.Println("invalid:", errors.Is(err, ErrInvalidField))
	if errors.As(err, &fieldErr) {
		fmt.Printf("field: %s, value: %s\n", fieldErr.Field, fieldErr.Value)
	}
}

invalid: true
field: email, value: alex.example.com

Unwrap 会让自定义错误成为错误链的一部分。errors.Is 可以看到类别，errors.As 则把匹配的 *FieldError 赋给目标，供调用方读取字段。这比解析 Error() 输出安全得多。

保留多个验证失败

调用方作出响应前，可以把互不依赖的检查全部执行完。errors.Join 会保留每项失败，不必迫使验证器只选一个，也不用另行设计专用的切片类型。

package main

import (
	"errors"
	"fmt"
	"strings"
)

var (
	ErrNameRequired = errors.New("name is required")
	ErrEmailInvalid = errors.New("email is invalid")
)

func validateCheckout(name, email string) error {
	var failures []error
	if strings.TrimSpace(name) == "" {
		failures = append(failures, ErrNameRequired)
	}
	if !strings.Contains(email, "@") {
		failures = append(failures, ErrEmailInvalid)
	}
	return errors.Join(failures...)
}

func main() {
	err := validateCheckout("", "alex.example.com")
	fmt.Println(err)
	fmt.Println("name required:", errors.Is(err, ErrNameRequired))
	fmt.Println("email invalid:", errors.Is(err, ErrEmailInvalid))
}

name is required
email is invalid
name required: true
email invalid: true

合并后的消息每个子错误占一行，但调用方不应解析这些行。它们可以通过合并值匹配任意哨兵错误。输入有效时，切片为空，errors.Join(failures...) 会返回 nil。

陷阱

丢弃错误或延迟检查

错误应紧挨着产生它的调用进行检查。只有操作契约明确说明失败无关紧要时才忽略错误；如果这一选择可能让审查者困惑，应留下简短原因。静态分析可以发现部分被丢弃的结果，却无法判断剩余行为是否安全。

根据消息匹配错误

对于文档明确承诺的值，使用 errors.Is；对于文档明确承诺的类型，使用 errors.As。如果依赖只公开文本，就在自己的适配器边界把失败转换成由本包控制的错误契约。不要迫使每个调用方重复解析文本。

包装导致实现细节外泄

只有确实希望调用方检查原因时才包装它。否则，应把它转换成本包定义的错误，并按需在边界诊断信息中保留原始详情。更换数据库驱动时，不应悄悄破坏那些被鼓励匹配旧驱动错误的调用方。

返回带类型的 nil

成功时直接返回字面值 nil。不要把 nil 的 *MyError 赋给 error 结果，并添加成功路径测试来断言 err == nil。如果 Error 方法会解引用接收者，格式化这个有问题的接口值还可能触发 panic。

记录后又返回同一个失败

可复用代码应添加上下文后返回错误。只在拥有结果的进程、请求或 worker 边界记录一次。这个边界可以附加稳定元数据，并防止凭据、载荷和个人数据进入消息。

对预期失败使用 panic

预期中的运行失败应返回错误。只有不变量被破坏，或名称以 Must 开头且契约明确说明会 panic 的辅助函数，才适合使用 panic。恢复机制属于边界处理，不能替代普通错误流；go/defer-panic-recover 专题有更详细的说明。

延伸阅读

• Package errors
• Package fmt：Errorf
• Go 博客：Working with Errors in Go 1.13
• Go 1.27 发布说明