4. Go 错误处理机制：从 error 接口到错误包装与解包

在 Go 语言中，错误处理是构建健壮系统的基石。对于对象存储接口而言，每一次 API 调用都可能返回网络超时、权限拒绝、资源不存在等错误。理解 Go 的错误处理机制，能够帮助我们精确地断言错误码，并做出正确的业务决策。

4.1 error 接口：一切错误的起点

Go 语言通过内置的 error 接口统一了错误的表示方式。任何实现了该接口的类型都可以作为错误值传递。

type error interface {
    Error() string
}

该接口只要求一个 Error() 方法，返回描述错误的字符串。这意味着你可以为自定义错误类型附加额外的上下文信息，例如 HTTP 状态码、对象存储的请求 ID 等。

4.2 errors 包：基础错误工厂

errors 包提供了最基础的错误创建与判断能力。

• errors.New(text string) error：创建一个只包含静态文本的错误。
• errors.Unwrap(err error) error：返回被包装错误的下一层（如果实现了 Unwrap() 接口）。
• errors.Is(err, target error) bool：判断错误链中是否包含与 target 相等的错误。
• errors.As(err error, target interface{}) bool：在错误链中查找第一个可以赋值给 target 类型的错误。

4.3 fmt.Errorf：带格式的错误包装

fmt.Errorf 是日常开发中最常用的错误创建方式。它支持格式化字符串，并通过 %w 动词实现错误包装。

import "fmt"

// 基础用法：创建带格式的错误
err := fmt.Errorf("bucket %s does not exist", bucketName)

// 包装错误：使用 %w 将原始错误包装进新错误
if _, err := os.Open(filepath); err != nil {
    return fmt.Errorf("open file failed: %w", err)
}

使用 %w 包装的错误会保留原始错误的类型和值，使得 errors.Is 和 errors.As 能够沿着错误链进行遍历查找。

4.4 自定义错误类型：携带结构化信息

对于对象存储接口，仅靠字符串描述远远不够。我们需要自定义错误类型来携带状态码、请求 ID、资源路径等结构化信息。

type StorageError struct {
    Code       int    // HTTP 状态码或业务错误码
    Message    string // 人类可读的错误描述
    RequestID  string // 用于追踪的请求 ID
    Resource   string // 出错的资源路径
    Err        error  // 原始错误（可选）
}

func (e *StorageError) Error() string {
    return fmt.Sprintf("storage error: code=%d, message=%s, request_id=%s, resource=%s",
        e.Code, e.Message, e.RequestID, e.Resource)
}

// 实现 Unwrap 接口，支持错误链
func (e *StorageError) Unwrap() error {
    return e.Err
}

4.5 错误包装与解包：errors.Is / errors.As

错误包装形成了链式结构。解包的核心工具是 errors.Is 和 errors.As，它们分别用于“值相等性判断”和“类型匹配判断”。

// 使用 errors.Is 判断哨兵错误
if errors.Is(err, ErrObjectNotFound) {
    // 执行对象不存在的处理逻辑
}

// 使用 errors.As 提取自定义错误类型
var storageErr *StorageError
if errors.As(err, &storageErr) {
    fmt.Printf("错误码: %d, 请求ID: %s\n", storageErr.Code, storageErr.RequestID)
}

4.6 错误处理流程总览

下图展示了从错误产生到错误断言解包的完整流程：

4.7 错误码断言实战模式

在对象存储接口中，我们通常将错误码断言封装为工具函数，提高代码复用性：

// 断言错误是否为指定的 HTTP 状态码
func IsHTTPStatus(err error, statusCode int) bool {
    var storageErr *StorageError
    if errors.As(err, &storageErr) {
        return storageErr.Code == statusCode
    }
    return false
}

// 断言错误是否为特定的哨兵错误
func IsObjectNotFound(err error) bool {
    return errors.Is(err, ErrObjectNotFound)
}

// 使用示例
func (c *Client) GetObject(ctx context.Context, bucket, key string) (*Object, error) {
    obj, err := c.api.GetObject(ctx, bucket, key)
    if err != nil {
        if IsHTTPStatus(err, 404) {
            // 对象不存在，返回 nil 而非错误
            return nil, nil
        }
        if IsHTTPStatus(err, 403) {
            // 权限不足，包装后返回
            return nil, fmt.Errorf("access denied to %s/%s: %w", bucket, key, err)
        }
        return nil, fmt.Errorf("get object failed: %w", err)
    }
    return obj, nil
}

4.8 错误处理最佳实践总结

• 优先使用哨兵错误：用 errors.New 定义包级别的错误常量，便于 errors.Is 精确匹配。
• 包装时保留根因：始终使用 %w 包装原始错误，不要吞没底层错误信息。
• 自定义错误携带上下文：为对象存储接口设计 StorageError 类型，包含状态码、请求 ID 等字段。
• 使用 errors.As 提取结构化信息：在断言时通过 errors.As 获取自定义错误类型的字段值。
• 避免裸返回：不要直接返回底层库的错误，应包装后添加业务上下文。