Echo 的 HTTPErrorHandler 捕获不到超时错误，因 net/http 底层超时（如 ReadHeaderTimeout）直接关闭连接，请求未进入 Echo 中间件链；真正生效的超时必须配置在 http.Server 实例上，而非 Echo 实例；单 handler 业务超时需用 context.WithTimeout(c.Request().Context(), ...) 并返回 echo.NewHTTPError() 才能触发自定义错误处理器。
echo.HTTPErrorHandler 捕获不到超时错误？
不是中间件写得不对，而是根本走不到它——net/http 底层的超时（如 ReadHeaderTimeout、IdleTimeout）会直接关闭连接，请求压根没进入 Echo 的中间件链。你看到的 context deadline exceeded 是 http.Server 自己抛的，和 c.SetTimeout() 无关。
全局超时必须配在 http.Server，不是 Echo 实例上
所有真正生效的超时控制都来自 http.Server 字段，Echo 只是封装。常见配置项及用途：
-
ReadHeaderTimeout：连接建立后，读完请求头的最大时间（防慢速攻击） -
IdleTimeout：HTTP/1.1 keep-alive 场景下，两次请求间的最大空闲时间 -
WriteTimeout：从开始写响应到写完的总时间（含Flush），不包含读请求头或 body 的时间
示例写法：
e := echo.New()
server := &http.Server{
Addr: ":8080",
Handler: e,
ReadHeaderTimeout: 5 * time.Second,
IdleTimeout: 60 * time.Second,
WriteTimeout: 30 * time.Second,
}
server.ListenAndServe()
单个 handler 要业务超时，用 context.WithTimeout() 派生子 context
这是唯一可控、可触发 echo.HTTPErrorHandler 的方式。注意三点：
Echo框架 5.1.0
下载
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 必须基于
c.Request().Context()派生，别用c.Context()（已被 Echo 包装，取消它可能干扰内部逻辑） - 务必调用
defer cancel()，否则 goroutine 泄漏 - 超时后要返回
echo.NewHTTPError()，才能进自定义错误处理器；直接返回原始 error 或 panic 不会触发
典型用法：
func timeoutHandler(c echo.Context) error {
ctx, cancel := context.WithTimeout(c.Request().Context(), 3*time.Second)
defer cancel()
result, err := db.QueryContext(ctx, "SELECT ...")
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
return echo.NewHTTPError(http.StatusRequestTimeout, "DB query timeout")
}
return err
}
return c.JSON(http.StatusOK, result)
}
别用中间件统一加 context.WithTimeout()，健康检查会挂
有人写一个“全局超时中间件”，对所有请求套 context.WithTimeout()，结果 /healthz 接口因超时失败——因为中间件无法区分路径语义，也没法跳过特定路由。
更安全的做法：
- 只在明确需要控制耗时的 handler 内部做
context.WithTimeout() - 若真要按路径分类，改用
e.Group("/api").Use(timeoutMiddleware)+ 白名单路由分组 - 健康检查等轻量接口，确保不经过任何带 context 超时的中间件或 handler
真正的难点不在怎么写，而在于判断哪个环节该由哪层超时兜底：连接层用 http.Server，业务调用层用 context.WithTimeout()，且两者不能互相替代或覆盖。
