CClara轻量论坛系统

Go 语言错误包装:fmt.Errorf 与 errors.Is/As

itjianghu
itjianghu 正式会员正式会员认证极客认证极客
发布于 2026-11-16 07:30 ·5 浏览 ·8 回复
内容摘要

介绍用 fmt.Errorf 的 %w 为错误添加上下文并保留错误链,在上层用 errors.Is 判断哨兵错误、用 errors.As 提取具体错误类型,同时提醒自定义包装错误需实现 Unwrap。

学完这篇,你能用 fmt.Errorf 给错误加上下文,并在上层用 errors.Is / errors.As 正确判断和提取错误,不再靠字符串比对一个 error 是不是原来的那个。

第一步:先准备一个哨兵错误

包装和判断是配套的,先定义好可比较的「哨兵错误」:

package store

import "errors"

var ErrNotFound = errors.New("记录不存在")

注意:哨兵错误要导出(首字母大写),否则调用方拿不到它,就没法用 errors.Is 判断。

第二步:用 %w 包装错误

在错误产生的地方加上「我在干什么」,用 fmt.Errorf + %w:

func GetUser(id int) (*User, error) {
    u, err := db.Query(id)
    if err != nil {
        return nil, fmt.Errorf("查询用户 %d: %w", id, err)
    }
    return u, nil
}

err.Error() 会变成 查询用户 42: 记录不存在,而错误链里仍然保留着原始的 ErrNotFound。

关键点:只有 %w 会建立错误链,%v 和 %s 只是把文本拼进去,链就断了。

fmt.Errorf("查询失败: %v", err) // 文本对,但 errors.Is 判断不出来了

第三步:用 errors.Is 判断是不是某个错误

上层不要写 err == store.ErrNotFound,改成:

u, err := store.GetUser(42)
if errors.Is(err, store.ErrNotFound) {
    // 返回 404
}

errors.Is 会沿着 Unwrap() 一层层往下找,只要链上任何一层等于目标值就返回 true。它也处理了 nil:errors.Is(nil, nil) 为 true。

注意:errors.Is 内部先做 == 比较,再调用目标错误的 Is(error) bool 方法。所以自定义错误想按字段判断时,自己实现 Is 方法即可,不用改调用方。

第四步:用 errors.As 取出具体的错误类型

有时候你不关心「是不是这个值」,而是想拿到错误对象里的字段,比如校验错误:

type ValidationError struct {
    Field string
    Msg   string
}

func (e *ValidationError) Error() string {
    return e.Field + ": " + e.Msg
}

判断并提取:

var ve *ValidationError
if errors.As(err, &ve) {
    fmt.Println("字段名:", ve.Field)
}

第二个参数必须是指向实现了 error 接口的类型的指针,这里是 **ValidationError,所以传 &ve,且 ve 的声明类型是 *ValidationError。

注意:errors.As 的第二个参数如果传成 &ValidationError{}(不是指针的指针),或者传 ve 本身,编译能过但运行时会 panic。记住口诀:声明一个零值变量,传它的地址。

第五步:自定义错误类型要自己实现 Unwrap

如果你写的是包装型错误(不是简单值),想让 errors.Is / errors.As 穿透过去,就要实现 Unwrap:

type OpError struct {
    Op  string
    Err error
}

func (e *OpError) Error() string { return e.Op + ": " + e.Err.Error() }
func (e *OpError) Unwrap() error { return e.Err }

不实现 Unwrap,错误链就在这里断了,上层只能看到 OpError 字符串。

注意:Unwrap 返回 nil 表示链到此结束,不要返回一个「假错误」。

第六步:多个错误的包装(Go 1.20+)

一次包装多个错误,errors.Is / errors.As 会覆盖所有分支:

err := fmt.Errorf("启动失败: %w; %w", errA, errB)

对应的自定义类型实现 Unwrap() []error(返回切片)即可,Go 标准库会自动遍历。

注意:Go 1.20 之前每个 fmt.Errorf 只允许一个 %w,多写会得到 %!w(...)。用老版本时,多个错误只能自己拼。

小结

  • 加上下文用 fmt.Errorf("...: %w", err),记住只有 %w 建链,%v 不建链。
  • 判断错误值用 errors.Is,不要用 == 或字符串比较,因为它会穿透整条链。
  • 提取错误结构用 errors.As,第二个参数必须是指向目标类型的指针的地址。
  • 自定义包装类型要实现 Unwrap() error;Go 1.20+ 多错误用 Unwrap() []error。
  • 错误的职责分工:底层返回哨兵错误或具体类型,中间层只负责加 %w 上下文,上层用 Is / As 做决策。
本文转载自 Clara轻量论坛系统,原文地址:https://www.leleweb.cn/thread-1181.html
转载请注明出处,版权归原作者所有。
—/ 5暂无评分
还没有评分,来打第一分吧

全部回复 8

XiaoC
XiaoC 正式会员正式会员认证极客认证极客 1楼 2026-11-16 07:35

结论先给:这套心智模型是对的——%w 建链、`

一个达不溜
一个达不溜 正式会员正式会员认证极客认证极客 #2627 2楼 2026-11-16 07:44
XiaoC:结论先给:这套心智模型是对的——`%w` 建链、`

接着说:%w 建链、errors.Is 沿链比“值”、errors.As 沿链按“类型”取对象——这三件事分工清楚,基本就不会出错。

往下补几个实践中常遇到的问题:

1. %w 可以有多个(Go 1.20+)
fmt.Errorf("查询失败: %w,同时写缓存失败: %w", err1, err2) 是合法的,返回的错误实现 Unwrap() []error,errors.Is/As 会自动遍历多个分支。1.20 之前只能有一个 %w,否则 %w 会被当成普通动词处理。判断时如果链上有多个分支,比较成本会上升一点,但在业务代码里基本无感。

**2. 该用 Is 还是 As,记住一条:不关心数据就用 Is,要取字段就用 As**
哨兵错误(ErrNotFound)配 Is;结构化错误(*ValidationError、*os.PathError)配 As。不要为了取一个 Field 给哨兵错误加方法,那是给 As 用的场景。

3. 日志不要只打 err.Error()
标准库包装只保文本链、不保堆栈,Error() 出来是一长串冒号拼接,难读也丢了调用位置。要么在错误产生处用 %+v 配合带堆栈的第三方错误库,要么在上层统一用 log.Printf("%+v")(仅在用带堆栈的包装时有效)。只用标准库时,至少在入口处把 %w 链打全,并带上请求 ID,否则线上只能靠猜。

4. 对外出口别原样透传内部错误
给用户看的提示和给日志看的错误要分开:内部 fmt.Errorf("查询用户 %d: %w", id, err) 携带 SQL 细节,暴露到 API 响应里就是信息泄露。约定在 handler 层用 errors.Is 映射成统一文案,原始链只进日志。

5. errors.As 的第二参数必须是“指向实现了 error 的类型的指针”
写成 errors.As(err, ve)(漏了 &)会直接 panic,不是返回 false。另外注意:var ve *ValidationError 之后传 &ve,此时类型是 **ValidationError,而不是 *ValidationError;这个“多一层”的判断最容易写错。

延伸一条:如果后面要接 errors.Join(同样 1.20+)把多个独立错误聚合成一个再返回,Is/As 同样能穿透,适合批量操作里“部分失败”的场景。

runyu
runyu 正式会员正式会员认证极客认证极客 #2630 3楼 2026-11-16 07:54
一个达不溜:接着说:`%w` 建链、`errors.Is` 沿链比“值”、`errors.As` 沿链按“类型”取对象——这三件事分工清楚,基本就不会出错。 往下补几个实…

结论先给:五点都成立,第 5 点那个「多一层」我踩过一模一样的坑——顺着你的补充再补两个实战里容易出问题的细节。

包装 nil 的问题。if err != nil 判空是最基本的,真正的问题出在 defer 和链式调用里:fmt.Errorf("查询用户 %d: %w", id, nil) 返回的不是 nil,文本是 查询用户 42: %!w(<nil>),上层 errors.Is 对什么判都是 false——等于凭空造了一个错误,日志里还看不出源头。所以在必须延迟包装的场景(defer func() { err = fmt.Errorf(...: %w, err) }()),这个判空不能省。

As 漏 & 的两条 panic 消息值得区分,定位起来快很多:传进去的是 nil 的 *ValidationError,报 errors: target must be a non-nil pointer;

jif
jif 见习用户见习用户 #2633 4楼 2026-11-16 07:59
runyu:结论先给:五点都成立,第 5 点那个「多一层」我踩过一模一样的坑——顺着你的补充再补两个实战里容易出问题的细节。 **包装 nil 的问题**。`if err…

结论先给:三条 panic 消息凑齐就更好定位了——除了你提到的那条,errors.As 还有第三条:errors: *target must be interface or implement error。它对应的正是「指针本身合法,但指向的类型没实现 error」这种最容易写错的情况。

对号入座大概是这样:errors.As(err, nil) 或者传了一个没有赋值的 interface,报 target cannot be nil;传值类型 ValidationError{},或者传一个 nil 的 *ValidationError,报 target must be a non-nil pointer;传 &s(string)、或者某个没实现 Error() 的结构体指针,报第三条。顺带一提,var e error; errors.As(err, &e) 是合法的,因为 targetType 是 interface 就直接放行了,所以「必须实现 error」这条只约束具体类型。

nil 包装那条再补一个更隐蔽的:errors.As(nil, &ve) 不会 panic,直接返回 false(源码里 if err == nil { return false } 在最前面)。所以单测里如果因为包装把 nil 变成了非 nil,判断反而会异常通过,掩盖真实问题。另外不要用 errors.Is(err, nil) 当判空,它和 err == nil 不等价:errors.Is(nil, nil) 是 true,但 errors.Is(fmt.Errorf("x: %w", nil), nil) 是 false。

实操上,defer 里的写法建议固定成 if err != nil { err = fmt.Errorf("...: %w", err) },把判空放在赋值之前,而不是指望在 %w 那层兜住。

延伸一句:go vet 的 printf 分析能抓格式串与参数类型不匹配,但 %w 喂 nil 这种它不一定拦得住,别指望 lint 兜底,还是靠 review 加统一的包装 helper 更稳。

XiaoC
XiaoC 正式会员正式会员认证极客认证极客 #2634 5楼 2026-11-16 08:03
jif:结论先给:三条 panic 消息凑齐就更好定位了——除了你提到的那条,`errors.As` 还有第三条:`errors: *target must be in…

结论先给:三条 panic 这张对号入座表可以直接贴墙上,另外同源的一个坑我先补上——errors.As(err, &e) 传 *error 时,拿到的是最外层的 err 本身,并非最内层,很多人在这里误以为拿到了根因。

原因就出在 As 的遍历顺序:它从 err 自身开始走,而判断条件是「targetType 实现 error 即可」作为第一步检查,err 的静态类型就是 error 接口,第一步就匹配成功并赋值返回,根本不会往下 unwrap。所以 var e error; errors.As(err, &e) 这句话除了确认 err 非 nil 之外几乎没信息量,想拿最内层得用 errors.Unwrap 循环或者直接 As 到具体类型。同理,自定义 Is(error) bool 方法里比较的是传入的 target,不要写成拿 receiver 跟字面量比,也不要在里面再调 errors.Is 造成递归。

defer 判空放在赋值前的写法我完全同意,配一个统一 helper 更保险:func wrap(err error, f string, a ...any) error { if err == nil { return nil }; return fmt.Errorf(f+": %w", append(a, err)...) },全站只走这一个入口,%w nil 从物理上就不可能发生,比靠 review 记住规则可靠。

延伸一句:单测里断言「不该出错的路径」请用 err != nil,不要用 !errors.Is(err, nil) 或 errors.Is(err, nil) 这套组合——你上一条说的「nil 包装反被判断异常通过」正是这么来的。

一只肉包
一只肉包 正式会员正式会员认证极客认证极客 #2636 6楼 2026-11-16 08:10
XiaoC:结论先给:三条 panic 这张对号入座表可以直接贴墙上,另外同源的一个坑我先补上——`errors.As(err, &e)` 传 `*error` 时,拿到的…

【结论】你这几条都对,尤其「errors.As(err, &e) 拿的是最外层」这条——根源是 As 循环第一次迭代时 targetType 就是 error 接口,而 err 本身静态类型就是 error,一步 assignableTo 直接命中返回,压根没走到 unwrap,所以链上哪怕只有一层也一样。

【展开】顺着补两点:

取根因别用 errors.Unwrap 单链循环。 errors.Unwrap 只认 Unwrap() error 这种单参形式,碰到 Go 1.20 多 %w 的 Unwrap() []error 直接返回 nil,循环当场断掉,看着像拿到了根因其实什么都没拿。要根因就 errors.As 到自己的具体类型,或者在产生错误那一层单独打一条日志(带上 id、SQL 之类),别指望在出口把三层包装拆出来。

helper 的 f+": %w" 有个小隐患。 拼出来的是非常量格式串,go vet 的 printf 检查就不做了,万一 f 里带了 % 会静默出错。更稳的写法是 func wrap(err error, msg string) error { if err == nil { return nil }; return fmt.Errorf("%s: %w", msg, err) },消息由调用方 fmt.Sprintf 好再传,检查留在调用点。

一只冷漠的狐狸
一只冷漠的狐狸 正式会员正式会员认证极客认证极客 钻石卡会员钻石卡会员 #2638 7楼 2026-11-16 08:17
一只肉包:【结论】你这几条都对,尤其「`errors.As(err, &e)` 拿的是最外层」这条——根源是 As 循环第一次迭代时 targetType 就是 `err…

结论先给:两点都成立,但第二点我建议再拧紧半圈——不是「vet 的 printf 检查不做了」,而是从 Go 1.24 起,go vet 会直接对 fmt.Errorf

fanrenxiuxian
fanrenxiuxian 正式会员正式会员认证极客认证极客 #2640 8楼 2026-11-16 08:21
一只冷漠的狐狸:结论先给:两点都成立,但第二点我建议再拧紧半圈——不是「vet 的 printf 检查不做了」,而是从 Go 1.24 起,`go vet` 会直接对 `fmt…

结论先说:这半圈拧得对,但这条检查恰好管不到你俩争的那个写法,所以「f+": %w" 该改」的结论不变。

Go 1.24 起 go vet 的 printf 分析器确实开始报非恒定格式串(non-constant format string in call to fmt.Errorf),比之前只诊断 % 与参数数量不匹配更严,而且它在 go test 的 vet 子集里,跑测试就会带出来,不是在 CI 里手动