Context.WithTimeout不能直接用于Echo handler，因Echo不监听子context.Done()；应使用echo.Timeout中间件统一控制超时，手动包装需显式检查ctx.Done()并defer cancel()。
Context.WithTimeout 不能直接用在 Echo 的 handler 中
Echo 的 echo.Context 本身不提供原生的超时控制方法，它也不是从 context.Context 派生出来的可取消上下文；你不能直接对 c.Request().Context() 调用 WithTimeout 并期望它中断 handler 执行——因为 Echo 不监听这个子 context 的 Done() 信号。
真正起作用的是 Echo 自己的超时中间件机制，而不是手动包装 request context。
用 echo.Timeout 中间件统一控制 handler 超时
echo.Timeout 是官方提供的、与 Echo 生命周期深度集成的超时方案。它会在 handler 执行超过指定时间后主动调用 http.CloseNotify（或等效机制），并终止响应流，同时触发错误回调。
Echo框架 5.1.0
下载
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 超时时间单位是
time.Duration，比如5 * time.Second - 必须配合
echo.HTTPError错误处理逻辑，否则超时错误会被静默吞掉 - 它只对当前路由或路由组生效，不是全局默认行为
- 底层依赖 Go HTTP server 的
WriteTimeout和连接状态检测，对长连接、流式响应（如 SSE）支持有限
// 示例：为某条路由加 3 秒超时
e.GET("/api/data", func(c echo.Context) error {
time.Sleep(4 * time.Second) // 故意超时
return c.String(http.StatusOK, "done")
}).Use(middleware.TimeoutWithConfig(middleware.TimeoutConfig{
Timeout: 3 * time.Second,
ErrorHandler: func(err error, c echo.Context) error {
return c.JSON(http.StatusGatewayTimeout, map[string]string{
"error": "request timeout",
})
},
}))
手动包装 Context 需要自己检查 Done() 并提前返回
如果你坚持要在 handler 内部用 context.WithTimeout（例如调用下游服务时做细粒度控制），必须显式监听 ctx.Done() 并主动退出，Echo 不会帮你中断执行。
- 不要只创建带超时的 context，却忽略
select或ctx.Err()判断 - 数据库查询、HTTP client 请求等需传入该 context，否则超时无意义
- 注意：handler 返回后，超时 context 的 goroutine 仍可能继续运行，造成资源泄漏
- 常见错误是写了
ctx, cancel := context.WithTimeout(...)却忘了defer cancel()
func(c echo.Context) error {
ctx, cancel := context.WithTimeout(c.Request().Context(), 2*time.Second)
defer cancel()
<pre class="brush:php;toolbar:false;">select {
case <-time.After(3 * time.Second):
return c.String(http.StatusOK, "slow but done")
case <-ctx.Done():
return echo.NewHTTPError(http.StatusRequestTimeout, "subtask timeout")
}}
超时和 WriteTimeout / ReadTimeout 的关系容易混淆
Echo 启动时设置的 e.Server.WriteTimeout 是 TCP 连接级别的写超时，影响整个 response body 发送过程；而 echo.Timeout 中间件是 handler 执行逻辑的超时，两者不互斥但作用域不同。
- 如果 handler 在 10s 内完成，但 response body 很大、网络很慢，
WriteTimeout仍可能触发关闭连接 -
echo.Timeout不影响 header 写入后的流式响应（如c.Stream()），此时应靠 client 端或反向代理控制 - Docker/K8s 环境下，还可能存在 LB 层（如 Nginx、ALB）自己的 idle timeout，它比 Echo 层级更高，且无法被中间件覆盖
真正难调试的，往往是多层 timeout 叠加导致的“看起来没超时却断连”——得逐层确认 echo.Timeout、Server.WriteTimeout、反向代理配置、客户端 timeout 设置是否一致。
