在Go语言里，错误处理一直是非常核心的话题。从Go 1.13开始，标准库新增了errors.Is和errors.As两个函数，专门用来处理被包装过的错误链。以往我们判断错误往往用等号比较或者类型断言，但在错误被一层层包装之后，这两种方式都会失效。理解这两个函数的机制，是写出健壮Go服务的基础。
错误包装与错误链基础
在Go 1.13之前，开发者如果想在底层错误上附加信息，通常会用fmt.Errorf拼接字符串，例如fmt.Errorf("read file failed: %v", err)。这种做法虽然保留了信息，但原始错误类型丢失了，调用方无法再用类型断言还原它。Go 1.13在fmt.Errorf中引入了%w动词，它返回一个实现了Unwrap方法的包装错误，从而构成一条错误链。
任何被%w包装的错误，都可以通过Unwrap一层层剥开，直到找到最底层的根因。标准库的error接口本身只有一个Error() string方法，而包装机制依赖于可选的Unwrap() error方法。只要某个错误类型实现了Unwrap，errors.Is和errors.As就能顺着这条链向下寻找目标。这种设计让错误既携带上下文，又不丢失原始类型。
package main
import (
"errors"
"fmt"
)
var ErrNotFound = errors.New("not found")
func readConfig() error {
return fmt.Errorf("load config: %w", ErrNotFound)
}
func main() {
err := readConfig()
fmt.Println(err) // load config: not found
// 此时 err 已不是 ErrNotFound 本身，而是包装了它的错误
}
errors.Is的使用方式与原理
errors.Is(err, target)用于判断错误链中是否存在与target相等的错误。它不仅仅比较最外层，而是会不断调用Unwrap，把链上每一个错误都和target做比较。比较规则是：如果错误本身等于target，或者错误实现了Is方法并自行判定为true，就返回true。这让我们可以安全地判断根因，而不必关心中间被包装了多少层。
与直接使用err == target相比，errors.Is明显更可靠。例如上面的readConfig返回的是包装错误，直接用等号比较必然为false，但errors.Is能正确识别链上的ErrNotFound。下面代码演示了正确用法以及错误用法的区别。
package main
import (
"errors"
"fmt"
)
var ErrNotFound = errors.New("not found")
func readConfig() error {
return fmt.Errorf("load config: %w", ErrNotFound)
}
func main() {
err := readConfig()
// 错误方式：直接比较
if err == ErrNotFound {
fmt.Println("equal compare: matched")
} else {
fmt.Println("equal compare: not matched")
}
// 正确方式：使用 errors.Is
if errors.Is(err, ErrNotFound) {
fmt.Println("errors.Is: matched")
} else {
fmt.Println("errors.Is: not matched")
}
}
在某些场景下，我们还会自定义错误类型并重写Is方法，以实现更灵活的判断逻辑。比如根据错误码而非指针地址来匹配。不过绝大多数业务代码直接用errors.New创建的哨兵错误配合errors.Is已经足够。
errors.As的类型提取实践
errors.As(err, target)的作用是把错误链中第一个能匹配目标类型的错误，赋值给target指向的变量。它常用于提取带有结构化字段的自定义错误，例如需要从错误里拿到错误码或重试次数。和类型断言不同，errors.As会沿着错误链寻找，而不要求最外层就是该类型。
使用errors.As时必须传入一个指向具体错误类型的指针，例如var e *MyError; errors.As(err, &e)。如果链上找到了对应类型，函数返回true且e被填充；否则返回false。下面示例定义了一个携带Code字段的错误，并展示如何通过errors.As提取它。
package main
import (
"errors"
"fmt"
)
type MyError struct {
Code int
Message string
}
func (e *MyError) Error() string {
return fmt.Sprintf("code %d: %s", e.Code, e.Message)
}
func doTask() error {
base := &MyError{Code: 500, Message: "internal"}
return fmt.Errorf("task failed: %w", base)
}
func main() {
err := doTask()
var me *MyError
if errors.As(err, &me) {
fmt.Printf("extracted code: %d, msg: %sn", me.Code, me.Message)
} else {
fmt.Println("not a MyError")
}
}
如果误用errors.As，例如传入非指针或者类型不匹配，编译期就可能报错，或者运行时永远返回false。因此务必保证target是对应错误类型的指针变量。相比直接用if e, ok := err.(*MyError); ok这种断言，errors.As能穿透包装层，是更推荐的做法。
二者差异与常见误区
很多初学者会混淆errors.Is和errors.As：前者回答的是“错误链里有没有这个值”，后者回答的是“错误链里有没有这种类型并把它交给我”。简单说，Is用于哨兵错误比对，As用于自定义错误提取。它们都依赖Unwrap，如果中间某一层错误没有正确实现Unwrap，链条就会断裂。
一个常见误区是在使用%w时混用%v，导致包装失效。只有%w才会建立Unwrap关系，用%v只是把错误转成字符串，链就断了。另外，不要把errors.As的target设成接口类型去匹配具体结构体，应当用具体类型的指针，否则无法正确赋值。
| 对比项 | errors.Is | errors.As |
|---|---|---|
| 主要目的 | 判断错误值是否存在于链中 | 提取链中特定类型的错误 |
| 目标参数 | 错误值（如哨兵错误） | 错误类型指针 |
| 典型场景 | 判断是否为ErrNotFound | 获取自定义错误字段 |
综合示例：在HTTP服务中处理错误链
假设我们有一个业务函数返回包装错误，在HTTP中间件里需要根据根因决定返回状态码。结合errors.Is和errors.As，可以写出清晰且不易出错的判断逻辑。下面例子展示了从数据层到接口层的完整错误传递与处理。
package main
import (
"errors"
"fmt"
)
var ErrUserNotFound = errors.New("user not found")
type BizError struct {
Code int
Tip string
}
func (b *BizError) Error() string {
return fmt.Sprintf("biz %d: %s", b.Code, b.Tip)
}
func repo() error {
return fmt.Errorf("query db: %w", ErrUserNotFound)
}
func service() error {
return fmt.Errorf("call repo: %w", repo())
}
func handler() {
err := service()
if errors.Is(err, ErrUserNotFound) {
fmt.Println("http 404: user not found")
return
}
var be *BizError
if errors.As(err, &be) {
fmt.Printf("http 400: biz code %dn", be.Code)
return
}
fmt.Println("http 500: unknown error")
}
func main() {
handler()
}
通过上述代码可以看到，无论错误被包装多少层，errors.Is都能稳定识别哨兵错误，而errors.As则能在需要时提取结构化错误。实际项目中建议统一在底层定义哨兵错误和自定义错误类型，上层只使用这两个函数判断，避免散落各处的字符串比较。
小结与编码建议
在Go错误处理中，优先使用fmt.Errorf的%w来包装错误，保留链信息。判断特定错误值用errors.Is，提取结构化错误用errors.As，不要用等号或类型断言替代。自定义错误若需特殊匹配逻辑，可实现Is或As方法，但多数情况标准行为已够用。掌握这两个函数，能显著提升Go代码的错误可追溯性与维护性。
errors.Aserrors.Iserror_wrapping修改时间：2026-08-06 22:10:42