不能直接用 io.ReadWriter 做对象存储接口，因其无法表达 ContentType、ACL 等元数据及 HeadObject 等非读写操作，需定义覆盖上传/下载/查询/删除/列举五类动作的契约接口。
为什么不能直接用 io.ReadWriter 做对象存储接口
因为对象存储的核心操作不是流式读写，而是带元数据、路径（Key）、版本和策略的原子性操作。直接套用 io.ReadWriter 会导致无法表达 PutObject 的 ContentType、ACL、Expires 等关键参数，也无法统一处理 HeadObject 或 ListObjectsV2 这类非读写行为。
真正需要的是一个能覆盖「上传/下载/查询/删除/列举」五类动作，并允许注入不同后端（S3、MinIO、本地FS）的契约接口。
-
PutObject必须接收io.Reader+options（比如ContentType、CacheControl） -
GetObject返回值需包含io.ReadCloser和ObjectInfo（含ETag、LastModified） -
DeleteObject应支持批量，但接口签名优先单 Key，避免强耦合批量实现细节 - 所有方法应返回标准
error，不封装成自定义错误类型——下游自己用errors.Is判断os.ErrNotExist或storage.ErrNotFound
如何定义最小可行的 ObjectStorage 接口
接口字段越少，越容易适配不同后端。重点不是功能全，而是可组合、可测试、不绑定 HTTP 或 SDK。
推荐定义如下（不含上下文、不带泛型、不预设加密/分片逻辑）：
立即学习“go语言免费学习笔记（深入）”；
type ObjectStorage interface {
PutObject(ctx context.Context, key string, r io.Reader, opts PutOptions) error
GetObject(ctx context.Context, key string, opts GetOptions) (ObjectReader, error)
DeleteObject(ctx context.Context, key string) error
ListObjects(ctx context.Context, prefix string, opts ListOptions) ([]ObjectInfo, error)
}
type ObjectReader interface {
io.ReadCloser
Info() ObjectInfo
}
注意三点：
-
PutOptions和GetOptions用结构体而非 map[string]any，便于 IDE 提示和编译检查 -
ObjectReader是接口而非 struct，方便 mock 测试时返回内存 reader + 预设 Info - 不暴露
Bucket参数——它应由实现层封装（如minioClient.BucketName），接口使用者只关心 key
本地文件系统实现最容易踩的坑
本地 FS 实现常被当成“开发模式兜底”，但若不处理边界，上线后会暴雷。
典型问题包括：
- 路径遍历：
key = "../../../etc/passwd"→ 必须用filepath.Clean+ 校验是否仍在根目录内 - 并发写入：多个 goroutine 写同一 key 时，
os.Create不是原子的 → 改用os.WriteFile或临时文件 +os.Rename - ListObjects 缺少分页支持：一次性读全目录易 OOM → 应接受
maxKeys并返回isTruncated字段（哪怕只是模拟） - ETag 计算方式不一致：S3 用 MD5，FS 实现若返回空或随机值，会导致 CDN 缓存失效 → 建议对小文件用
md5.Sum，大文件跳过或返回"-"（非校验型 ETag）
对接 AWS S3 / MinIO 时必须重写的三个方法
官方 SDK（aws-sdk-go-v2 或 minio-go）不直接兼容上述接口，需做适配，重点改以下三处：
-
PutObject：SDK 要求传*s3.PutObjectInput，需把PutOptions映射过去；特别注意ContentType必须显式设置，否则 S3 默认为binary/octet-stream，浏览器可能拒解析 -
GetObject：SDK 返回*s3.GetObjectOutput.Body是io.ReadCloser，但缺失ContentLength和ETag→ 需包装一层 struct，从output.ContentLength和output.ETag构造ObjectInfo -
ListObjects：S3 v2 的ListObjectsV2分页依赖ContinuationToken，而接口只传prefix→ 实现里需循环调用直到IsTruncated == false，或明确文档说明“本实现不支持分页，仅用于 dev”
别试图在接口层加 WithContext 方法变体——Go 接口不支持重载，统一用 context.Context 参数即可。
