Go 错误处理规范：errors.Is、errors.As 与包装链

Go 错误处理的现代规范只有三条：包装用 %w、判定用 errors.Is、取类型用 errors.As，其余写法（== 比较、strings.Contains(err.Error(), ...)、%v 包装）在 Go 1.13 之后都属于要淘汰的旧习惯。结论：只要你的错误需要跨函数、跨层传递并被上层识别，就必须走"包装链 + Is/As"这一套。

一、先定义可识别的错误：哨兵值或自定义类型

结论：能被 errors.Is 识别的错误，必须在包级别用 var 声明哨兵值，能被 errors.As 提取的信息，必须封装成实现了 error 的结构体。

// 哨兵错误：只表达"哪一类失败"
var (
    ErrNotFound = errors.New("not found")
    ErrConflict = errors.New("conflict")
)

// 自定义类型：需要携带字段（SQL、记录 ID、重试次数）时用
type QueryError struct {
    SQL string
    Err error
}
func (e *QueryError) Error() string { return "query failed: " + e.Err.Error() }
func (e *QueryError) Unwrap() error { return e.Err }   // 关键：暴露下层错误

注意 Unwrap() 是包装链的接口。没有它，errors.Is/As 走到这一层就断了，链上更内层的错误永远查不到。

二、包装：%w 是链，%v 是断链

结论：fmt.Errorf 只有用 %w 才会建立包装链，用 %v/%s 只是把错误文本拼进消息，上层再也无法识别原始错误。

// 正确：保留链，附带上下文
return fmt.Errorf("load user %d: %w", id, err)

// 错误：链断了，errors.Is(err, ErrNotFound) 会返回 false
return fmt.Errorf("load user %d: %v", id, err)

这是最常见的隐性 bug：日志里错误信息看着"信息很全"，但调用方的 errors.Is 全部失效。一个实用判据——**如果你希望上层能判定它，就 %w；如果你刻意不想暴露内部错误类型（例如防止调用方依赖实现细节），才用 %v 主动断链。** 断链应该是设计决策，不是疏忽。

Go 1.20 起 fmt.Errorf 支持多个 %w，但常规工程规范仍建议一条链只包一个 %w，需要聚合多个错误时用 errors.Join。

三、判定：errors.Is 沿链递归比较

结论：判断"是不是某类错误"一律用 errors.Is(err, ErrXxx)，它会沿 Unwrap 链逐层比较，并且支持被比较方自定义 Is 方法。

if errors.Is(err, ErrNotFound) {
    return c.JSON(404, nil)
}

它比 == 强在两点：一是自动穿透包装链，二是比较目标是自定义类型时可以定义等价语义：

func (e *QueryError) Is(target error) bool {
    t, ok := target.(*QueryError)
    return ok && t.SQL == e.SQL
}

坑点提醒：errors.Is(nil, nil) 返回 true，errors.Is(nil, ErrNotFound) 返回 false。所以永远先 if err != nil 再判定，别把判空逻辑混进 Is。

四、取类型：errors.As 沿链找第一个匹配类型

结论：当你需要取出错误里的字段（而不是只判类别）时用 errors.As，第二个参数必须是指向目标变量（或接口）的指针。

var qe *QueryError
if errors.As(err, &qe) {
    log.Printf("failed sql: %s", qe.SQL)
}

规范要点：目标变量声明为指针类型 var qe *QueryError，传 &qe；如果写成 errors.As(err, qe)（没取地址）会直接 panic。想提取接口时同理，var pe interface{ Timeout() bool } 然后 errors.As(err, &pe)，这是 net.Error 之外的通用写法。另外 As 命中的是链上第一个匹配类型，所以包装层不要重复包裹同类型错误。

五、分层规范：中间层只包装，边界层只记录一次

结论：日志只在请求边界（handler / main）打一次，中间层一律只做 %w 包装，否则同一次失败会在日志里出现十几条。

推荐分工：仓储层返回哨兵错误或领域类型；服务层用 %w 补业务上下文（"load user 42"）；handler 层集中判定并映射响应：

switch {
case errors.Is(err, ErrNotFound):
    return 404
case errors.Is(err, ErrConflict):
    return 409
default:
    log.Printf("unhandled: %+v", err)  // 全链路文本在这里一次性落盘
    return 500
}

如果用了 github.com/pkg/errors 的 %+v 打印堆栈，建议把这种打印也收敛到这一处，别散落在各层。

六、必须避开的四个坑

结论：这四个错误占了 Go 错误处理线上事故的绝大多数。

一是用 == 比较错误——只要中间有一次 %w 包装就会失效，改用 errors.Is。二是字符串匹配 strings.Contains(err.Error(), "not found")——文案一改、国际化一上就崩，且无法区分同文案不同语义。三是 As 的 target 不是指针导致 panic，code review 时重点看这一行。四是自定义错误忘了实现 Unwrap()，导致内层哨兵错误不可见。

另外 Go 1.20 的 errors.Join(err1, err2) 适合"多处失败都要上报"的场景（如批量校验），它同时实现了 Unwrap() []error，Is/As 同样能穿透，但别拿它替代单链包装。

一句话收尾：在包级别定义哨兵值和错误类型，跨层传递时用 %w 保持链完整，判定统一走 errors.Is，取字段统一走 errors.As，日志只在边界打一次——严格执行这五条，错误处理就不会再是靠字符串猜谜的体力活。