错误处理

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发布说明