3. 错误码基础概念：HTTP 状态码与对象存储错误码的关系

在对象存储接口的日常开发中，错误码是定位问题最直接的线索。Go 语言 SDK 封装了底层 HTTP 通信，但错误码的根源仍来自 HTTP 协议层与对象存储服务端的约定。理解 HTTP 状态码与对象存储错误码的映射关系，是编写健壮断言逻辑的前提。

3.1 HTTP 状态码与对象存储错误码的映射关系

对象存储服务（如 AWS S3、阿里云 OSS、腾讯云 COS）均基于 RESTful API 设计，所有接口响应都携带 HTTP 状态码。SDK 在收到响应后，会将 HTTP 状态码解析为更细粒度的业务错误码。下表展示了常见 HTTP 状态码与对象存储错误码的对应关系：

3.2 错误码分类：客户端错误 4xx 与服务端错误 5xx

对象存储错误码按 HTTP 状态码范围分为两大类，每一类对应不同的处理策略。

3.2.1 客户端错误（4xx）

4xx 错误表示请求本身存在问题，通常由调用方传入非法参数、权限不足或资源不存在导致。这类错误在重试时大概率会再次失败，因此业务代码应直接向上层返回错误，而非盲目重试。

• 常见子类：400（参数错误）、401/403（认证/授权失败）、404（资源不存在）、409（资源冲突）。
• 处理策略：记录错误日志、检查请求参数、确认权限配置、提示用户修正输入。
• Go SDK 示例：当收到 NoSuchKey 错误时，应判断为对象不存在，而非网络问题。

3.2.2 服务端错误（5xx）

5xx 错误表示服务端内部异常或过载，请求本身可能并无问题。这类错误通常具有临时性，适合采用指数退避策略进行重试。

• 常见子类：500（内部错误）、503（服务不可用）、504（网关超时）。
• 处理策略：实现重试逻辑（建议最多 3 次）、增加退避间隔、监控服务端健康状态。
• Go SDK 示例：当收到 ServiceUnavailable 错误时，SDK 内置的重试器会自动尝试，但业务层仍需捕获最终失败。

3.3 错误码在 SDK 中的表示

Go 语言的对象存储 SDK 通常将错误码封装为结构体类型，实现 error 接口。业务代码通过类型断言或错误码字符串来获取具体错误信息。以下以阿里云 OSS SDK 和 AWS S3 SDK 为例说明。

3.3.1 阿里云 OSS SDK 错误表示

import "github.com/aliyun/aliyun-oss-go-sdk/oss"

// 发起请求
_, err := bucket.GetObject("my-object.txt")
if err != nil {
    // 类型断言获取 OSS 服务错误
    if ossErr, ok := err.(oss.ServiceError); ok {
        fmt.Printf("HTTP Status: %d\n", ossErr.StatusCode)
        fmt.Printf("Error Code: %s\n", ossErr.Code)
        fmt.Printf("Error Message: %s\n", ossErr.Message)
        fmt.Printf("Request ID: %s\n", ossErr.RequestID)
    } else {
        // 非服务端错误（如网络超时）
        fmt.Printf("Network error: %v\n", err)
    }
}

3.3.2 AWS S3 SDK 错误表示

import (
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/smithy-go"
)

// 发起请求
_, err := client.GetObject(ctx, &s3.GetObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("my-object.txt"),
})
if err != nil {
    // 类型断言获取 smithy 通用错误
    var opErr *smithy.OperationError
    if errors.As(err, &opErr) {
        fmt.Printf("Operation: %s\n", opErr.Operation)
        // 进一步断言获取 HTTP 响应信息
        var httpErr *smithyhttp.ResponseError
        if errors.As(opErr, &httpErr) {
            fmt.Printf("HTTP Status: %d\n", httpErr.HTTPStatusCode)
        }
    }
    // 获取 S3 特定错误码
    var noSuchKey *s3types.NoSuchKey
    if errors.As(err, &noSuchKey) {
        fmt.Println("Error: object does not exist")
    }
}

3.4 错误码分类与 SDK 表示结构图

下图展示了 HTTP 状态码、对象存储错误码与 Go SDK 错误类型之间的分层关系：

3.5 错误码断言的核心流程

在 Go 对象存储接口的实战中，错误码断言通常遵循以下步骤：

1. 发起请求：调用 SDK 提供的 Bucket/Object 操作方法。
2. 捕获错误：检查返回的 error 是否为 nil。
3. 类型断言：将 error 断言为 SDK 定义的错误结构体（如 oss.ServiceError 或 smithy.OperationError）。
4. 提取错误码：从结构体中读取 Code 或 StatusCode 字段。
5. 分类处理：根据错误码前缀或具体值，决定是重试、返回默认值还是向上层报错。