Go / 系统课时
创建、包装并检查 error
创建、包装并检查 error
这一课用一个可运行程序演示 Go 错误链:errors.New 定义稳定错误语义,fmt.Errorf 配合 %w 增加上下文,调用方再用 errors.Is 或 errors.As 检查根因,而不是依赖错误字符串。
学习目标
- 用
errors.New与fmt.Errorf("%w")创建并包装错误。 - 用
errors.Is在包装链中判断哨兵错误。 - 用
errors.As从错误链中取得具体错误类型和字段。
从错误值到错误链
当调用层只返回 errors.New("user not found"),上层知道“失败了”,却不知道失败发生在哪一步。包装错误时用 %w 保留原错误,同时把查询对象、操作阶段等上下文放进新错误消息。
下面程序同时演示哨兵错误和自定义错误类型,适用于 Go 1.13 及以上:
package main
import (
"errors"
"fmt"
)
// 包级哨兵错误提供稳定身份,调用方可用 errors.Is 判断。
var ErrNotFound = errors.New("user not found")
type ValidationError struct {
Field string
Msg string
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("%s: %s", e.Field, e.Msg)
}
func findUser(id int) error {
if id == 42 {
// %w 在增加查询上下文的同时保留 ErrNotFound。
return fmt.Errorf("query user %d: %w", id, ErrNotFound)
}
return nil
}
func saveAge(age int) error {
if age < 0 {
return fmt.Errorf(
"save profile: %w",
&ValidationError{Field: "age", Msg: "must be >= 0"},
)
}
return nil
}
func main() {
err := findUser(42)
fmt.Println(err)
fmt.Println("== sentinel:", err == ErrNotFound)
fmt.Println("errors.Is:", errors.Is(err, ErrNotFound))
err = saveAge(-1)
var target *ValidationError
// As 会穿过外层包装,取得具体类型携带的字段。
if errors.As(err, &target) {
fmt.Printf("validation field=%s message=%s\n", target.Field, target.Msg)
}
}预期结果:代码可直接编译运行,并同时产生一个被包装的哨兵错误和一个被包装的 *ValidationError,供后续两种检查 API 验证。
运行:
go run .预期输出:
query user 42: user not found
== sentinel: false
errors.Is: true
validation field=age message=must be >= 0err == ErrNotFound 为 false,因为最外层已经是 fmt.Errorf 创建的新错误;errors.Is 会沿包装关系向内检查,所以仍能找到 ErrNotFound。
用 errors.Is 判断稳定语义
哨兵错误应定义一次并复用,例如包级变量 var ErrNotFound = errors.New("user not found")。不要在判断位置重新写 errors.New("user not found"),即使字符串相同,它也是另一个错误值。

在服务层可以据此把内部错误映射成稳定行为,例如 HTTP 404、业务状态码或重试策略。判断逻辑应写成 errors.Is(err, ErrNotFound),而不是 strings.Contains(err.Error(), "not found");后者会被文案变化、语言变化和额外上下文轻易破坏。
用 errors.As 取得具体错误类型
当调用方不仅要知道“是哪类错误”,还要读取字段时,用 errors.As。示例中的目标变量是 *ValidationError,因此调用写成 errors.As(err, &target);第二个参数实际是指向目标变量的指针。
命中后可以直接读取 target.Field 与 target.Msg。这比对 err 做一次普通类型断言更稳,因为普通断言只检查最外层错误,而 errors.As 会沿错误链继续向内寻找。
包装时保留可判断性
同样是补充上下文,%v 和 %w 的行为不同。fmt.Errorf("load user: %v", err) 只把原错误格式化进字符串;fmt.Errorf("load user: %w", err) 才把原错误保留在可展开的错误关系中。
如果上层需要根据根因分支处理,就使用 %w。如果你故意不希望调用方继续识别内部错误语义,例如跨越安全边界时要屏蔽底层实现细节,可以创建一个新的公开错误,而不是把内部错误继续包装出去。
错误文本用于日志和排查,errors.Is、errors.As 用于程序分支。把“给人看的上下文”和“给代码判断的语义”分开,错误信息可以继续演进,而调用方不必跟着修改字符串匹配规则。