直接用aws-sdk-go-v2/service/s3配置即可兼容多云S3服务，无需自定义ObjectStorage接口；因其已内置重试、超时、签名等逻辑，只需正确设置region（如oss-cn-hangzhou）、signingName=s3、带协议且不含bucket的endpoint，并启用ResolveUnknownService。
直接用 aws-sdk-go-v2/service/s3 配置 endpoint 和 credentials 就能跑通阿里云 OSS、腾讯云 COS、MinIO 等所有 S3 兼容服务，不需要为每家云单独写 SDK 封装。
为什么不用自己定义 ObjectStorage 接口
很多人一上来就写 type ObjectStorage interface { PutObject(); GetObject() }，再给各家云各实现一个 struct。结果是：80% 的代码重复（重试、超时、context 取消），但错误码映射、分块上传策略、元数据 key 大小写又得各自 hack；某家云升级签名 header 规则，你得改三处。
而 aws-sdk-go-v2/service/s3 本身已覆盖 S3 兼容服务的绝大多数行为。你写的不是“适配器”，是“配置驱动的 S3 客户端”。
-
region必须严格匹配文档 ID（如阿里云填oss-cn-hangzhou，不能填 “华东1”） -
signingName必须显式设为s3（哪怕对接 OSS，否则 SDK 会尝试用 oss 签名，返回403 Forbidden） -
endpoint必须带协议（https://），且不能含 bucket 名（错例：https://my-bucket.oss-cn-hangzhou.aliyuncs.com→ 正确：https://oss-cn-hangzhou.aliyuncs.com）
如何让 config.LoadDefaultConfig 同时兼容各家云
核心是绕过 SDK 默认的 region→endpoint 映射，用 config.WithEndpointResolverWithOptions 强制指定 endpoint，并通过 config.WithRegion 仅传递 region 字符串（用于签名和部分 header 构造，不用于 DNS 解析）。
立即学习“go语言免费学习笔记（深入）”；
在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface
示例配置阿里云 OSS：
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithRegion("oss-cn-hangzhou"),
config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
"your-access-key", "your-secret-key", "")),
config.WithEndpointResolverWithOptions(
aws.EndpointResolverWithOptionsFunc(func(service, region string) (aws.Endpoint, error) {
return aws.Endpoint{URL: "https://oss-cn-hangzhou.aliyuncs.com"}, nil
}),
func(o *config.LoadOptions) { o.ResolveUnknownService = true }),
)
注意：o.ResolveUnknownService = true 是关键开关，否则 SDK 会因不认识 oss 服务名而拒绝加载。
Gin 中初始化并注入 S3 客户端
别在 handler 里每次 new client，应在应用启动时初始化一次，然后注入到 Gin *gin.Context 或全局变量中。
- 推荐方式：用
c.Set("s3client", client)在中间件中挂载，后续 handler 用c.MustGet("s3client").(*s3.Client)取用 - 避免用全局变量裸奔，尤其在测试时难以 mock
- 上传大文件建议传带 timeout 的
context.WithTimeout(ctx, 5*time.Minute)，防止阻塞整个请求链路 - 调用
s3.PutObject前务必检查bucket是否存在且可写，否则错误信息模糊（常见报错：NotFound或AccessDenied，实际可能是 bucket 不存在或权限不足）
MinIO 本地调试必须注意的坑
MinIO 默认启用 SSL，但本地 Docker 启动时通常用 HTTP；若没关 SSL，aws-sdk-go-v2 会因证书校验失败直接 panic。
- Docker 启动加
-e "MINIO_SERVER_URL=http://localhost:9000"显式声明非 HTTPS 地址 - Go 客户端初始化时
useSSL设为false，否则连接被拒 - MinIO 的 AccessKey/SecretKey 必须是 16 位以上，否则 SDK 报
Invalid argument to crypto/cipher.NewCTR - 首次访问 MinIO 控制台后，记得手动创建 bucket，SDK 不会自动建（
PutObject会直接失败）
真正麻烦的不是写上传逻辑，而是各家云对 ETag 计算、Content-MD5 校验、分块大小限制（OSS 最小 100KB，COS 最小 5MB）、以及 x-amz-meta- 前缀元数据是否大小写敏感这些细节——它们不会报错，但会导致前端直传签名失效或 CDN 缓存不一致。
