3、错误码设计原则：HTTP状态码与业务错误码的关系、RESTful API错误响应格式（XML/JSON）

3.1 错误码分层设计模型

在对象存储接口中，错误码采用双层结构：传输层（HTTP状态码）与业务层（业务错误码）。HTTP状态码用于快速判断请求的大类结果（成功、客户端错误、服务端错误），而业务错误码则精确描述具体失败原因（如桶不存在、签名过期、权限不足）。

3.2 HTTP状态码与业务错误码的映射关系

对象存储接口遵循RESTful语义，每个业务错误码都对应一个最合适的HTTP状态码。下表列出常见映射关系：

3.3 RESTful API错误响应格式

对象存储接口必须同时支持XML和JSON两种错误响应格式。客户端通过请求头 Accept 或查询参数 format 选择格式。两种格式包含相同的语义字段：

3.3.1 XML错误响应示例

HTTP/1.1 403 Forbidden
Content-Type: application/xml
x-amz-request-id: 1a2b3c4d5e6f7g8h

<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>AccessDenied</Code>
    <Message>请求被拒绝，请检查访问权限</Message>
    <Resource>/my-bucket/secret-file.pdf</Resource>
    <RequestId>1a2b3c4d5e6f7g8h</RequestId>
    <AdditionalDetails>
        <SignatureProvided>AWS4-HMAC-SHA256 ...</SignatureProvided>
        <StringToSign>AWS4-HMAC-SHA256 ...</StringToSign>
    </AdditionalDetails>
</Error>

3.3.2 JSON错误响应示例

HTTP/1.1 403 Forbidden
Content-Type: application/json
x-amz-request-id: 1a2b3c4d5e6f7g8h

{
    "code": "AccessDenied",
    "message": "请求被拒绝，请检查访问权限",
    "resource": "/my-bucket/secret-file.pdf",
    "requestId": "1a2b3c4d5e6f7g8h",
    "details": {
        "signatureProvided": "AWS4-HMAC-SHA256 ...",
        "stringToSign": "AWS4-HMAC-SHA256 ..."
    }
}

3.4 错误码断言在Go中的实现模式

在Go对象存储客户端中，错误码断言的核心是类型断言与错误码匹配。以下展示标准实现：

// 定义业务错误类型
type S3Error struct {
    HTTPStatusCode int    // HTTP状态码
    Code           string // 业务错误码
    Message        string // 错误描述
    Resource       string // 资源路径
    RequestId      string // 请求ID
}

// 实现 error 接口
func (e *S3Error) Error() string {
    return fmt.Sprintf("s3 error: %s (HTTP %d) - %s", e.Code, e.HTTPStatusCode, e.Message)
}

// 错误码断言函数
func IsAccessDenied(err error) bool {
    var s3Err *S3Error
    if errors.As(err, &s3Err) {
        return s3Err.Code == "AccessDenied"
    }
    return false
}

func IsNoSuchBucket(err error) bool {
    var s3Err *S3Error
    if errors.As(err, &s3Err) {
        return s3Err.Code == "NoSuchBucket"
    }
    return false
}

// 使用示例
func GetObject(bucket, key string) ([]byte, error) {
    data, err := s3Client.GetObject(bucket, key)
    if err != nil {
        if IsNoSuchBucket(err) {
            // 处理桶不存在：创建桶或返回友好提示
            return nil, fmt.Errorf("桶 %s 不存在，请检查名称", bucket)
        }
        if IsAccessDenied(err) {
            // 处理权限拒绝：刷新凭证或提示用户
            return nil, fmt.Errorf("无权访问对象 %s/%s", bucket, key)
        }
        return nil, fmt.Errorf("获取对象失败: %w", err)
    }
    return data, nil
}

3.5 错误码设计检查清单

3.6 常见错误码定义示例（Go常量）

// 错误码常量定义
const (
    // 客户端错误
    ErrCodeAccessDenied            = "AccessDenied"
    ErrCodeSignatureDoesNotMatch   = "SignatureDoesNotMatch"
    ErrCodeInvalidAccessKeyId      = "InvalidAccessKeyId"
    ErrCodeNoSuchBucket            = "NoSuchBucket"
    ErrCodeNoSuchKey               = "NoSuchKey"
    ErrCodeNoSuchUpload            = "NoSuchUpload"
    ErrCodeBucketAlreadyExists     = "BucketAlreadyExists"
    ErrCodeBucketNotEmpty          = "BucketNotEmpty"
    ErrCodeInvalidArgument         = "InvalidArgument"
    ErrCodeMissingContentLength    = "MissingContentLength"
    ErrCodePreconditionFailed      = "PreconditionFailed"
    ErrCodeInvalidRange            = "InvalidRange"

    // 服务端错误
    ErrCodeInternalError           = "InternalError"
    ErrCodeServiceUnavailable      = "ServiceUnavailable"
    ErrCodeSlowDown                = "SlowDown"

    // 重定向
    ErrCodePermanentRedirect       = "PermanentRedirect"
    ErrCodeTemporaryRedirect       = "TemporaryRedirect"
)

// 断言函数集合
var ErrAssertions = map[string]func(error) bool{
    ErrCodeAccessDenied:          IsAccessDenied,
    ErrCodeNoSuchBucket:          IsNoSuchBucket,
    ErrCodeNoSuchKey:             IsNoSuchKey,
    ErrCodeSignatureDoesNotMatch: IsSignatureDoesNotMatch,
    ErrCodeInternalError:         IsInternalError,
    // ... 其他错误码
}