断点续传核心在于服务端不提前消费字节流、客户端精准写入偏移；r.parsemultipartform(0) 和 os.o_append 是两大陷阱，90% 失败源于此——服务端须禁用自动解析，因首次访问 r.multipartform 即触发默认 parsemultipartform(32
Go 实现大文件流式传输的断点恢复，核心不是“能不能发请求”，而是服务端能否保持原始字节流不被提前消费、客户端能否精准定位并安全写入偏移位置——r.ParseMultipartForm(0) 和 os.O_APPEND 是两个最常踩的坑，90% 的失败源于它们。
服务端必须禁用 ParseMultipartForm 自动解析
Go 的 http.Request 在首次访问 r.MultipartForm 或调用 r.ParseMultipartForm（哪怕没显式写）时，会默认执行 r.ParseMultipartForm(32 ，把整个请求体读进内存或临时文件。这对分片上传是致命的：流被提前消费，<code>r.Body 后续读不到数据，分片内容错位或为空。
- 必须在 handler 开头第一行调用
r.ParseMultipartForm(0)，传0表示禁用自动解析 - 元信息（如
upload_id、chunk_index）从r.URL.Query().Get("chunk_index")或r.FormValue("upload_id")获取，别碰r.MultipartForm.Value——它可能为 nil 或尚未就绪 - 分片二进制数据直接从
r.Body读取，用io.CopyN(dst, r.Body, chunkSize)写入磁盘，路径建议为./uploads/{upload_id}/chunk_{index:04d} - 写入前用
os.MkdirAll确保目录存在；并发写同一分片时，打开文件需加os.O_EXCL防止覆盖
客户端 Range 请求必须验证真实支持性
只看响应头有 Accept-Ranges: bytes 毫无意义——Nginx、CDN 常伪造该 header，但实际对 Range 请求返回 200 OK 或直接 500。必须发试探请求确认行为。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 下载前先发一个
HEAD /file.zip或带Range: bytes=0-1023的GET请求 - 仅当响应码为
206 Partial Content且Content-Range头匹配（如bytes 0-1023/12345678）才启用续传逻辑 - 若返回
200，说明服务端不支持，应清空本地文件重下；若返回416，需用HEAD获取真实长度再重试 - 每次请求的
Range头必须严格为bytes={offset}-，不能多空格、不能结尾带横杠（如bytes=1024-✅，bytes=1024-❌）
写文件必须用 Seek + O_WRONLY，彻底抛弃 O_APPEND
os.O_APPEND 是断点续传最大陷阱：它会让后续所有 Write() 忽略之前 Seek() 的偏移，强制写到末尾，导致数据错位、中间填充空白字节，文件损坏。
- 正确打开方式：
os.OpenFile(filename, os.O_WRONLY|os.O_CREATE, 0644)（不加O_TRUNC，不加O_APPEND） - 打开后立刻调用
f.Seek(offset, io.SeekStart)，并检查返回值是否等于offset；不等说明文件已被外部修改 - 写入前可选调用
f.Truncate(expectedSize)确保文件长度足够，防止稀疏文件问题 - 并发写同一文件时，
Seek+Write非原子，必须用sync.Mutex包裹，或改用单 goroutine 顺序写
断点状态必须持久化且轻量
重启或部署更新后，内存里的进度全丢，续传就变成重传。状态不能只存变量，也不能用重载开销大的数据库。
- 推荐用 JSON 文件落地，例如
./state/{upload_id}.json，内容含uploaded_chunks: [0,1,3]、total_chunks: 12、file_size: 12345678 - 合并阶段前，必须校验
len(uploaded_chunks) == total_chunks，缺一不可；否则静默失败比报错更危险 - 每个分片上传成功后，立即追加索引到状态文件（用
os.O_WRONLY | os.O_APPEND写状态文件本身没问题，因为它只是小文本） - 服务端需配 TTL 清理机制，比如定时扫描 24 小时未更新的
{upload_id}目录并删除
最关键的细节藏在最朴素的操作里：禁用 ParseMultipartForm 是服务端流式接收的前提，而拒绝 O_APPEND 是客户端数据不越界的底线。这两步做错，其余逻辑再完整也大概率失败。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
