1. 错误码断言概述

什么是错误码断言

错误码断言（Error Code Assertion）是 Go 语言测试中用于验证函数或方法返回的错误是否包含预期错误码的断言技术。它不同于简单的 err != nil 检查，而是深入到错误的具体类型、包装层级和语义标识，确保被测代码在特定条件下返回了正确的错误类别。

在 Go 1.13 引入的 errors 包机制下，错误码断言通常通过以下方式实现：

• errors.Is：判断错误链中是否包含某个特定的哨兵错误。
• errors.As：判断错误链中是否存在某个类型的错误，并提取该错误实例。
• 自定义断言函数：对业务错误码（如 HTTP 状态码、业务 Code 字段）进行结构化匹配。

// 传统断言：仅检查错误是否存在
if err != nil {
    t.Fatal("expected no error, got:", err)
}

// 错误码断言：验证错误的语义和类别
if !errors.Is(err, ErrNotFound) {
    t.Fatalf("expected ErrNotFound, got: %v", err)
}

// 结构化错误码断言
var bizErr *BusinessError
if errors.As(err, &bizErr) {
    if bizErr.Code != 1001 {
        t.Fatalf("expected business code 1001, got: %d", bizErr.Code)
    }
}

为什么需要错误码断言

在 Go 项目的测试实践中，仅靠 err != nil 进行错误验证存在明显不足。错误码断言解决了以下关键问题：

错误码断言在 Go 测试中的角色

错误码断言在 Go 测试体系中扮演着质量守门员和契约验证者的双重角色。它贯穿单元测试、集成测试和契约测试三个层次：

错误码断言在测试中的具体职责可以归纳为以下四个方面：

1. 验证错误路径的完整性：确保每个错误分支都返回了正确的错误码，避免遗漏或混淆。
2. 保障错误包装的正确性：验证 fmt.Errorf("%w", err) 包装后，原始错误仍能被正确识别。
3. 强化接口契约：通过断言错误码，将 API 文档中的错误约定转化为可执行的测试用例。
4. 提升测试可维护性：基于错误标识符的断言比基于错误字符串的断言更稳定，重构时不易断裂。

错误码断言 vs 传统错误检查

下表从多个维度对比了两种方式的差异，帮助理解错误码断言的价值所在：