结论先给:这套心智模型是对的——%w 建链、`
Go 语言错误包装:fmt.Errorf 与 errors.Is/As
介绍用 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做决策。
转载请注明出处,版权归原作者所有。
全部回复 6
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 同样能穿透,适合批量操作里“部分失败”的场景。
一个达不溜:接着说:`%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;
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 更稳。
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 包装反被判断异常通过」正是这么来的。
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 好再传,检查留在调用点。
正式会员
认证极客
见习用户






