分片上传必须先调用 CreateMultipartUpload 获取唯一 uploadId，Key 大小写敏感且需合法；PartNumber 从 1 开始严格递增，不可跳号或复用；每片 ≥5 MiB（末片除外）；ETag 必须从 UploadPart 响应头提取并准确传入 CompleteMultipartUpload；断点续传依赖本地持久化 uploadId、PartNumber 和 ETag 三元组状态。

分片上传前必须初始化 Multipart Upload

不调用 CreateMultipartUpload 直接传分片会返回 InvalidRequest 或 NoSuchUpload 错误。对象存储（如 AWS S3、MinIO、腾讯云 COS）要求先获取唯一 uploadId，后续所有分片都必须携带它。

• 每次初始化都会生成新 uploadId，不能复用旧的（即使文件名相同）
• Key（即对象路径）需与最终合成时一致，大小写敏感，且不能含非法字符（如 \0、CR/LF）
• 建议在初始化后立即持久化 uploadId 和 bucket/key，防止客户端中断后无法续传

分片上传需按序号上传且不可跳号

调用 UploadPart 时必须传入严格递增的 PartNumber（从 1 开始），服务端不会自动排序或校验内容连续性——传错序号会导致 CompleteMultipartUpload 失败并报 InvalidPart。

• PartNumber 是整数，范围 1–10000，不能为 0 或负数
• 每个分片大小建议 ≥ 5 MiB（S3 要求最小 5 MiB，MinIO 默认兼容但部分配置下也强制）；最后一片可小于该值
• 上传并发时需确保 PartNumber 不冲突，推荐用 goroutine + channel 控制顺序，或提前分配好编号再并发上传

合并分片前必须收集完整 Part ETag 列表

CompleteMultipartUpload 的输入是 PartNumber 和对应分片的 ETag（不是 MD5，而是服务端计算的 base64 编码值），缺一不可，且顺序必须与上传时 PartNumber 一致。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

• ETag 必须从 UploadPart 响应头中提取，不能自行计算（S3 的 ETag 是 MD5 拼接 "-n"，但 MinIO/COS 实现不同）
• 若某一分片上传失败，需重传并用相同 PartNumber，ETag 会变化，必须更新记录
• 合并请求体是 JSON 格式，字段名必须是 Parts，每个元素含 PartNumber 和 ETag，字段名大小写敏感

断点续传依赖 uploadId + PartNumber + ETag 三元组校验

服务端不保存客户端本地状态，续传能力完全由你维护的元数据决定：只要你知道 uploadId、哪些 PartNumber 已成功上传、对应 ETag 是什么，就能跳过已传分片。

立即学习“go语言免费学习笔记（深入）”；

• 不要依赖“文件是否已存在”判断是否能续传——对象未完成前，服务端查不到该 key 的任何数据
• 建议将每一分片状态（pending / uploading / uploaded / failed）存到本地磁盘或数据库，避免内存丢失
• 调用 ListParts 可查询已上传分片，但它只返回 PartNumber 和 ETag，不返回原始分片内容或校验和，不能替代本地记录

分片上传真正麻烦的不是代码量，而是状态同步——uploadId 生命周期、PartNumber 分配逻辑、ETag 存储位置、失败重试边界，这四点任意一个没对齐，就会卡在合并阶段报错，而且错误信息往往模糊。