Go语言错误包装与扩展技巧

IT行业相对于一般传统行业，发展更新速度更快，一旦停止了学习，很快就会被行业所淘汰。所以我们需要踏踏实实的不断学习，精进自己的技术，尤其是初学者。今天golang学习网给大家整理了《Go语言自定义错误包装与扩展方法》，聊聊，我们一起来看看吧！

用 fmt.Errorf 的 %w 动词包装错误可保留原始堆栈，支持 errors.Is/As；自定义错误需实现 Unwrap() 才能参与错误链；errors.As 要求目标为指针且类型匹配；仅当需逻辑判断或提取上下文时才定义自定义错误。

如何用 fmt.Errorf 包装错误并保留原始堆栈

Go 1.13+ 的错误包装机制依赖 fmt.Errorf 的 %w 动词，不是简单拼字符串。直接用 %s 或 + 拼接会丢失被包装错误的底层信息，导致 errors.Is 和 errors.As 失效。

正确做法是：

• 用 %w 唯一标识“被包装的错误”，且只能出现一次（多个 %w 会 panic）
• 被包装的错误必须是非 nil；若上游返回 nil，不要传给 %w，否则运行时报错
• %w 后面不能再跟其他动词（如 %w: %s 是非法的），格式需严格为 "msg: %w" 或 "%w"

示例：

err := doSomething()
if err != nil {
    return fmt.Errorf("failed to process item: %w", err) // ✅ 正确
}

定义自定义错误类型时为何要实现 Unwrap 方法

只有实现了 Unwrap() error 方法的类型，才能被 errors.Unwrap、errors.Is、errors.As 等标准库函数识别为“可包装错误”。不实现它，你的类型就只是普通 error，无法参与错误链遍历。

常见误区：

• 只实现 Error() string，忘了 Unwrap → 包装后无法向下查找原始错误
• Unwrap 返回 nil 表示“已到错误链末端”，返回非 nil 才继续展开
• 若错误包含多个嵌套错误（少见），Unwrap 应只返回一个（Go 错误链是单向链表，不是树）

示例：

type ValidationError struct {
    Field string
    Err   error
}

func (e *ValidationError) Error() string {
    return "validation failed on " + e.Field
}

func (e *ValidationError) Unwrap() error {
    return e.Err // ✅ 让 errors.Is 能穿透到 e.Err
}

errors.As 查找自定义错误类型失败的三个原因

errors.As 用于从错误链中提取特定类型的错误实例，但经常查不到——多数是因为类型不匹配或指针问题。

• 目标变量必须是指针（&target），因为 As 需要赋值，而 Go 的 error 接口是值类型
• 自定义错误类型本身是结构体时，必须用指向它的指针类型做断言（即 *MyError，不是 MyError）
• 如果错误链中某层是 fmt.Errorf("... %w", err)，但 err 是 MyError{}（值），而非 &MyError{}（指针），则 As 会失败——因为 Unwrap() 返回的是值，而 As 只匹配指针类型

安全写法：

var ve *ValidationError
if errors.As(err, &ve) {
    log.Printf("validation error on field: %s", ve.Field)
}

何时该用自定义错误类型，何时只需 fmt.Errorf 包装

自定义错误类型不是为了“看起来更专业”，而是为了支持程序逻辑判断和差异化处理。如果错误不需要被代码分支识别（比如仅日志打印），用 fmt.Errorf("context: %w", err) 就够了。

• 需要 errors.Is 判断错误类别（如重试、跳过、告警）→ 定义带导出变量的错误（var ErrNotFound = errors.New("not found")）
• 需要提取上下文数据（如失败字段名、HTTP 状态码）→ 定义结构体错误，并实现 Unwrap 和字段访问方法
• 只是加一层调用上下文（如 “failed to read config file”）→ 直接 fmt.Errorf 包装，别造类型

过度设计自定义错误会导致类型爆炸，且大多数时候 errors.Is 已足够 —— 真正难的是厘清哪些错误值得区分、哪些应该统一处理。

好了，本文到此结束，带大家了解了《Go语言错误包装与扩展技巧》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！