4. 错误码断言基础：使用 errors.Is 进行值断言、使用 errors.As 进行类型断言、断言失败时的处理策略

在 Go 语言中，错误处理不仅仅是检查 err != nil。当错误在调用栈中被多次包装（wrapping）后，原始的错误值和类型信息被层层包裹。为了从包装链中准确提取特定错误或特定错误类型，Go 1.13 引入了两个核心断言函数：errors.Is 和 errors.As。本章将深入剖析这两个函数的语义、使用场景以及断言失败后的标准处理策略。

4.1 错误包装与断言需求

现代 Go 工程中，通过 fmt.Errorf("context: %w", err) 或第三方库对错误进行包装已成为标准实践。包装后的错误形成了一个链表结构。直接使用 == 或类型断言只能匹配最外层的错误，无法穿透包装层。因此，我们需要一种能够遍历整个错误链的断言机制。

4.2 使用 errors.Is 进行值断言

errors.Is(err, target) 用于判断错误链中是否存在与 target 相等的错误值。它比较的是错误的值（value），通常用于检查预定义的哨兵错误（sentinel errors）。

4.2.1 基本用法与哨兵错误匹配

var ErrNotFound = errors.New("record not found")
var ErrPermissionDenied = errors.New("permission denied")

func queryData(id int) error {
    // 模拟不同错误场景
    if id < 0 {
        return fmt.Errorf("query failed: %w", ErrNotFound)
    }
    if id == 0 {
        return fmt.Errorf("access error: %w", ErrPermissionDenied)
    }
    return nil
}

func main() {
    err := queryData(-1)
    if errors.Is(err, ErrNotFound) {
        fmt.Println("✅ 匹配到 ErrNotFound 哨兵错误")
    }
    if errors.Is(err, ErrPermissionDenied) {
        fmt.Println("✅ 匹配到 ErrPermissionDenied")
    } else {
        fmt.Println("❌ 未匹配到 ErrPermissionDenied")
    }
}

4.2.2 多错误场景对比

4.3 使用 errors.As 进行类型断言

errors.As(err, target) 用于判断错误链中是否存在某个类型的错误，并将第一个匹配的错误赋值给 target。它通常用于提取自定义错误类型中的附加信息。

4.3.1 自定义错误类型与类型断言

type HTTPError struct {
    Code    int
    Message string
    Err     error
}

func (e *HTTPError) Error() string {
    return fmt.Sprintf("HTTP %d: %s", e.Code, e.Message)
}

func (e *HTTPError) Unwrap() error {
    return e.Err
}

func fetchResource(url string) error {
    return &HTTPError{
        Code:    404,
        Message: "Not Found",
        Err:     fmt.Errorf("resource missing: %w", ErrNotFound),
    }
}

func main() {
    err := fetchResource("/api/data")
    var httpErr *HTTPError
    if errors.As(err, &httpErr) {
        fmt.Printf("✅ 捕获 HTTPError: Code=%d, Message=%s\n", httpErr.Code, httpErr.Message)
        // 进一步检查内部错误
        if errors.Is(httpErr.Err, ErrNotFound) {
            fmt.Println("  内部原因: 资源未找到")
        }
    }
}

4.3.2 errors.Is 与 errors.As 对比

4.4 断言失败时的处理策略

当 errors.Is 或 errors.As 返回 false 时，表示在完整的错误链中未找到目标。此时需要采取稳健的降级策略，避免程序进入未定义状态。

4.4.1 标准处理流程

1. 记录详细日志：输出完整的错误链（使用 %+v 或 fmt.Errorf 的详细格式），保留现场信息。
2. 返回通用错误：向上层返回一个通用的、安全的错误，避免泄露内部实现细节。
3. 触发告警：对于关键路径，断言失败可能意味着未预期的错误类型，应触发监控告警。
4. 执行兜底逻辑：如使用默认值、重试、降级服务等。

4.4.2 代码示例：稳健的断言失败处理

func handleDatabaseError(err error) error {
    // 策略1: 尝试提取自定义重试错误
    var retryErr *RetryableError
    if errors.As(err, &retryErr) {
        log.Printf("可重试错误，延迟 %v 后重试", retryErr.RetryAfter)
        return retryErr // 向上传递，由调用方决定是否重试
    }

    // 策略2: 检查特定哨兵错误
    if errors.Is(err, ErrConnectionClosed) {
        log.Println("连接已关闭，尝试重新建立连接")
        return reconnectAndRetry()
    }

    // 策略3: 断言失败 - 未知错误类型
    log.Printf("⚠️ 未预期的数据库错误类型: %+v", err)
    // 记录告警指标
    metrics.IncUnknownError()
    // 返回通用安全错误
    return fmt.Errorf("database internal error")
}

4.4.3 断言失败处理策略对比

4.5 常见陷阱与避坑指南

• 陷阱1：对 nil 错误进行断言 —— errors.Is(nil, target) 永远返回 false，不会 panic。但 errors.As(nil, &target) 如果 target 为 nil 会 panic。始终先检查 err != nil。
• 陷阱2：errors.As 的 target 必须是非 nil 指针 —— 如果传入 nil 或非指针类型，函数会 panic。必须使用 var myErr *MyType; errors.As(err, &myErr)。
• 陷阱3：使用值接收者实现 error 接口 —— 如果自定义错误类型使用值接收者实现 Error() 方法，errors.As 可能无法正确匹配。始终使用指针接收者。
• 陷阱4：忽略 Unwrap 方法 —— 自定义错误类型若想参与错误链，必须实现 Unwrap() error 方法，否则断言无法穿透。