MinIO分片上传必须走InitiateMultipartUpload→PutObjectPart→CompleteMultipartUpload三步流程，而非PutObject或ComposeObject；需严格切片读取、并发限流、ETag校验与错误重试闭环。
分片上传前必须调用 PutObject 还是 ComposeObject？
都不是。MinIO 的分片上传必须走 InitiateMultipartUpload → PutObjectPart → CompleteMultipartUpload 三步流程，PutObject 是单文件直传，ComposeObject 是服务端拼接已有对象，两者都不参与分片逻辑。
常见错误是直接用 PutObject 传大文件，结果超时或内存爆掉；或者误以为 ComposeObject 能替代分片，实际它不支持从客户端流式上传分片数据。
-
InitiateMultipartUpload返回唯一uploadID，后续所有分片必须携带它 - 每个
PutObjectPart必须指定非零正整数partNumber（1～10000），且不能重复 -
CompleteMultipartUpload需传入按partNumber排序的ObjectPart列表，顺序错会导致校验失败
如何正确构造 PutObjectPart 的 io.Reader 参数？
不能直接传整个文件的 *os.File 或大 buffer，否则每片都读全量、内存和 IO 双重浪费。必须按分片切片读取——即对源文件 seek 到偏移量，读取指定长度。
典型坑：用 bytes.NewReader(data) 把整块数据加载进内存再传，100MB 分片就占 100MB 堆内存；或用 file.Read() 但没控制长度，导致后续分片读错位置。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 用
io.NewSectionReader(file, offset, size)最稳妥：底层复用文件句柄，只读指定区间 - 避免用
file.Seek()+io.CopyN()组合，Seek 在并发上传时易受干扰 - 如果源是
http.Request.Body这类不可 rewind 流，必须先写到临时文件或bytes.Buffer（仅限小文件）
CompleteMultipartUpload 失败报 InvalidPart 怎么排查？
这不是网络问题，而是服务端校验失败：上传的某一分片的 ETag 与 MinIO 计算出的不一致。根本原因几乎总是分片内容不完整或被篡改。
现象包括：最后一片读取长度不足（文件总长不是分片大小整数倍）、中间片被截断、HTTP 传输中 gzip 自动解压干扰（尤其 Nginx 代理未禁用压缩）、或客户端重复上传同一 partNumber 但内容不同。
- 检查每个
PutObjectPart返回的ObjectInfo.ETag，确认是否全为合法 hex 字符串（如"d41d8cd98f00b204e9800998ecf8427e"），空值或带引号说明上传异常 - 确保每个分片读取字节数严格等于你声明的
size，用len(buf)校验，而非依赖io.Read()返回值是否等于size - 关闭任何中间件（如反向代理、WAF）对请求体的修改，MinIO 对分片内容敏感
并发上传分片时要不要加锁或控制 goroutine 数量？
要，但不是为数据竞争——minio.Client 本身是线程安全的，问题在于系统资源耗尽：默认不限速会瞬间打开数百个 HTTP 连接，触发 dial tcp: too many open files 或服务端连接拒绝。
MinIO 官方 SDK 不内置限流，靠外部控制。别用 sync.WaitGroup 简单起手并发，那只是等完成，不解决连接爆炸。
- 用
semaphore.NewWeighted(int64(maxConcurrentParts))（需golang.org/x/sync/semaphore）限制同时上传分片数，推荐 3～5 - 每个
PutObjectPart调用前sem.Acquire(ctx, 1)，完成后sem.Release(1) - 注意
context.WithTimeout必须包住整个分片上传流程，否则单个分片卡死会拖垮全部
分片上传真正难的不是 API 调用顺序，而是把文件切片、并发控制、错误重试、ETag 校验这四件事在一次上传中闭环住——漏掉任意一环，都会在大文件或弱网下暴露问题。
