Go Academy · 课时

错误包装与拆包

使用 %w、errors.Is 与 errors.As

错误包装与拆包 是 CoddyKit 上的免费 Go Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Go Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Go Academy 课程共包含 4 节课。

什么是错误包装？

错误包装会将原始错误嵌入新错误中，在添加上下文的同时保留原始错误，以便程序检查。Go 1.13 正式引入了这种机制：

package main
import ("fmt"; "errors")

var ErrDB = errors.New("database unreachable")

func queryUsers() error {
    return fmt.Errorf("queryUsers: %w", ErrDB)
}

func loadProfile(id int) error {
    return fmt.Errorf("loadProfile(%d): %w", id, queryUsers())
}

func main() {
    err := loadProfile(42)
    fmt.Println(err) // loadProfile(42): queryUsers: database unreachable
}

%w 动词

在 fmt.Errorf 中使用 %w（而不是 %v）来包装错误。可以通过 errors.Unwrap 访问被包装的错误：

package main
import ("fmt"; "errors")

func main() {
    inner := errors.New("inner error")
    outer := fmt.Errorf("outer: %w", inner)

    fmt.Println(outer)              // outer: inner error
    fmt.Println(errors.Unwrap(outer)) // inner error
    fmt.Println(errors.Is(outer, inner)) // true
}

errors.Unwrap

errors.Unwrap 会返回错误链中的下一个错误（被包装的错误）；如果不存在，则返回 nil：

package main
import ("fmt"; "errors")

type Layer struct{ msg string; err error }
func (l *Layer) Error() string { return l.msg }
func (l *Layer) Unwrap() error { return l.err }

func main() {
    root := errors.New("root")
    mid  := &Layer{"mid", root}
    top  := &Layer{"top", mid}

    fmt.Println(errors.Unwrap(top))  // mid
    fmt.Println(errors.Unwrap(mid))  // root
    fmt.Println(errors.Unwrap(root)) // <nil>
}

errors.Is — 遍历错误链

errors.Is(err, target) 会递归解包错误链，直到找到匹配项或到达 nil：

package main
import ("fmt"; "errors")

var ErrNotFound = errors.New("not found")

func findItem(id int) error {
    return fmt.Errorf("findItem(%d): %w",
        id, fmt.Errorf("repo: %w", ErrNotFound))
}

func main() {
    err := findItem(7)
    fmt.Println(errors.Is(err, ErrNotFound)) // true — deep in chain
    fmt.Println(err)                         // full message chain
}

errors.As — 按类型遍历错误链

errors.As(err, &target) 会遍历错误链，查找可赋值给 target 类型的错误：

package main
import ("fmt"; "errors")

type StatusError struct{ Code int }
func (e *StatusError) Error() string { return fmt.Sprintf("status %d", e.Code) }

func doRequest() error {
    return fmt.Errorf("request: %w", &StatusError{503})
}

func main() {
    err := doRequest()
    var se *StatusError
    if errors.As(err, &se) {
        fmt.Println("status code:", se.Code) // 503
    }
}

用于错误链的自定义 Unwrap

在自定义错误类型上实现 Unwrap() error，以支持 errors.Is 和 errors.As：

package main
import ("fmt"; "errors")

type AppError struct {
    Op  string
    Err error
}
func (e *AppError) Error() string  { return fmt.Sprintf("%s: %v", e.Op, e.Err) }
func (e *AppError) Unwrap() error  { return e.Err }

var ErrAuth = errors.New("unauthorized")

func main() {
    err := &AppError{"login", ErrAuth}
    fmt.Println(errors.Is(err, ErrAuth)) // true
}

fmt.Errorf 中的 %v 与 %w

%v 与 %w 的区别：

package main
import ("fmt"; "errors")

func main() {
    inner := errors.New("inner")

    withV := fmt.Errorf("outer: %v", inner) // string only, no wrap
    withW := fmt.Errorf("outer: %w", inner) // wraps inner

    fmt.Println(errors.Is(withV, inner)) // false — not wrapped
    fmt.Println(errors.Is(withW, inner)) // true  — wrapped
}

实际包装：HTTP 处理器

一致的错误包装可以让生产系统中的调试更加容易：

package main
import "fmt"

func dbQuery(sql string) error {
    return fmt.Errorf("db.Query(%q): connection refused", sql)
}

func getUserByID(id int) (string, error) {
    if err := dbQuery("SELECT * FROM users WHERE id=?"); err != nil {
        return "", fmt.Errorf("getUserByID(%d): %w", id, err)
    }
    return "Alice", nil
}

func handler() error {
    _, err := getUserByID(1)
    if err != nil {
        return fmt.Errorf("handler: %w", err)
    }
    return nil
}

func main() { fmt.Println(handler()) }

errors.Join — 多重包装（Go 1.20+）

errors.Join 会创建一个包装多个错误的错误。errors.Is 会检查其中的所有错误：

package main
import ("fmt"; "errors")

var ErrA = errors.New("err A")
var ErrB = errors.New("err B")

func main() {
    joined := errors.Join(ErrA, ErrB)
    fmt.Println(joined)
    fmt.Println(errors.Is(joined, ErrA)) // true
    fmt.Println(errors.Is(joined, ErrB)) // true
}

解包最佳实践

错误包装指南：

使用 %w 进行包装，以保留错误供程序检查
添加操作名称作为上下文：fmt.Errorf("funcName: %w", err)
如果调用方不会使用 errors.Is，就不要包装哨兵错误
避免在每一层重复包装相同的上下文
在自定义类型上实现 Unwrap()，使其参与错误链

快速检查

在 fmt.Errorf 中使用 %v 与 %w 有什么区别？

回顾：错误包装与解包

总结：

fmt.Errorf("ctx: %w", err) 使用上下文进行包装
errors.Unwrap 获取错误链中的下一个错误
errors.Is 遍历错误链以进行身份匹配
errors.As 遍历错误链以进行类型匹配
自定义类型实现 Unwrap() error
errors.Join 包装多个错误（Go 1.20+）

常见问题解答

「错误包装与拆包」课时是免费的吗？

是的 — 「错误包装与拆包」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Go Academy 课程的其余内容，请升级到 CoddyKit PRO。 Go Academy 课程共包含 4 节课。

「错误包装与拆包」这节课中我会学到什么？

使用 %w、errors.Is 与 errors.As 你通过在浏览器中直接运行的动手代码来练习 Go Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Go Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Go Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「错误包装与拆包」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Go Academy 课中编写并运行代码吗？

能。每节 Go Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Go Academy