默认的 echo.new() 不自动带请求id，因为 echo 设计轻量无状态，不内置请求追踪中间件；请求id需显式添加中间件生成并透传，否则日志和链路追踪中该字段为空或混乱。
为什么默认的 echo.New() 不会自动带请求ID
因为 Echo 的核心设计是轻量、无状态，echo.New() 创建的实例本身不注入任何中间件，包括请求追踪相关逻辑。你看到的请求 ID（如 X-Request-ID）必须显式添加中间件来生成和透传，否则所有日志、链路追踪里都只有空或随机 fallback 值。
常见错误现象：日志里 request_id 字段全为空、多个请求混在同一个 ID 下、下游服务收不到该 header。
- 别依赖第三方 logger 自动注入 —— Echo 的
echo.Logger不解析或生成请求 ID - 别在 handler 里手动
c.Set("req_id", ...)后就以为能全局取到 —— 中间件执行顺序错会导致取不到 - 若用
echo.HTTPErrorHandler统一处理错误，记得它发生在中间件链之后，此时c.Get("req_id")才可用
用 echo.MiddlewareFunc 实现轻量级请求 ID 中间件
不需要引入 uuid 包或外部库，Echo 内置的 echo.NewHTTPError 和 c.Request().Header.Get 就够用。关键是复用已有 header 或 fallback 生成，并统一挂载到 context。
func RequestID() echo.MiddlewareFunc {
return func(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
// 优先读取客户端传入的 X-Request-ID
reqID := c.Request().Header.Get(echo.HeaderXRequestID)
if reqID == "" {
// 生成 UUIDv4 格式字符串（用标准库 crypto/rand）
b := make([]byte, 16)
rand.Read(b)
reqID = fmt.Sprintf("%x-%x-%x-%x-%x",
b[0:4], b[4:6], b[6:8], b[8:10], b[10:16])
}
// 写回响应头 + 挂载到 context 供后续使用
c.Response().Header().Set(echo.HeaderXRequestID, reqID)
c.Set("req_id", reqID)
return next(c)
}
}
}
注意点：
-
echo.HeaderXRequestID是 Echo 预定义常量，值为"X-Request-ID"，直接用更安全 - 不要用
math/rand—— 它不是并发安全的，crypto/rand才适合生成 ID - 挂载
c.Set("req_id", ...)是为了在 handler 或自定义 logger 中快速获取，不是必须但强烈建议
如何让日志中间件正确打印请求 ID
如果你用了 echo.Logger 或自定义日志器，必须确保它在请求 ID 中间件之后注册，否则 c.Get("req_id") 取出来是 nil 或空字符串。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
错误顺序：
e.Use(echo.MiddlewareLogger) // ❌ 此时 req_id 还没生成 e.Use(RequestID())
正确顺序：
e.Use(RequestID()) // ✅ 先生成并挂载 e.Use(echo.MiddlewareLogger) // ✅ 此时可读取
如果用自定义 logger（比如结合 zap），记得在格式化时显式取值：
logger.Info("request handled",
"status", c.Response().Status,
"req_id", c.Get("req_id"), // 必须这样取，不能依赖 logger 自动推断
"path", c.Request().URL.Path)
- 别在 logger 中调用
c.Request().Header.Get(echo.HeaderXRequestID)—— 因为中间件可能已覆盖 header，而 context 挂载值才是最终态 - 如果启用了
echo.HTTPErrorHandler，它的c参数也携带"req_id"，可用于错误日志上下文对齐
生产环境要注意的兼容性与性能细节
这个中间件看似简单，但在高并发或代理穿透场景下容易出问题。关键不是“能不能跑”，而是“会不会漏”或“会不会冲突”。
- 反向代理（如 Nginx、Cloudflare）可能已设置
X-Request-ID，你的中间件要尊重上游，而不是覆盖 —— 上面示例已按此实现 - 避免在中间件里做耗时操作（如调用外部服务生成 ID），UUIDv4 本地生成是毫秒级安全的
- 如果用
echo.Group分路由，中间件注册位置影响作用域：全局e.Use()对所有路由生效；分组g.Use()只对子路由生效 - 某些 APM 工具（如 Datadog、Jaeger）要求 ID 格式为 16 进制且长度固定（如 32 位），上面的 UUIDv4 生成符合要求
最易被忽略的一点：如果你在中间件里修改了 Response().Header()，又启用了 echo.HTTPErrorHandler，那么错误响应头里的 X-Request-ID 仍会正确写出 —— 因为错误处理器是在中间件链结束后触发的，header 已写入缓冲区。但如果你手动调用 c.Error() 并提前结束，就得自己补 header。
