Go 错误处理最佳实践：从 errors.Is 到自定义错误类型

错误处理是 Go 语言中最具争议也最体现工程素养的话题之一。Go 没有异常机制，而是将错误作为值传递，这种设计迫使开发者在每一层调用中都直面错误的可能性。然而，if err != nil 的反复出现也让许多人感到繁琐。问题不在于 Go 的设计，而在于我们是否掌握了正确的错误处理模式。本文将从标准库的 errors.Is 和 errors.As 出发，逐步深入到自定义错误类型的设计，帮助你构建一套清晰、可维护的错误处理体系。

为什么需要 errors.Is 和 errors.As

在 Go 1.13 之前，判断错误类型主要依赖直接比较或类型断言：

if err == io.EOF {
    // 处理文件结束
}

这种方式的问题在于，一旦错误在传递过程中被包装（wrap），直接比较就会失效。比如 fmt.Errorf("read config: %w", err) 返回的是一个新错误，它包含了原始错误，但 err == io.EOF 不再成立。

Go 1.13 引入了 errors.Is 和 errors.As，专门解决这个问题。

errors.Is 用于判断错误链中是否存在某个特定错误：

if errors.Is(err, os.ErrNotExist) {
    // 文件不存在，无论经过多少层包装都能识别
}

errors.As 用于从错误链中提取特定类型的错误：

var pathErr *os.PathError
if errors.As(err, &pathErr) {
    fmt.Println("操作:", pathErr.Op, "路径:", pathErr.Path)
}

两者的核心区别在于：errors.Is 关心的是“是不是这个错误”，errors.As 关心的是“能不能变成这个类型”。理解这一点，是正确使用它们的前提。

错误包装的正确姿势

Go 1.13 同时引入了 %w 动词，让 fmt.Errorf 可以包装错误：

func LoadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("load config %s: %w", path, err)
    }
    // ...
}

包装的好处是保留了完整的错误链，调用方既能看到上下文信息，又能通过 errors.Is/errors.As 追溯到根因。

但包装也有代价：每一层包装都会增加错误信息的长度，过度包装会让日志变得冗长且难以阅读。一个实用的原则是：在跨越抽象边界时包装错误，在同一抽象层内直接返回。比如 repository 层调用数据库驱动时包装一次，service 层调用 repository 时再包装一次，这样就足够了。

另外需要注意的是，%w 只能包装一个错误。如果需要同时包装多个错误，可以使用 errors.Join（Go 1.20 引入）：

err := errors.Join(err1, err2)

何时定义自定义错误类型

标准库的错误类型（如 os.PathError、net.OpError）已经覆盖了很多场景，但在业务代码中，我们经常需要表达更丰富的语义。这时就需要自定义错误类型。

一个典型的场景是：调用方需要根据错误类型做出不同的决策。比如一个用户注册接口，可能返回“邮箱已存在”“用户名已存在”“密码强度不足”等不同错误，每种错误对应不同的 HTTP 状态码或前端提示。

type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
}

使用指针接收者实现 error 接口是一个重要细节。因为 errors.As 需要一个指向错误类型的指针，如果 Error() 方法定义在值接收者上，errors.As 的行为会变得微妙。统一使用指针接收者可以避免这类困惑。

调用方可以这样使用：

var valErr *ValidationError
if errors.As(err, &valErr) {
    // 根据 valErr.Field 返回具体的错误提示
}

哨兵错误 vs 自定义类型

Go 社区中有一个经典争论：应该使用哨兵错误（sentinel error，即包级别的 var ErrXxx = errors.New(...)）还是自定义错误类型？

哨兵错误适合表达“一种状态”，比如 io.EOF、sql.ErrNoRows。它们的优点是简单、易于比较，缺点是携带的信息有限，且一旦导出就成为公共 API 的一部分，难以修改。

自定义错误类型适合表达“一类问题”，可以携带结构化数据。缺点是定义成本较高，且调用方需要了解类型的结构。

一个实用的判断标准是：如果调用方只需要知道“发生了什么”，用哨兵错误；如果调用方还需要知道“具体细节”，用自定义类型。两者也可以结合使用，比如定义一个哨兵错误作为 Is 方法的目标：

var ErrNotFound = errors.New("not found")

type NotFoundError struct {
    Resource string
    ID       string
}

func (e *NotFoundError) Error() string {
    return fmt.Sprintf("%s %s not found", e.Resource, e.ID)
}

func (e *NotFoundError) Is(target error) bool {
    return target == ErrNotFound
}

这样调用方既可以用 errors.Is(err, ErrNotFound) 做粗粒度判断，也可以用 errors.As 提取详细信息。

错误处理的工程化建议

最后，分享几条在实践中总结的建议：

第一，错误信息使用小写字母开头，不加标点结尾。 因为错误通常会被包装到更大的上下文中，fmt.Errorf("load config: %w", err) 中的前缀应该像句子的一部分，而不是独立句子。

第二，在程序边界处记录日志，而不是在每一层。 如果每一层都 log.Printf，同一个错误会被打印多次。正确的做法是在最外层（如 HTTP handler 或 main 函数）统一记录，中间层只负责包装和传递。

第三，不要忽略错误，也不要无意义地 panic。 _ = doSomething() 应该只用在确实无关紧要的场景，并且最好加上注释说明原因。panic 只应该用于程序无法继续运行的场景，比如初始化失败。

第四，为错误定义行为，而不是让调用方猜测。 通过导出哨兵错误或提供 IsXxx(err error) bool 辅助函数，让调用方能够以稳定的方式判断错误，而不是依赖字符串匹配。

结语

Go 的错误处理哲学是“错误是值”，这既是约束也是自由。约束在于你必须显式处理每一个错误，自由在于你可以像操作任何值一样操作错误——包装它、比较它、提取它、分类它。掌握 errors.Is、errors.As、%w 包装和自定义错误类型这四个工具，你就能在保持代码清晰的同时，构建出健壮的错误处理体系。记住，好的错误处理不是让错误消失，而是让错误在正确的地方以正确的方式被理解和响应。

未经允许不得转载：任鹏个人博客 » Go 错误处理最佳实践：从 errors.Is 到自定义错误类型