必须在handler开头调用context.WithTimeout，因为Echo的echo.Context不自带可取消context，仅c.Request().Context()是信号源；延迟派生会导致中间耗时操作（如DB查询）无法响应超时。
为什么 context.WithTimeout 必须在 handler 开头就调用
因为 Echo 的 echo.Context 默认不携带可取消的 context.Context，它只是个封装，底层的 Request.Context() 才是真正的信号源。如果你在 handler 中间才创建带超时的 context，中间已执行的耗时操作（比如 DB 查询、HTTP 调用）完全不受控——它们仍在用原始 request context，cancel 信号根本传不到。
正确做法是：一进 handler 就基于 c.Request().Context() 派生新 context，并设好超时：
func myHandler(c echo.Context) error {
// 立即派生，5 秒超时
ctx, cancel := context.WithTimeout(c.Request().Context(), 5*time.Second)
defer cancel() // 别漏 defer！
// 后续所有依赖 context 的操作都用 ctx
data, err := fetchFromDB(ctx, "user_123")
if err != nil {
return c.JSON(http.StatusServiceUnavailable, map[string]string{"error": "db timeout"})
}
return c.JSON(http.StatusOK, data)
}
- 超时时间应略小于反向代理（如 Nginx）或 API 网关设置的 upstream timeout，避免 Echo 还在处理而上游已断连
-
defer cancel()是硬性要求；不调用会导致 goroutine 泄漏，尤其在高并发下会迅速耗尽内存 - 不要用
time.AfterFunc或手动 timer 替代context.WithTimeout，它无法触发下游 I/O 的自动中断（比如http.Client的Do会响应 cancel）
如何让 Echo 的中间件也感知 context 取消
Echo 的中间件默认运行在 handler 之前，但它的 echo.Context 不会自动继承你 handler 里创建的超时 context。如果中间件里有阻塞操作（比如 JWT 解析时调用远程密钥服务），它可能卡住整个请求链路，且无法被 handler 的 cancel 触发中断。
解决方案是：把超时 context 注入到 echo.Context 中，并在中间件里显式使用它：
立即学习“go语言免费学习笔记（深入）”；
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
// 自定义中间件，优先于业务 handler 执行
func timeoutMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
// 在中间件里也建超时 context（与 handler 一致）
ctx, cancel := context.WithTimeout(c.Request().Context(), 3*time.Second)
defer cancel()
// 把它存进 echo.Context，供后续中间件或 handler 取用
c.Set("timeout_ctx", ctx)
return next(c)
}
}
// handler 中取用
func myHandler(c echo.Context) error {
ctx := c.Get("timeout_ctx").(context.Context) // 类型断言需谨慎
data, err := callExternalAPI(ctx)
// ...
}
- 中间件中的超时时间建议比 handler 更短（比如 3s vs 5s），防止中间件吃掉大部分 budget
- 用
c.Set()传递 context 是可行的，但要注意并发安全——echo.Context是 per-request 的，无需额外锁 - 避免在中间件里做长时间同步操作；更推荐把重逻辑下沉到 handler，并统一用同一个超时 context 控制
echo.HTTPError 和 context cancel 的错误类型冲突怎么处理
当 context 被 cancel，ctx.Err() 返回 context.Canceled 或 context.DeadlineExceeded，但 Echo 默认的错误处理器会把它们当成普通 error 渲染成 500 响应。这不符合语义——超时应该返回 408 或 503，且不应记录为 panic 级别日志。
必须自定义 HTTPErrorHandler，显式识别 context 错误：
e.HTTPErrorHandler = func(err error, c echo.Context) {
code := http.StatusInternalServerError
message := "Internal Server Error"
// 优先检查 context 相关错误
if errors.Is(err, context.Canceled) {
code = http.StatusRequestTimeout
message = "Request canceled"
} else if errors.Is(err, context.DeadlineExceeded) {
code = http.StatusServiceUnavailable
message = "Request timeout"
} else if he, ok := err.(*echo.HTTPError); ok {
code = he.Code
message = he.Message
}
// 记录日志时过滤掉预期的 cancel/timeout 错误，避免刷屏
if !errors.Is(err, context.Canceled) && !errors.Is(err, context.DeadlineExceeded) {
log.Printf("HTTP %d: %v", code, err)
}
c.Logger().Error(err)
c.JSON(code, map[string]string{"error": message})
}
-
errors.Is是关键，不能用==直接比较，因为 context 错误是 wrapped error - 注意区分
context.Canceled（客户端主动断开）和context.DeadlineExceeded（服务端超时），它们的 HTTP 状态码语义不同 - 日志中跳过这两类错误，否则监控系统会被海量“超时”日志淹没，真正的问题反而被掩盖
HTTP 客户端调用外部服务时漏传 context 的典型表现
很多开发者在 handler 里用了 context.WithTimeout，却在调用 http.Client.Do 时仍传原始 c.Request().Context()，导致外部请求完全不响应超时信号。现象是：Echo handler 已返回 503，但后台 goroutine 仍在等待远端响应，甚至几分钟后才结束。
根本原因是 http.Client 只在发起请求那一刻读取 context；之后 context cancel 不会影响正在进行的 TCP 连接或 TLS 握手。
- 务必用派生出的超时 context 构造
http.Request：req.WithContext(ctx) - 给
http.Client设置Timeout字段是冗余的，且优先级低于 context；只设Timeout而不传 context，cancel 依然无效 - 若用第三方 SDK（如 AWS SDK Go），确认其方法是否接受
context.Context参数；不接受的 SDK 无法被优雅中断，得换或加 wrapper
最易忽略的一点：数据库驱动（如 pgx、mysql）的查询方法，必须显式传入带超时的 context，否则 query 会一直挂起，直到连接池超时或 TCP keepalive 断连——那通常要几分钟。
