Go / 技术文章
Go 错误包装怎么设计 errors.Is 与 As
导语:后端服务通常需要让底层错误保留可诊断信息,同时让上层根据稳定的错误类别决定返回码、重试策略或业务分支。关键不在于把字符串拼得更完整,而在于构造可遍历的错误链,并明确什么时候用 errors.Is 做类别判断、什么时候用 errors.As 提取具体错误。
先理解错误包装解决什么问题
假设仓储层调用数据库失败,应用层需要补充“创建订单失败”的上下文,但又不能让上层只能比较最终字符串。Go 的错误包装通过 fmt.Errorf 的 %w 保留原错误,使调用方可以沿着错误链继续判断。
package main
import (
"errors"
"fmt"
)
var ErrNotFound = errors.New("not found")
func loadOrder() error {
return fmt.Errorf("load order: %w", ErrNotFound)
}
func main() {
err := loadOrder()
fmt.Println(err)
fmt.Println(errors.Is(err, ErrNotFound))
}预期结果:
load order: not found
true这里的 err.Error() 包含了新的上下文,但 errors.Is(err, ErrNotFound) 仍然能够识别底层哨兵错误。这个关系适合表达“这是什么类别的失败”。
errors.Is 用来判断错误类别
errors.Is 的核心用途是判断错误链中是否存在目标错误。它特别适合稳定的业务或基础设施分类,例如“资源不存在”“权限不足”“超时”等。
不要根据错误字符串判断类别:字符串属于展示信息,容易随着上下文变化而变化。也不要为了传递上下文而丢掉 %w,否则错误链会在中间层被截断。
var (
ErrNotFound = errors.New("not found")
ErrConflict = errors.New("conflict")
)
func save() error {
return fmt.Errorf("save user: %w", ErrConflict)
}
func handle(err error) {
switch {
case errors.Is(err, ErrNotFound):
fmt.Println("return 404")
case errors.Is(err, ErrConflict):
fmt.Println("return 409")
default:
fmt.Println("return 500")
}
}预期结果:
return 409这里上层只依赖稳定分类,而不需要知道错误来自哪个数据库驱动或具体函数。错误上下文可以不断增加,但分类契约保持不变。
errors.As 用来提取具体错误
errors.As 解决的是另一类问题:调用方不仅想知道“是不是某类错误”,还需要取得满足某个类型的错误值,再读取其中结构化字段。
典型场景是底层返回一个具体错误类型,其中包含错误码、临时性标记或其他诊断信息。errors.As 会沿错误链查找能够赋值给目标类型的错误。
package main
import (
"errors"
"fmt"
)
type ValidationError struct {
Field string
Msg string
}
func (e *ValidationError) Error() string {
return e.Field + ": " + e.Msg
}
func createUser() error {
return fmt.Errorf("create user: %w", &ValidationError{
Field: "email",
Msg: "invalid format",
})
}
func main() {
err := createUser()
var ve *ValidationError
if errors.As(err, &ve) {
fmt.Println(ve.Field)
fmt.Println(ve.Msg)
}
}预期结果:
email
invalid format可以把两者记成一句话:Is 问“是不是这种错误”,As 问“它是不是这种类型,并把它取出来”。
错误链应该怎么设计
错误传播通常跨越基础设施层、领域或应用层、接口层。每一层都应有明确职责:底层保留可诊断原因,中间层增加必要上下文,边界层把稳定分类转换成协议响应。
一种常见做法是:
- 基础设施层返回原始错误或定义明确的基础设施错误类型。
- 应用层只在增加上下文时包装,并优先使用
%w。 - 对外暴露的错误类别使用稳定的哨兵错误或自定义错误类型。
- HTTP、RPC 等接口层通过
errors.Is或errors.As做协议映射,而不是解析字符串。
例如数据库层遇到“记录不存在”,应用层可以继续包装:
func findUser() error {
err := queryUser()
if err != nil {
return fmt.Errorf("find user: %w", err)
}
return nil
}
func getProfile() error {
err := findUser()
if err != nil {
return fmt.Errorf("load profile: %w", err)
}
return nil
}
func queryUser() error {
return fmt.Errorf("query users table: %w", ErrNotFound)
}预期结果:
load profile: find user: query users table: not found此时接口层仍可以直接使用 errors.Is(err, ErrNotFound),无需了解中间经过了多少层。
Is 与 As 怎么划分边界
选择标准可以很简单:只有需要读取结构化字段时才使用 As;只是判断错误类别时优先使用 Is。
例如返回 HTTP 状态码时,通常只需要判断分类:
func statusCode(err error) int {
switch {
case errors.Is(err, ErrNotFound):
return 404
case errors.Is(err, ErrConflict):
return 409
default:
return 500
}
}而记录底层特定错误的数据库错误码、网络错误字段时,可以使用 As:
var netErr interface {
Timeout() bool
}
if errors.As(err, &netErr) && netErr.Timeout() {
// 根据结构化信息决定是否重试
}两种方式不要混成字符串协议。字符串适合日志和展示,Is 与 As 才适合作为程序间的错误判断机制。
日志应该记录在哪一层
错误被多层包装后,最容易出现的问题不是信息太少,而是同一错误被每层重复打印。一个请求可能先在数据库层打印一次、应用层再打印一次、HTTP 中间件又打印一次,最终日志里出现多条重复堆栈。
更稳定的做法是:下层返回错误并补充上下文,不因为“看到了错误”就立刻记录;靠近请求边界的统一日志层负责记录一次完整链路。只有某个中间层拥有额外且无法在上层重建的诊断信息时,才单独记录。
同时,日志内容与客户端响应要分开。内部错误链可以保留数据库表、驱动错误和调用上下文,对外响应则只暴露稳定的业务错误类别和安全的提示信息。
最后检查错误包装是否可靠
可以用三个问题快速审查一段错误处理代码:
- 这次包装是为了增加上下文,还是只是重复改写字符串?
- 上层需要判断类别还是读取具体字段?前者通常用
Is,后者通常用As。 - 错误最终是否只在明确的边界记录一次,并由该边界完成协议映射?
只要错误链完整、分类稳定、日志集中,服务就能在不断增加调用层级时继续保留诊断能力,同时避免把数据库驱动细节泄漏到业务判断中。