echo.httperrorhandler无法捕获超时错误，因为net/http底层超时（如readheadertimeout、idletimeout）会直接关闭连接，请求未进入echo中间件链；真正的超时控制应通过http.server配置或在handler内用context.withtimeout()派生子context并返回echo.newhttperror触发错误处理。
echo.HTTPErrorHandler 无法捕获超时错误？
超时错误根本不会走到 echo.HTTPErrorHandler，因为 net/http 的底层连接在超时后直接关闭，请求甚至没进入 Echo 的中间件链。你看到的 context deadline exceeded 实际来自 http.Server 自身的超时机制，和 Echo 的 Context.SetTimeout() 是两套逻辑。
真正起作用的是 http.Server 的三个超时字段：ReadTimeout、WriteTimeout、IdleTimeout（Go 1.8+ 推荐用 ReadHeaderTimeout 和 IdleTimeout 替代前两者）。Echo 只是封装了 http.Server，没重写底层连接生命周期。
-
ReadHeaderTimeout：从连接建立到读完请求头的最大时间，防慢速攻击 -
IdleTimeout：两次请求之间允许的最大空闲时间（HTTP/1.1 keep-alive 场景） -
WriteTimeout：从开始写响应到写完的总时间（含 flush），但不包含读请求头或 body 的时间
如何给单个 handler 设置上下文超时？
用 c.Request().Context() 派生带超时的子 context，再传给下游调用（如数据库查询、HTTP 调用）。注意：这不会中断正在写的 HTTP 响应，只影响你主动使用的 context-aware 操作（比如 db.QueryContext() 或 http.Client.Do()）。
示例：
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
func timeoutHandler(c echo.Context) error {
// 为当前 handler 设置 3 秒业务超时
ctx, cancel := context.WithTimeout(c.Request().Context(), 3*time.Second)
defer cancel()
// 所有依赖 context 的操作都用 ctx
result, err := someService.Do(ctx)
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
return echo.NewHTTPError(http.StatusRequestTimeout, "service timeout")
}
return err
}
return c.JSON(http.StatusOK, result)
}
- 别在 handler 外层用
context.WithTimeout(c.Context(), ...)——c.Context()已被 Echo 包装，取消它可能干扰 Echo 内部逻辑 - 务必调用
defer cancel()，否则 goroutine 泄漏 - 超时后返回
echo.NewHTTPError()，Echo 才会走自定义错误处理器；直接 panic 或返回原始 error 不触发HTTPErrorHandler
全局超时 + 中间件组合容易踩的坑
有人用中间件对所有请求统一加 context.WithTimeout()，结果发现健康检查接口也超时失败。问题在于：超时是按 handler 入口统一设的，但不同接口实际耗时差异极大。
- 不要在顶层中间件硬编码超时值，尤其不能覆盖
/health、/metrics这类低开销接口 - 如果必须用中间件控制，按路径前缀或路由组区分，例如：
if strings.HasPrefix(c.Path(), "/api/v1/") { ... } -
echo.TimeoutWithConfig()中间件存在严重缺陷：它基于time.AfterFunc()触发 cancel，但无法保证 goroutine 立即退出；且超时后仍会继续执行 handler 剩余代码（只是 context 已 cancel），容易引发并发写 response 或 panic
更稳妥的做法是：只在明确需要超时控制的 handler 内部做 context.WithTimeout()，而不是靠中间件兜底。
客户端看到 504 还是 503？取决于谁先超时
如果你的 Echo 服务上游还有反向代理（Nginx、ALB、Cloudflare），最终返回给用户的错误码由「最先超时的一方」决定：
- Nginx 的
proxy_read_timeout设为 10s，Echo 的WriteTimeout设为 30s → 客户端收到 504 Gateway Timeout - Echo 的
ReadHeaderTimeout设为 2s，Nginx 未设限制 → 客户端收到 408 Request Timeout（由 Echo 返回） - 业务 handler 内部
context.WithTimeout()触发，且你返回了echo.NewHTTPError(http.StatusServiceUnavailable)→ 客户端收到 503
排查时优先查 curl -v 的状态码和响应头 X-Content-Type-Options 等是否来自你的服务，还是代理透传的。真实超时点藏在最短的那个 timeout 配置里。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
