超时需按 handler 粒度用 context.WithTimeout 控制，而非依赖全局 Read/WriteTimeout；各路由应显式创建带超时的 context 并传入下游，超时后返回 504，同时确保资源释放与 goroutine 安全。
超时不是全局配置，而是按 handler 粒度控制
很多人以为 e.Server.ReadTimeout 或 e.Server.WriteTimeout 能给某个路由单独设超时，其实不能——那是整个 HTTP server 的底层连接级超时，影响所有请求，且无法按路径区分。真正能实现「不同路由不同超时」的，只有在 handler 内部用 context.WithTimeout() 主动控制业务逻辑执行时长。
用 context.WithTimeout 包裹业务调用是最可靠方式
比如一个用户查询接口可以容忍 5 秒，而导出报表接口允许 60 秒，就得在各自 handler 里显式创建带超时的 context，并传给 service 层或下游调用：
- 别直接用
c.Request().Context()做长期操作，它可能被客户端断开或继承自父级 server 超时 - 统一用
ctx, cancel := context.WithTimeout(c.Request().Context(), 5*time.Second)，并在 defer 中调用cancel() - 所有依赖 context 的操作（如 DB 查询、HTTP client.Do、channel receive）都会在超时后自动中断
- 超时后返回
echo.NewHTTPError(http.StatusGatewayTimeout, "request timeout")，避免裸奔 panic
示例片段：
e.GET("/api/users/:id", func(c echo.Context) error {
ctx, cancel := context.WithTimeout(c.Request().Context(), 5*time.Second)
defer cancel()
user, err := userService.GetByID(ctx, c.Param("id"))
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
return echo.NewHTTPError(http.StatusGatewayTimeout, "fetch user timeout")
}
return echo.NewHTTPError(http.StatusInternalServerError, err.Error())
}
return c.JSON(http.StatusOK, user)
})
别碰 net/http.Transport 超时来“模拟”路由级超时
有人试图在中间件里替换 c.Response().Writer 或改写 http.Client 的 Timeout/Deadline 字段，这是危险的：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
-
http.Client.Timeout是整个请求生命周期（DNS + dial + TLS + write + read），无法区分是卡在上游还是自己 handler 里 - 若你在中间件里为每个请求 new 一个 client 并设不同 Timeout，会绕过连接池，导致大量 TIME_WAIT 和 fd 耗尽
- 更隐蔽的问题：Echo 的
c.Request().WithContext()不会自动同步到你手动构造的 client 请求中，context 传递断裂
结论：Transport 层超时只适用于「调用外部服务」这一子场景，且应由 service 层按需配置，绝不该用来替代 handler 内部的业务超时控制。
注意 context 超时与 HTTP 状态码的匹配关系
Go 标准库和 Echo 对 context 超时的响应不一致，容易导致前端收不到预期状态码：
- 如果只是用
ctx, _ := context.WithTimeout(...)但没检查errors.Is(err, context.DeadlineExceeded)，DB 或 HTTP client 返回的可能是context canceled，最终被 Echo 默认转成 500 -
http.StatusRequestTimeout (408)语义是「客户端发得太慢」，不是服务端处理超时；正确应返回http.StatusGatewayTimeout (504)或http.StatusServiceUnavailable (503) - 如果你用了第三方中间件（如 zap 日志），记得在日志里记录是否因 context 超时退出，否则线上排查时根本分不清是慢 SQL 还是网络抖动
真正的复杂点不在怎么设超时，而在于——超时之后，资源有没有被干净释放？goroutine 是否泄漏？数据库连接是否归还？这些都得靠你亲手验证，框架不会替你兜底。
