Go / 技术文章

Go 错误包装怎么设计 errors.Is 与 As

导语:后端服务通常需要让底层错误保留可诊断信息,同时让上层根据稳定的错误类别决定返回码、重试策略或业务分支。关键不在于把字符串拼得更完整,而在于构造可遍历的错误链,并明确什么时候用 errors.Is 做类别判断、什么时候用 errors.As 提取具体错误。

先理解错误包装解决什么问题

假设仓储层调用数据库失败,应用层需要补充“创建订单失败”的上下文,但又不能让上层只能比较最终字符串。Go 的错误包装通过 fmt.Errorf 的 %w 保留原错误,使调用方可以沿着错误链继续判断。

go
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))
}

预期结果:

text
load order: not found
true

这里的 err.Error() 包含了新的上下文,但 errors.Is(err, ErrNotFound) 仍然能够识别底层哨兵错误。这个关系适合表达“这是什么类别的失败”。

errors.Is 用来判断错误类别

errors.Is 的核心用途是判断错误链中是否存在目标错误。它特别适合稳定的业务或基础设施分类,例如“资源不存在”“权限不足”“超时”等。

不要根据错误字符串判断类别:字符串属于展示信息,容易随着上下文变化而变化。也不要为了传递上下文而丢掉 %w,否则错误链会在中间层被截断。

go
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")
    }
}

预期结果:

text
return 409

这里上层只依赖稳定分类,而不需要知道错误来自哪个数据库驱动或具体函数。错误上下文可以不断增加,但分类契约保持不变。

errors.As 用来提取具体错误

errors.As 解决的是另一类问题:调用方不仅想知道“是不是某类错误”,还需要取得满足某个类型的错误值,再读取其中结构化字段。

典型场景是底层返回一个具体错误类型,其中包含错误码、临时性标记或其他诊断信息。errors.As 会沿错误链查找能够赋值给目标类型的错误。

go
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)
    }
}

预期结果:

text
email
invalid format

可以把两者记成一句话:Is 问“是不是这种错误”,As 问“它是不是这种类型,并把它取出来”。

错误链应该怎么设计

错误传播通常跨越基础设施层、领域或应用层、接口层。每一层都应有明确职责:底层保留可诊断原因,中间层增加必要上下文,边界层把稳定分类转换成协议响应。

一种常见做法是:

  • 基础设施层返回原始错误或定义明确的基础设施错误类型。
  • 应用层只在增加上下文时包装,并优先使用 %w。
  • 对外暴露的错误类别使用稳定的哨兵错误或自定义错误类型。
  • HTTP、RPC 等接口层通过 errors.Is 或 errors.As 做协议映射,而不是解析字符串。

例如数据库层遇到“记录不存在”,应用层可以继续包装:

go
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)
}

预期结果:

text
load profile: find user: query users table: not found

此时接口层仍可以直接使用 errors.Is(err, ErrNotFound),无需了解中间经过了多少层。

Is 与 As 怎么划分边界

选择标准可以很简单:只有需要读取结构化字段时才使用 As;只是判断错误类别时优先使用 Is。

例如返回 HTTP 状态码时,通常只需要判断分类:

go
func statusCode(err error) int {
    switch {
    case errors.Is(err, ErrNotFound):
        return 404
    case errors.Is(err, ErrConflict):
        return 409
    default:
        return 500
    }
}

而记录底层特定错误的数据库错误码、网络错误字段时,可以使用 As:

go
var netErr interface {
    Timeout() bool
}

if errors.As(err, &netErr) && netErr.Timeout() {
    // 根据结构化信息决定是否重试
}

两种方式不要混成字符串协议。字符串适合日志和展示,Is 与 As 才适合作为程序间的错误判断机制。

日志应该记录在哪一层

错误被多层包装后,最容易出现的问题不是信息太少,而是同一错误被每层重复打印。一个请求可能先在数据库层打印一次、应用层再打印一次、HTTP 中间件又打印一次,最终日志里出现多条重复堆栈。

更稳定的做法是:下层返回错误并补充上下文,不因为“看到了错误”就立刻记录;靠近请求边界的统一日志层负责记录一次完整链路。只有某个中间层拥有额外且无法在上层重建的诊断信息时,才单独记录。

同时,日志内容与客户端响应要分开。内部错误链可以保留数据库表、驱动错误和调用上下文,对外响应则只暴露稳定的业务错误类别和安全的提示信息。

最后检查错误包装是否可靠

可以用三个问题快速审查一段错误处理代码:

  1. 这次包装是为了增加上下文,还是只是重复改写字符串?
  2. 上层需要判断类别还是读取具体字段?前者通常用 Is,后者通常用 As。
  3. 错误最终是否只在明确的边界记录一次,并由该边界完成协议映射?

只要错误链完整、分类稳定、日志集中,服务就能在不断增加调用层级时继续保留诊断能力,同时避免把数据库驱动细节泄漏到业务判断中。

目录与阅读设置

记录一个想法

Go 错误包装怎么设计 errors.Is 与 As

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通