Go HTTP 上传无原生 per-request 超时，需手动封装 multipart.File 为带 context 的 reader 并在 io.Copy 中检查 ctx.Done()，否则 ParseMultipartForm 超时后 file.Read() 仍无限阻塞。
Go HTTP 上传请求本身不支持 per-request 超时控制
默认 http.Server 的 ReadTimeout 和 WriteTimeout 是全局连接级的，对 multipart 文件上传几乎无效——因为 body 读取（尤其是大文件）发生在 handler 内部，超时计时器早已停摆。你看到的 “上传卡住” 或 “客户端断连无响应”，往往就是这个原因。
真正可控的超时点有两个：一是客户端发起请求后等待服务端接收 header 的时间（可由反向代理或客户端控制），二是服务端在 r.ParseMultipartForm() 或 form.File 后逐块读取文件流的时间。
- 用
context.WithTimeout包裹整个 handler 逻辑，但注意：它只中断 handler 执行，不会主动关闭底层 TCP 连接，客户端可能仍卡在 read 状态 - 必须在读取文件流时显式使用带 cancel 的
io.Copy，比如io.CopyN配合ctx.Done()检查，或封装一个带上下文的 reader - 避免直接调用
file.Open()后无限制io.Copy—— 此时超时完全失效
multipart.File 接口不支持 context，需手动 wrap reader
multipart.File 是个 io.ReadCloser，但它的 Read() 方法不接受 context.Context。这意味着你无法靠标准库原生方式实现“读一块、等一秒、超时就停”。常见错误是只对 ParseMultipartForm 加超时，却放任后续 file.Read() 自由执行。
正确做法是把 multipart.File 封装成一个带 context 的 reader：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
type ctxReader struct {
io.Reader
ctx context.Context
}
func (r *ctxReader) Read(p []byte) (n int, err error) {
select {
case <-r.ctx.Done():
return 0, r.ctx.Err()
default:
return r.Reader.Read(p)
}
}
- 不要用
time.AfterFunc或 goroutine 定时 close —— 可能引发 panic 或资源泄漏 - 如果用
io.Copy，务必传入&ctxReader{file, ctx}，而非原始file - 注意
multipart.File的底层可能是内存 buffer（小文件）或临时磁盘文件（大文件），前者读取快，后者更依赖 I/O 超时保障
上传链路中容易被忽略的 timeout 节点
一个完整上传链路包含至少 4 个独立超时点，漏掉任意一个都可能导致“看似设了超时，实则无效”：
- 客户端到反向代理（如 Nginx）：需配置
client_header_timeout、client_body_timeout，否则请求还没到 Go 进程就已被丢弃 - 反向代理到 Go server：Nginx 的
proxy_read_timeout必须 ≥ Go handler 的 context timeout，否则提前切断连接 - Go server 的
http.Server.ReadHeaderTimeout：控制从 TCP 建立到收到完整 header 的时间，防止慢 header 攻击 - handler 内部的 context timeout：应覆盖从
r.ParseMultipartForm开始，到文件保存完成的全过程；建议设为 30–120 秒，依业务容忍度调整
特别注意：若使用 net/http/pprof 或其他中间件，它们可能干扰 context 传递，务必验证 ctx.Err() 是否在超时时真实返回 context.DeadlineExceeded。
链路跟踪（trace）需在超时发生前完成 span 结束
如果你用 go.opentelemetry.io/otel 或类似库做链路跟踪，超时导致的 handler 提前退出很容易造成 span 泄漏——span 未结束，traceID 却已丢失，后续日志和 metric 关联断裂。
关键动作是在 defer 或 recover 前显式结束 span：
func uploadHandler(w http.ResponseWriter, r *http.Request) {
ctx, span := tracer.Start(r.Context(), "upload")
defer span.End() // 必须放最外层 defer，不能只包在 success 分支里
if err := r.ParseMultipartForm(32 << 20); err != nil {
span.RecordError(err)
http.Error(w, "parse failed", http.StatusBadRequest)
return
}
// ... 处理逻辑
}
- 不要在
if ctx.Err() != nil分支里才调span.End()—— 那样 span 已泄露 - 超时错误本身应作为
span.RecordError()上报，而不是仅打日志 - 若上传分块（如 tus 协议），每个 chunk 的 trace 应继承父 span，且每个 chunk 的 timeout 独立控制
超时不是终点，而是链路可观测性的起点——没记录清楚的超时，等于没设超时。
