部署Gin请求超时必须三层协同：http.Server.ReadTimeout设连接级超时、context.WithTimeout中间件+业务层显式检查ctx.Err()并c.Abort()、Nginx等反向代理同步调大proxy_read_timeout和client_max_body_size，缺一不可。
部署 Gin 并设置请求超时，不能只改 http.Server.ReadTimeout 或依赖中间件“自动中断”，必须分三层处理：启动时的 HTTP 服务配置、路由级 context 超时控制、以及外部依赖（如 Nginx）协同。否则会出现“前端卡在 95%”“日志无报错但响应丢失”“超时了 handler 还在跑”等典型问题。
Go 启动时必须显式配置 http.Server 的 ReadTimeout
这是大文件上传、长连接、慢客户端场景的第一道防线。Gin 自身不接管连接读取，全靠底层 http.Server。Go 1.26+ 默认 ReadTimeout = 0（即不限制），但实际受 TCP keepalive 影响，可能在 2–5 分钟静默断连。
-
ReadTimeout控制从客户端开始发包到请求头+body 完全接收完成的时间，不是 handler 执行时间 - 必须在
http.Server实例上设置，不能只调gin.Engine.Run() - 示例写法：
srv := &http.Server{
Addr: ":8080",
Handler: router,
ReadTimeout: 10 * time.Minute, // ⚠️ 关键：上传大文件必须设
WriteTimeout: 30 * time.Second,
}
srv.ListenAndServe()不设这个，c.FormFile 可能根本没机会执行——请求在进 Gin 前就被底层关掉了。
用 context.WithTimeout 写中间件，但必须配合 c.Abort() 和业务层检查
这是控制单个请求 handler 执行时长的唯一可靠方式。ReadTimeout 是连接级，它不管你的 SQL 查了多久、下游 API 卡在哪；只有 context 能透传到 DB、HTTP Client、子 goroutine 里。
- 中间件只负责创建带超时的
ctx、替换c.Request、调c.Next()、检查ctx.Err()并立即c.Abort() -
c.Abort()缺失会导致后续中间件和 handler 继续执行，即使已超时 - 业务 handler 内仍要主动检查：
if c.Request.Context().Err() == context.DeadlineExceeded，否则 DB 查询、HTTP 调用不会停 - 若启了子 goroutine（如异步发 MQ），必须传入
c.Request.Context()并在循环中select { case <-ctx.Done(): return }
一个最小可用中间件示例：
func Timeout(d time.Duration) gin.HandlerFunc {
return func(c *gin.Context) {
ctx, cancel := context.WithTimeout(c.Request.Context(), d)
defer cancel()
c.Request = c.Request.WithContext(ctx)
c.Next()
if ctx.Err() == context.DeadlineExceeded {
c.Status(http.StatusGatewayTimeout)
c.String(http.StatusGatewayTimeout, "request timeout")
c.Abort() // ⚠️ 必须加
}
}
}Nginx 等反向代理必须同步调大 proxy_read_timeout 和 client_max_body_size
很多“超时”根本没进 Go 进程——Nginx 在 60 秒（默认值）就切断了连接。此时 Gin 日志里看不到任何请求记录，c.FormFile 永远不会被调用。
-
proxy_read_timeout：Nginx 等待上游（Gin）返回响应的最长时间，需 ≥ Gin 的ReadTimeout -
client_max_body_size：必须 ≥ 前端上传文件大小，否则直接返回 413，不是超时 - 示例 Nginx 配置段：
location /api/upload {
proxy_pass http://gin_backend;
proxy_read_timeout 600; # 10 分钟
client_max_body_size 1g;
}漏掉这一层，所有 Go 层的超时设置都白搭。
DB/HTTP Client 等依赖必须用 Context 版本接口
超时信号不会自动传播到第三方库。你传了 ctx，它们才可能响应；不传，就等于放弃控制。
- 数据库：必须用
db.QueryContext(ctx, ...)，而非db.Query(...) - HTTP 调用：必须用
req = req.WithContext(c.Request.Context())，再client.Do(req) - 自定义
http.Transport时，DialContext、TLSHandshakeTimeout也得配合ctx，否则连接卡住时信号传不下去 - 手动
time.Sleep或纯 CPU 计算不会响应ctx.Done()，需定期select检查
最容易被忽略的是：超时不是“时间到了就停”，而是“信号发出 + 底层组件协作”。TCP 层要重设 SetReadDeadline，DB 驱动要支持 Context，HTTP Client 要传对 ctx——缺一不可。
