Go标准库无上传进度回调，必须用ProgressReader包装Request.Body并手动解析multipart，配合轮询获取状态；Gin/Echo的MultipartForm()因一次性读取无法监控进度。
Go 语言标准库不提供上传进度回调，想在框架（如 Gin、Echo）中实现上传进度实时监控，必须绕过默认的 Request.Body 读取路径，用自定义 io.Reader 包装原始流，并配合客户端轮询或 WebSocket 主动推送状态——这是唯一可行路径，没有“开箱即用”的捷径。
为什么 Gin/Echo 的 c.MultipartForm() 无法直接获取上传进度
Gin 和 Echo 在解析 multipart 表单时，会一次性调用 Request.Body.Read() 直到读完或超时，中间不暴露读取过程。这意味着：
- 你无法在框架自动解析阶段插入进度统计逻辑
-
c.FormFile()或c.MultipartForm()返回的是已完整读入内存或临时磁盘的文件句柄，此时上传早已结束 - 若文件较大，还可能触发
http: request body too large错误，而你连进度都看不到
必须手动接管 Request.Body：用 ProgressReader 包装并注入 multipart.Reader
核心动作不是改框架，而是替换请求体的读取源头。你需要：
- 提前读取
c.Request.Header.Get("Content-Length")获取总大小（注意：客户端必须发送该 header，否则 fallback 到 -1） - 创建一个
ProgressReader，嵌入原始c.Request.Body，并在其Read()方法中累加字节数、更新sync.Map中以uploadID为 key 的状态 - 用这个
ProgressReader初始化multipart.NewReader()，再逐个解析Part—— 这样每读一块数据，进度就更新一次 - 避免使用
c.ParseMultipartForm()，它会绕过你的包装器
示例关键片段：
Echo框架 5.1.0
下载
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
立即学习“go语言免费学习笔记（深入）”；
pr := &ProgressReader{
Reader: c.Request.Body,
total: contentLength,
id: uploadID,
}
mr := multipart.NewReader(pr, boundary)
for {
part, err := mr.NextPart()
if err == io.EOF { break }
// 处理 part.Header 和 part.Body（仍是 ProgressReader 包装过的）
}
客户端怎么拿到进度？轮询接口比 WebSocket 更稳
服务端把 uploadID 返回给前端后，前端应发起独立轮询（如 /api/progress?id=xxx），服务端从 sync.Map 查状态并返回 JSON：
- 不要用 WebSocket：上传本身是单向 HTTP 流，WebSocket 需额外维护连接生命周期，容易因超时、重连失败导致进度丢失
- 轮询间隔建议 500ms–2s，太密增加服务端压力，太疏影响感知
- 状态结构体必须含
read、total、done bool、err string，前端靠done和err判断是否终止轮询 -
sync.Map的 key 必须带 TTL 清理（比如上传完成 5 分钟后自动删），否则内存泄漏
大文件上传时最易忽略的三个点
实际压测中，90% 的进度不准或卡死问题都出在这三处：
- 没禁用
http.Server.ReadTimeout：上传大文件时，超时会直接中断连接，但ProgressReader不知情，状态卡在中间值 - 没处理
multipart.Part的FileName空值：某些客户端（如 curl -F）不带 filename，part.FileName()返回空，但part.Header里仍有数据，需 fallback 到part.FormName() - 没限制单次
Read()的[]byte长度：若传入超大 buffer（如 64MB），ProgressReader.Read()一次就上报全部，进度条“瞬间跳到 100%”
进度监控的本质是控制数据流的可见性，不是功能叠加；一旦开始接管 Body，就要对整个 HTTP 生命周期负责——包括超时、错误传播、资源释放。别指望框架替你兜底。
