Documentation
¶
Overview ¶
Package hmw 提供 trace_id 的 Hertz 中间件实现。
职责：
- 生成 trace_id 并注入 Hertz RequestContext 和标准 context.Context
- 提供从 RequestContext 提取 trace_id 的便捷函数
框架无关的核心定义（Key、HeaderKey、ContextWith）来自 github.com/oekit/tracing/traceid，本包通过 import 复用。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromRequestContext ¶
func FromRequestContext(c *app.RequestContext) string
FromRequestContext 从 Hertz RequestContext 中提取 trace_id。 trace_id 由 Middleware 注入到 RequestContext。 返回空字符串表示上下文中没有 trace_id（中间件未注册）。
func Middleware ¶
func Middleware() []app.HandlerFunc
Middleware 返回请求 ID 中间件链，负责 trace_id 的生成、透传与桥接。
采用社区标准实现 hertz-contrib/requestid 作为生成核心，并附加一层桥接， 将 requestid 生成的 ID 同步到 ekit 内部的两处存储，保证下游消费者零改动：
- Hertz RequestContext: c.Set(Key, ...)（供 FromRequestContext/health/version 读取）
- 标准 context.Context: traceid.ContextWith（供 logx.Ctx* / service 层 / NATS publisher 读取）
流程:
- requestid.New — 读取请求头 traceid.HeaderKey，缺失则生成 traceid.IDLength 位 ID，写入响应头
- bridge — 读取 requestid 写入的 ID，同步注入 c.Set 与标准 context
客户端 trace ID 白名单校验 ¶
客户端传入的 X-Trace-Id 经 validTraceID 白名单校验：非空、长度 ≤ 64、 字符集仅 [0-9a-zA-Z-]（本包生成 12 位十六进制、W3C trace-id 为 32 位十六进制， 弹性接受字母数字连字符格式；白名单防日志注入/ID 伪造关联）。 不在白名单的越界 ID（超长/任意字符/空）被静默丢弃并重新生成合法 ID， 三处注入（响应头 / RequestContext / 标准 context）保持一致，该请求 trace 链路不断。
必须搭配 RecoveryMiddleware ¶
本中间件只做 trace_id，不提供 panic 防护。Hertz 引擎级 recover 仅在 PanicHandler 非 nil 时才挂 defer（hertz pkg/route/engine.go ServeHTTP： `if engine.PanicHandler != nil { defer engine.recv(ctx) }`，server.New 不设默认 PanicHandler），netpoll 的 onProcess/onRequest 亦无 recover （cloudwego/netpoll connection_onevent.go）——handler panic 会直接冲垮 连接甚至进程。自定义中间件栈必须包含 mw.RecoveryMiddleware（或 mw.MinimalMiddleware / mw.DefaultMiddleware，均已内置）。
使用方式:
// 注册为最前置的中间件（在 ResponseMiddleware 之前） h.Use(hmw.Middleware()...) h.Use(mw.RecoveryMiddleware()) // 必须有：无 Recovery 的 panic = 断连/进程死
Types ¶
This section is empty.
Source Files