本文档说明高性能桶 Go SDK 的错误处理方式。当 SDK 调用失败时,会返回统一的错误类型
*cos.ErrorResponse,可从中获取错误码、错误信息、请求 ID 及 HTTP 状态码,便于定位与处理问题。错误类型
SDK 调用失败时返回的错误可断言为
*cos.ErrorResponse,其结构如下:字段 | 类型 | 描述 |
Code | string | 错误码,如 NoSuchBucket、AccessDenied |
Message | string | 错误的详细描述信息 |
Resource | string | 发生错误的资源 |
RequestID | string | 本次请求的唯一标识,排查问题时可提供给技术支持 |
TraceID | string | 服务端调用链追踪 ID |
Response | *http.Response | 原始 HTTP 响应,可通过 Response.StatusCode 获取 HTTP 状态码 |
辅助函数
SDK 提供以下辅助函数便于判断与提取错误:
函数 | 描述 |
func IsNotFoundError(e error) bool | 判断错误是否为资源不存在(HTTP 404),如对象或桶不存在 |
func IsCOSError(e error) (*ErrorResponse, bool) | 类型断言,若为 COS 错误则取出 *ErrorResponse 并返回 true |
示例
判断错误并提取错误码、错误信息、请求 ID 与 HTTP 状态码:
package mainimport ("context""log""net/http""net/url""os""time""github.com/tencentyun/cos-go-sdk-v5")func main() {u, _ := url.Parse("https://examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com")b := &cos.BaseURL{BucketURL: u}base := &cos.AuthorizationTransport{SecretID: os.Getenv("SECRETID"),SecretKey: os.Getenv("SECRETKEY"),}c := cos.NewClient(b, &http.Client{Transport: cos.NewRapidCredentialTransport(base),Timeout: 30 * time.Second,})ctx := context.Background()_, err := c.Object.Get(ctx, "not-exist-key", nil)if err != nil {// 使用 IsNotFoundError 判断对象/桶是否不存在。if cos.IsNotFoundError(err) {log.Println("object not found")return}// 取出 *ErrorResponse,读取详细字段。if e, ok := cos.IsCOSError(err); ok {log.Printf("Code: %s", e.Code)log.Printf("Message: %s", e.Message)log.Printf("RequestID: %s", e.RequestID)if e.Response != nil {log.Printf("StatusCode: %d", e.Response.StatusCode)}return}// 其他错误(如网络错误)。log.Fatalf("request failed: %v", err)}}
常见错误码
错误码 | HTTP 状态码 | 说明 |
NoSuchBucket | 404 | 请求的桶不存在 |
NoSuchKey | 404 | 请求的对象不存在 |
NoSuchPolicy | 404 | 桶未设置存储桶策略 |
AccessDenied | 403 | 无权限访问,请检查 CAM 授权或桶策略 |
BucketNotEmpty | 409 | 删除桶时桶内仍有对象,需先清空对象 |
错误码可结合
RequestID 一并用于问题排查。