4、S3兼容错误码体系

在对象存储接口开发中，S3兼容错误码是客户端与服务器之间传递错误信息的标准化载体。无论是调用AWS S3原生服务，还是兼容S3 API的自建对象存储（如MinIO、Ceph RGW），错误码的结构和语义都遵循同一套规范。掌握这套体系，是编写健壮错误断言逻辑的前提。

4.1 S3标准错误码列表

S3规范定义了数十种标准错误码，覆盖访问控制、资源存在性、请求合法性、内部错误等场景。以下是开发中最常遇到的错误码及其含义：

4.2 错误码结构：Code / Message / Resource / RequestId

S3错误响应体采用XML格式，包含四个核心字段。理解每个字段的语义和取值规则，是正确解析和断言错误的关键。

• Code — 错误码标识符，如 NoSuchBucket。用于程序化判断错误类型，是断言的主要匹配目标。
• Message — 人类可读的错误描述，如 The specified bucket does not exist。用于日志输出和调试，不建议作为断言依据（不同服务商可能措辞不同）。
• Resource — 触发错误的资源标识，如 /my-bucket/my-object.txt。用于定位具体资源，在断言中可用于验证错误是否发生在预期的资源上。
• RequestId — 服务端为该请求生成的唯一标识符。用于追踪请求链路，在断言中通常不直接匹配，但可在测试失败时用于排查。

一个典型的S3错误响应体如下：

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchBucket</Code>
  <Message>The specified bucket does not exist</Message>
  <Resource>/example-bucket</Resource>
  <RequestId>tx00000000000000000001-0065a3b2c1</RequestId>
</Error>

4.3 S3错误码断言流程

下图展示了从发起S3请求到完成错误码断言的完整流程：

4.4 错误码断言实战要点

在Go中编写错误码断言时，推荐遵循以下步骤：

1. 类型断言：将 error 接口断言为具体的S3错误类型。
2. 提取Code：通过 err.Code 或 err.ErrorCode() 获取错误码字符串。
3. 匹配预期：使用 assert.Equal(t, "NoSuchBucket", code) 进行断言。
4. 可选验证Resource：当需要确认错误发生在特定资源时，验证 err.Resource 字段。

// Go 错误码断言示例
func TestNoSuchBucket(t *testing.T) {
    // 模拟调用S3 API
    _, err := client.HeadBucket(ctx, &s3.HeadBucketInput{
        Bucket: aws.String("non-existent-bucket"),
    })

    // 类型断言为 smithyhttp.ResponseError
    var respErr smithyhttp.ResponseError
    if errors.As(err, &respErr) {
        // 进一步断言错误码
        assert.Equal(t, "NoSuchBucket", respErr.ErrorCode())
        t.Logf("RequestId: %s", respErr.RequestID)
    } else {
        t.Fatalf("expected smithyhttp.ResponseError, got %T", err)
    }
}

4.5 错误码与HTTP状态码对照关系

下表整理了常见S3错误码与HTTP状态码的对应关系，帮助你在断言时建立双重验证思维：