正确姿势是在 handler 内用 context.withtimeout 主动控制执行边界，因 gin 同步执行且无内置取消机制；需检查 ctx.err()、传递 ctx 给第三方库、定期 select 检查、封装超时中间件并调用 c.abort()。
Gin 中设置单个请求超时的正确姿势
不能靠 http.Server.ReadTimeout 或 WriteTimeout —— 那是连接级超时，对已进入路由处理的请求完全无效。真正起作用的是在 handler 内部用 context.WithTimeout 主动控制执行边界。
为什么必须用 context.WithTimeout 而不是中间件全局设 deadline
因为 Gin 的 handler 是同步执行的，没有内置异步取消机制；超时必须由业务逻辑主动响应 ctx.Done() 信号。常见错误是只调用 ctx.WithTimeout 却没检查 ctx.Err()，结果超时了但 handler 还在跑、资源没释放、响应也没发。
- 所有耗时操作（DB 查询、HTTP 调用、文件读写）必须接收并传递
ctx参数 - 第三方库如
database/sql、net/http.Client都支持ctx，不传就等于放弃超时控制 - 手动 sleep 或纯 CPU 计算不会响应
ctx.Done()，需定期用select检查
一个安全可用的超时 handler 封装示例
别在每个路由里重复写 context.WithTimeout，封装成中间件更可靠，但注意：它只能设置子 context，不能替你中断正在运行的 goroutine。
func Timeout(duration time.Duration) gin.HandlerFunc {
return func(c *gin.Context) {
ctx, cancel := context.WithTimeout(c.Request.Context(), duration)
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() // 阻止后续 handler 执行
}
}
}
使用：router.GET("/api/data", Timeout(5*time.Second), dataHandler)
-
c.Abort()必须加，否则c.Next()后续 handler 仍会执行 - 这个中间件只负责设 context 和兜底响应，具体业务逻辑里仍要检查
ctx.Err() - 如果 handler 内部启动了子 goroutine，必须显式传入
ctx并监听取消
容易被忽略的坑：time.Timer + select 不等于超时保障
有人用 time.AfterFunc 或 select { case 模拟超时，这在 Gin 里非常危险——它和 HTTP 连接生命周期脱钩，可能响应已写出后 timer 才触发，甚至引发 panic。
- 永远优先用
context.Context，它是 Go 生态事实标准 -
http.TimeoutHandler是 net/http 原生封装，Gin 不兼容（会绕过所有中间件和 context） - 超时时间建议设为略大于 P95 业务延迟，避免大量正常请求被误杀
最复杂的点其实是业务代码里那些没适配 ctx 的老逻辑，它们才是超时失效的根源。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
