trace

package
v1.3.15 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

README

logger/trace — 链路追踪集成

为 logger 包提供链路追踪能力:自动生成/透传 Request ID,并把它自动打印到每条日志中。完全兼容现有日志 API,无破坏性变更。

  • 📦 零侵入:业务代码只需 logger.Ctx(ctx).Info(...) 一行即可打印带 Request ID 的日志
  • 🚀 高性能:基于 zap 派生 logger,Ctx(空 ctx) 零分配;带追踪的日志调用约 500ns
  • 🧩 多框架:开箱支持 net/http、Gin、Fiber v3、go-restful、gRPC
  • 🆔 NanoID:默认使用 21 字符 URL-safe NanoID 作为 Request ID(比 UUID 更短、碰撞概率更低)
  • 🎯 格式优雅:
    • Console:... INFO xxx.go:42 [request_id:abc] 消息
    • JSON:{"msg":"消息","request_id":"abc",...}

目录结构

logger/
├── logger.go                   # 核心 logger(已有,本次未修改)
├── ctx_logger.go               # 新增:MyLogger.Ctx(ctx) / WithTrace(...)
└── trace/
    ├── trace.go                # TraceConfig / TraceField / Context 存取
    ├── generator.go            # NanoID / UUID 生成器
    ├── extractor.go            # 字段提取器(Header/Query/Cookie/Metadata/Chain)
    ├── process.go              # 所有中间件共享的处理核心
    └── middleware/
        ├── http.go             # net/http
        ├── gin.go              # Gin
        ├── fiber.go            # Fiber v3
        ├── restful.go          # go-restful v3
        └── grpc.go             # gRPC Unary + Stream

快速开始

1. 最简用法(Gin 为例)
package main

import (
    "gitee.com/hexug/go-tools/logger"
    "gitee.com/hexug/go-tools/logger/trace"
    "gitee.com/hexug/go-tools/logger/trace/middleware"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.New()
    // 一行接入,开箱即用
    r.Use(middleware.Gin(trace.DefaultConfig()))

    r.GET("/hello", func(c *gin.Context) {
        logger.Ctx(c.Request.Context()).Infof("hello %s", c.Query("name"))
        c.String(200, "ok")
    })
    r.Run(":8080")
}

日志输出(Console 格式):

2026-05-05T12:06:07.684+0800	INFO	main.go:15	[request_id:V1StGXR8_Z5jdHi6B-myT] hello alice

响应头:X-Request-Id: V1StGXR8_Z5jdHi6B-myT

💡 小贴士:Gin 中间件会把追踪字段同步写入 c.Keys,因此以下三种写法完全等价:

logger.Ctx(c).Info("hi")                      // ✅ 直接传 *gin.Context(推荐,最简洁)
logger.Ctx(c.Request.Context()).Info("hi")    // ✅ 传标准 ctx(业务层解耦推荐)
rid := c.GetString("request_id")              // ✅ Gin 原生 API 读取

2. JSON 格式下自动成为独立字段

切换为 JSON 输出后,所有追踪字段会从 Console 的 [k:v, ...] 前置标签转为独立顶层字段,便于日志采集系统按字段索引、聚合。下例展示开启 JSON 格式后 Infow 的真实输出:

logger.UseJSONFormat = true
logger.Update()

logger.Ctx(ctx).Infow("login", "user", "alice")

输出:

{"level":"INFO","ts":"...","caller":"main.go:20","msg":"login","request_id":"V1StGXR...","user":"alice"}

3. 全框架集成示例

本段展示除 Gin 外其它 4 个内置中间件的最小接入示例,所有中间件签名一致:middleware.<框架>(trace.DefaultConfig()),可直接复制到现有项目。

net/http

标准库 net/http 用包装 http.Handler 的方式接入,中间件返回类型为 func(http.Handler) http.Handler:

handler := middleware.HTTP(trace.DefaultConfig())(myHandler)
http.ListenAndServe(":8080", handler)
Fiber v3
app := fiber.New()
app.Use(middleware.Fiber(trace.DefaultConfig()))
app.Get("/hello", func(c fiber.Ctx) error {
    logger.Ctx(c).Info("hi")          // 直接传 fiber.Ctx 即可
    return c.SendString("ok")
})

💡 Fiber 中间件会把追踪字段同步写入 c.Locals,以下三种写法等价:

logger.Ctx(c).Info("hi")                      // ✅ 直接传 fiber.Ctx
logger.Ctx(c.Context()).Info("hi")            // ✅ 传标准 ctx
rid, _ := c.Locals("request_id").(string)     // ✅ Fiber 原生 API
go-restful
container := restful.NewContainer()
container.Filter(middleware.Restful(trace.DefaultConfig()))

ws.Route(ws.GET("/hello").To(func(req *restful.Request, resp *restful.Response) {
    // 注意:*restful.Request 未实现 context.Context,需传 req.Request.Context()
    logger.Ctx(req.Request.Context()).Info("hi")
    // 也可通过 go-restful 原生 Attribute 读取
    rid, _ := req.Attribute("request_id").(string)
    _ = rid
}))
gRPC

Unary 和 Stream 两类调用各有独立拦截器,构建 Server 时同时注册即可同时支持普通 RPC 和流式 RPC:

srv := grpc.NewServer(
    grpc.UnaryInterceptor(middleware.GRPCUnaryServerInterceptor(trace.DefaultConfig())),
    grpc.StreamInterceptor(middleware.GRPCStreamServerInterceptor(trace.DefaultConfig())),
)

自定义配置

链式 API
cfg := trace.NewConfig().
    WithRequestID().       // 默认 request_id 字段
    WithTraceID().         // 额外添加 trace_id
    WithUserID().          // 额外添加 user_id(仅透传不生成)
    AddField(&trace.TraceField{
        Name:          "tenant_id",
        HeaderName:    "X-Tenant-Id",
        Extractor:     trace.HeaderExtractor("X-Tenant-Id"),
        WriteResponse: true,
    })

r.Use(middleware.Gin(cfg))

输出日志(多字段):

... INFO main.go:15 [request_id:abc, trace_id:xyz, user_id:u1, tenant_id:t1] hello
字段级选项

每个内置字段都支持通过 FieldOption 覆盖默认值:

cfg := trace.NewConfig().WithRequestID(
    trace.WithHeaderName("X-My-Req-Id"),                    // 自定义 header
    trace.WithGenerator(trace.NanoIDGenerator(32)),          // 自定义 32 位 NanoID
    trace.WithExtractor(trace.ChainExtractor(                // 混合提取策略
        trace.HeaderExtractor("X-My-Req-Id"),
        trace.QueryExtractor("rid"),
        trace.CookieExtractor("req_id"),
    )),
    trace.WithResponseWrite(false),                          // 不回写响应头
)
自定义提取器
// 从 Authorization 头解析 user id
tokenExtractor := trace.ExtractorFunc(func(s trace.ExtractSource) (string, bool) {
    auth := s.Headers("Authorization")
    if strings.HasPrefix(auth, "Bearer ") {
        return parseUserIDFromJWT(auth[7:]), true
    }
    return "", false
})

cfg := trace.DefaultConfig().WithUserID(trace.WithExtractor(tokenExtractor))

完整配置示例:多源追踪字段集成

以下示例展示如何在 Gin 服务中配置复杂的多源追踪字段,包括 Header、Query、Cookie 和 Body 等多种数据源。

场景需求
  • Request ID:支持多源提取(Header:X-Request-Id / X-Trace-Id / Trace-Id,Query:trace_id / request_id,Cookie:trace_id),全部缺失时生成 32 位 NanoID
  • Header 字段:user_id(默认 "anonymous")、session_id(默认 UUID)、client_version(默认 "unknown")
  • Query 参数:source、platform(仅透传,不生成默认值)
  • Cookie 字段:user_token、device_id、locale(均有默认值)
  • Body 业务字段:从 JSON 请求体中提取 group_id,仅解析 RESTful JSON 请求,对文件/媒体/超大包等自动跳过,杜绝 OOM 风险
核心实现
1. 健壮的 Body 提取器

仅对 Content-Type: application/json 且方法带 body 的请求做解析;用 io.LimitReader 限制读取量(默认 1MB)防止恶意大包;读取完立即把 body "塞回"到 Request.Body,保证后续 c.ShouldBindJSON 仍可正常工作;所有异常(非 JSON、畸形、字段缺失、IO 错误)一律静默降级为未命中。

package trace_config

import (
    "bytes"
    "encoding/json"
    "io"
    "net/http"
    "strings"

    "gitee.com/hexug/go-tools/logger/trace"
    "github.com/gin-gonic/gin"
)

const maxBodySniffSize = 1 << 20 // 1MB,防止恶意大包导致 OOM

// GroupIDFromBody 安全地从 JSON Body 中提取 group_id
//   - 仅处理 application/json 请求,文件/媒体/表单等一律跳过
//   - 限长读取 + body 回填,无副作用
//   - 兼容 "group_id":"g-1" 与 "group_id":123 两种写法
func GroupIDFromBody() trace.FieldExtractor {
    return trace.ExtractorFunc(func(s trace.ExtractSource) (string, bool) {
        c, ok := s.Raw.(*gin.Context)
        if !ok || c == nil || c.Request == nil || c.Request.Body == nil {
            return "", false
        }
        req := c.Request

        // 1) 过滤无 body 的方法
        switch req.Method {
        case http.MethodGet, http.MethodHead, http.MethodDelete, http.MethodOptions:
            return "", false
        }

        // 2) 严格校验 Content-Type,只处理 application/json
        ct := req.Header.Get("Content-Type")
        if i := strings.IndexByte(ct, ';'); i >= 0 {
            ct = ct[:i]
        }
        if !strings.EqualFold(strings.TrimSpace(ct), "application/json") {
            return "", false
        }

        // 3) 限长读取
        raw, err := io.ReadAll(io.LimitReader(req.Body, maxBodySniffSize))
        // 4) 关键:立刻回填 body,保证后续 Handler 可再次读取
        req.Body = io.NopCloser(bytes.NewReader(raw))
        if err != nil || len(raw) == 0 {
            return "", false
        }

        // 5) 仅探测 group_id,避免全量反序列化
        var probe struct {
            GroupID json.RawMessage `json:"group_id"`
        }
        if err := json.Unmarshal(raw, &probe); err != nil {
            return "", false
        }
        v := bytes.TrimSpace(probe.GroupID)
        if len(v) == 0 || bytes.Equal(v, []byte("null")) {
            return "", false
        }

        // 6) 兼容 string / number 两种类型
        var asStr string
        if err := json.Unmarshal(v, &asStr); err == nil && asStr != "" {
            return asStr, true
        }
        if v[0] == '-' || (v[0] >= '0' && v[0] <= '9') {
            return string(v), true
        }
        return "", false
    })
}
2. 完整配置构建
func BuildTraceConfig() *trace.TraceConfig {
    return trace.NewConfig().
        // Request ID:多源提取 + 32 位 NanoID 兜底
        WithRequestID(
            trace.WithHeaderName("X-Request-Id"),
            trace.WithGenerator(trace.NanoIDGenerator(32)),
            trace.WithExtractor(trace.ChainExtractor(
                trace.HeaderExtractor("X-Request-Id", "X-Trace-Id", "Trace-Id"),
                trace.QueryExtractor("trace_id", "request_id"),
                trace.CookieExtractor("trace_id"),
            )),
            trace.WithResponseWrite(true),
        ).
        // Header 字段(均带默认生成器)
        AddField(&trace.TraceField{
            Name:       "user_id",
            HeaderName: "X-User-Id",
            Extractor:  trace.HeaderExtractor("X-User-Id"),
            Generator:  func() string { return "anonymous" },
            Required:   true,
        }).
        AddField(&trace.TraceField{
            Name:       "session_id",
            HeaderName: "X-Session-Id",
            Extractor:  trace.HeaderExtractor("X-Session-Id"),
            Generator:  trace.UUIDGenerator(),
            Required:   true,
        }).
        AddField(&trace.TraceField{
            Name:       "client_version",
            HeaderName: "X-Client-Version",
            Extractor:  trace.HeaderExtractor("X-Client-Version"),
            Generator:  func() string { return "unknown" },
            Required:   true,
        }).
        // Query 参数(仅透传,缺失则不打印)
        AddField(&trace.TraceField{
            Name:      "source",
            Extractor: trace.QueryExtractor("source"),
        }).
        AddField(&trace.TraceField{
            Name:      "platform",
            Extractor: trace.QueryExtractor("platform"),
        }).
        // Cookie 字段(均带默认生成器)
        AddField(&trace.TraceField{
            Name:      "user_token",
            Extractor: trace.CookieExtractor("user_token"),
            Generator: func() string { return "" },
        }).
        AddField(&trace.TraceField{
            Name:      "device_id",
            Extractor: trace.CookieExtractor("device_id"),
            Generator: func() string { return "unknown-device" },
            Required:  true,
        }).
        AddField(&trace.TraceField{
            Name:      "locale",
            Extractor: trace.CookieExtractor("locale"),
            Generator: func() string { return "zh-CN" },
            Required:  true,
        }).
        // Body 业务字段(静默失败,不生成兜底)
        AddField(&trace.TraceField{
            Name:      "group_id",
            Extractor: GroupIDFromBody(),
        })
}
3. Gin 中间件集成
r := gin.New()
r.Use(middleware.Gin(BuildTraceConfig()))

r.POST("/api/orders", func(c *gin.Context) {
    ctx := c.Request.Context()
    // 业务代码中自动携带追踪字段
    logger.Ctx(ctx).Infow("业务日志", "key", "value")

    // Body 提取器已回填 body,此处仍可正常 Bind
    var body struct{ GroupID string `json:"group_id"` }
    _ = c.ShouldBindJSON(&body)
    c.JSON(200, gin.H{"ok": true})
})
日志输出效果
Console 格式
2026-05-05T13:26:34.684+0800    INFO    main.go:25    [request_id:req-123, user_id:u-1001, session_id:550e8400-..., client_version:2.3.4, source:web, platform:ios, device_id:dev-xyz, locale:zh-CN, group_id:g-555] 业务日志    {"key": "value"}
JSON 格式
{
  "level": "INFO",
  "ts": "2026-05-05T13:26:34.684+0800",
  "caller": "main.go:25",
  "msg": "业务日志",
  "request_id": "req-123",
  "user_id": "u-1001",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_version": "2.3.4",
  "source": "web",
  "platform": "ios",
  "device_id": "dev-xyz",
  "locale": "zh-CN",
  "group_id": "g-555",
  "key": "value"
}
关键特性说明
  1. 优先级机制:ChainExtractor 按配置顺序短路执行,第一个命中即停止,Extractor 永远优先于 Generator。
  2. 健壮性设计:Body 提取器对非 JSON 请求、畸形 JSON、超大包、IO 异常等全部静默降级,不影响正常请求流程。
  3. 无副作用:读取 Body 后立即用 io.NopCloser(bytes.NewReader(raw)) 回填,后续 ShouldBindJSON / BindJSON 不受干扰。
  4. 防 OOM:io.LimitReader(1MB) 为 Body 读取封顶,文件上传 / 媒体流 / 恶意大包均被隔离在业务层之外。
  5. 灵活配置:每个字段独立配置提取策略、默认值生成器和响应回写开关。
  6. 格式自适应:同一份 TraceConfig 自动适配 Console([field:value, ...] 前置标签)和 JSON(独立顶层字段)两种输出。
响应头回写

配置了 HeaderName 且 WriteResponse=true 的字段会自动回写到响应头,便于下游服务/网关/前端做链路关联:

HTTP/1.1 200 OK
X-Request-Id: req-123
X-User-Id: u-1001
X-Session-Id: 550e8400-e29b-41d4-a716-446655440000
X-Client-Version: 2.3.4

业务字段(如 source、group_id)未配 HeaderName 或 WriteResponse=false,不会回写,避免敏感信息泄漏。


ID 生成器

内置生成器
生成器 默认长度 字母表 说明
NanoIDGenerator(21) 21 A-Za-z0-9_- 默认,URL-safe,126 bit 熵
NanoIDGeneratorCustom(alphabet, size) 自定义 自定义 如 NanoIDGeneratorCustom("0123456789", 10)
UUIDGenerator() 36 UUID v4 传统 36 字符带连字符格式
自定义生成器
// Snowflake、ULID 等任意实现都可接入
cfg := trace.NewConfig().WithRequestID(
    trace.WithGenerator(func() string {
        return mySnowflake.Generate().String()
    }),
)

Context 传参的三种等价写法

在 Gin / Fiber / go-restful 中,中间件不仅会把追踪字段写进 Request.Context(),还会同步写到框架的本地 KV(Gin c.Keys、Fiber c.Locals、go-restful req.Attribute)。配合 trace 内置的 ContextAdapter 机制,业务层有三种等价的取值方式,按需选择即可。

工作机制
┌──────────────────────────┐
│  请求进入中间件            │
└────────────┬─────────────┘
             ▼
┌──────────────────────────────────────────────┐
│ 1) 提取/生成追踪字段(按 TraceConfig 规则)   │
│ 2) ctx = context.WithValue(req.Context(), ...)│
│ 3) req = req.WithContext(ctx)                 │
│ 4) 同步写入框架本地 KV(c.Keys/c.Locals/...)  │
└──────────────────────────────────────────────┘
             ▼
┌──────────────────────────────────────────────┐
│ 业务层 logger.Ctx(x) 的查找路径:              │
│  ① 先 x.Value(traceBagKey{})  ← 标准 ctx 命中 │
│  ② 未命中则走 ContextAdapter  ← 框架 ctx 兜底 │
└──────────────────────────────────────────────┘

各框架中间件在 init() 中已自动注册对应的 ContextAdapter,无需用户手动处理。

三种写法对照表
框架 写法 A:直传框架 ctx 写法 B:传标准 ctx 写法 C:框架原生 API
Gin logger.Ctx(c).Info(...) ✅ logger.Ctx(c.Request.Context()).Info(...) ✅ c.GetString("request_id") ✅
Fiber logger.Ctx(c).Info(...) ✅ logger.Ctx(c.Context()).Info(...) ✅ c.Locals("request_id") ✅
go-restful ❌ *restful.Request 未实现 context.Context logger.Ctx(req.Request.Context()).Info(...) ✅ req.Attribute("request_id") ✅
net/http — logger.Ctx(r.Context()).Info(...) ✅ —
gRPC — logger.Ctx(ctx).Info(...) ✅ —
推荐用法
  • Handler 内部:直接传框架 ctx(写法 A)最简洁,少一次 .Request.Context() 链式调用。
  • 跨层调用 / Service 层:传标准 context.Context(写法 B),让下层与具体 Web 框架解耦,方便单测。
  • 读取单个追踪字段:如需在非日志场景获取(例如作为业务参数透传给第三方),选择当前框架最习惯的方式即可(写法 A 或 C)。
扩展自定义框架

若接入 Echo / Chi / Hertz 等新框架,只需在自定义中间件的 init() 中注册一个 ContextAdapter 即可让 logger.Ctx(框架ctx) 自动生效:

func init() {
    trace.RegisterContextAdapter(func(v any) (context.Context, bool) {
        if c, ok := v.(echo.Context); ok && c != nil {
            return c.Request().Context(), true
        }
        return nil, false
    })
}

trace 核心包零修改,原生支持任意 Web 框架。


Context 工具

API 作用
trace.WithRequestID(ctx, id) 写入 request_id(id 为空则自动生成)
trace.RequestIDFromContext(ctx) 读取 request_id
trace.EnsureRequestID(ctx) 确保 ctx 中有 request_id,返回 (新ctx, id)
trace.WithValue(ctx, name, val) 写入任意字段
trace.WithValues(ctx, map) 批量写入
trace.ValueFromContext(ctx, name) 读取任意字段
trace.ValuesFromContext(ctx) 读取全部字段(返回拷贝)

Logger 新增方法

方法 作用
logger.L().Ctx(ctx) 派生带追踪字段的临时 logger
logger.L().WithTrace(k1, v1, k2, v2) 手动附加追踪字段
logger.Ctx(ctx) 全局快捷(等价 L().Ctx(ctx))
logger.WithTrace(...) 全局快捷

派生的 logger 兼容所有现有方法:Info/Infof/Infow/Success/Fail/Successf/Failw/InfoWithIcon/... 全部支持,无需修改业务代码。

📌 关于 Ctx(ctx) 的参数:虽然签名是 Ctx(ctx context.Context),但得益于 ContextAdapter 机制,你可以直接传入 *gin.Context / fiber.Ctx 等框架对象——它们都实现了 context.Context 接口,且内部会被 adapter 正确解析。详见 Context 传参的三种等价写法。


异步/goroutine 安全

Go 的 context.Context 天然并发安全,但需要显式传递:

// ❌ 错误:丢失 request_id
go func() {
    logger.L().Info("async")
}()

// ✅ 正确
go func(ctx context.Context) {
    logger.Ctx(ctx).Info("async")
}(ctx)

性能基准

运行环境:AMD EPYC 9754 / Go 1.25

场景 耗时 分配
Ctx(空 ctx) 派生 9.6 ns/op 0 B / 0 allocs
Ctx(有ctx).Info(...) Console ~500 ns/op 640 B / 10 allocs
Ctx(有ctx).Info(...) JSON ~570 ns/op 688 B / 10 allocs
NanoIDGenerator(21) ~940 ns/op 72 B / 2 allocs
UUIDGenerator() ~830 ns/op 64 B / 2 allocs
Process(默认配置) ~360 ns/op 728 B / 6 allocs

设计原则

  1. 完全兼容:不修改 logger.go 任何现有行为;未使用 Ctx() 的日志路径性能零影响。
  2. 零依赖引入:只新增 github.com/google/uuid 从 indirect 变为 direct(已存在于 go.sum)。NanoID 用 crypto/rand 自研。
  3. 按需编译:中间件各框架相互独立,用户只 import 自己需要的,Go linker 自动裁剪未用框架的依赖。
  4. Context 优先:遵循 Go 官方最佳实践,不使用 goroutine-local 等 hack 手段。
  5. 对齐 OpenTelemetry:字段名、Header 名与 OTel 规范保持一致,未来可无缝对接。

FAQ

Q1:业务老代码怎么渐进迁移? 不需要改。老代码(logger.L().Infof(...))继续正常工作,只是不带 Request ID。需要追踪的新代码用 logger.Ctx(ctx).Infof(...) 即可。

Q2:跨服务调用时如何透传 Request ID? HTTP 下游调用前从 ctx 取出 id,写入 X-Request-Id 请求头;gRPC 下游用 metadata.AppendToOutgoingContext(ctx, "x-request-id", id)。后续版本会提供 Client 端中间件自动化。

Q3:为什么选择 NanoID? 21 字符 NanoID:

  • 比 UUID 短 40%(21 vs 36),日志可读性更好
  • 熵更高(126 bit vs UUID v4 的 122 bit)
  • URL-safe,可直接嵌入 URL 和文件名
  • 性能与 UUID 相当(均 ~800-900ns)

Q4:能否关闭响应头回写? 可以:trace.WithResponseWrite(false) 或直接构造 TraceField{WriteResponse: false}。

Q5:为什么 logger.Ctx(c)(c 是 *gin.Context)能拿到追踪字段?Gin 的 c.Value() 默认不会 fallback 到 Request.Context() 啊? 是的,Gin 默认 engine.ContextWithFallback = false,直接 c.Value(非string key) 会返回 nil。我们为此设计了 ContextAdapter 机制:ValuesFromContext 在标准路径取不到 bag 时,会调用已注册的 adapter 把 *gin.Context 解析成 c.Request.Context() 再查一次。Fiber、go-restful 同理。整个过程对用户透明,无需开启任何 Gin 配置。

Q6:中间件会把追踪字段同时写到框架的本地 KV 吗?会不会有性能损耗? 会同步写入(Gin 的 c.Keys、Fiber 的 c.Locals、go-restful 的 req.Attribute),方便业务通过框架原生 API 读取。每个字段多一次 map 写入,开销在纳秒级,可忽略。若你确定不需要该能力,可自行 fork 中间件代码去掉对应循环。

Q7:Fiber 里 ctx.Get("request_id") 为什么拿不到?但 ctx.Locals / ctx.Value / logger.Ctx(ctx) 都正常。 这是 Fiber 的 API 语义问题,不是本库的 bug。Fiber 模仿了 Express.js 的设计,ctx.Get(key) 读的是 HTTP Request Header,而不是请求级 KV 存储。几种 API 的区别如下:

写法 数据源 能否拿到 request_id
ctx.Get("request_id") HTTP Request Header ❌ 除非客户端正好传了同名 header
ctx.Get("X-Request-Id") HTTP Request Header ⚠️ 仅当请求本身带了该 header
ctx.Locals("request_id") Fiber 本地 KV ✅ 中间件已同步写入
ctx.Value("request_id") Context(Fiber 会 fallback) ✅ 来自 bag
trace.RequestIDFromContext(ctx.Context()) bag ✅ 标准路径
logger.Ctx(ctx).Info(...) bag(经 ContextAdapter) ✅ 推荐

实际使用建议:日志直接用 logger.Ctx(ctx);若需在 handler 里单独取值,用 ctx.Locals("request_id") 或 trace.RequestIDFromContext(ctx.Context())。Gin 里也有类似区别——c.GetHeader("X-Request-Id") 读的是 header,c.GetString("request_id") 读的才是 c.Keys。


License

与主仓库保持一致(见根目录 LICENSE)。

Documentation

Overview

Package trace context_adapter.go 提供"非标准 context"到追踪字段的适配机制。

背景:

  • trace 包默认将追踪字段以 traceBagKey{} 为 key 存到标准 context.Context
  • 但部分框架(Gin / Fiber / go-restful)传递给业务层的 context 对象并非纯粹的 context.Context:它们要么只在 req.Context() 中持有真正的 ctx,要么使用自家 KV 存储(c.Keys / c.Locals / req.Attribute)
  • 为了让用户无论传 *gin.Context、fiber.Ctx、*restful.Request 还是普通 ctx, logger.Ctx(x) 都能正确注入追踪字段,trace 提供一个可插拔的 Adapter 机制

设计:

  • 各框架中间件(middleware/*.go)通过 init() 注册自己的 Adapter
  • Adapter 职责:给定一个任意对象,尝试从中"解出"一个携带 trace bag 的 context.Context
  • ValuesFromContext 在标准 context 取不到 bag 时,会依次调用已注册的 Adapter 兜底

线程安全:

  • Adapter 注册应在 init() 阶段完成,运行时只读;使用 sync.RWMutex 保护读写

extractor.go 定义字段提取器抽象以及内置实现。

设计思路:

  • FieldExtractor 接口完全与具体 HTTP/gRPC 库解耦
  • 各中间件在调用前将自身的请求对象适配为统一的 ExtractSource
  • 内置提取器覆盖 90% 场景;复杂场景使用 ExtractorFunc 自定义

Package trace 提供链路追踪所需的 ID 生成、Context 存取、字段提取等能力。

generator.go 负责 ID 生成器:

  • 默认生成器:NanoID(21 字符,URL-safe 字母表),零新增依赖
  • 可选生成器:UUID v4

NanoID 相比 UUID v4 的优势:

  • 更短(21 字符 vs 36 字符),日志可读性更好
  • 同等安全强度(21 字符 × 64 字母表 = 126 bit 熵,优于 UUID v4 的 122 bit)
  • URL-safe,可直接嵌入 URL
  • 支持自定义字母表与长度

process.go 定义所有中间件共享的"请求处理核心"。

职责:

  1. 按 TraceConfig.Fields 顺序,逐字段尝试 Extractor → Generator
  2. 将提取到的值合并写入 ctx
  3. 调用 writeHeader 将需要回写的字段写入响应头

各框架中间件仅负责"适配输入/输出",逻辑完全复用本函数。

Package trace trace.go 定义链路追踪的核心类型:

  • TraceField:单个追踪字段(name/header/extractor/generator 的集合)
  • TraceConfig:多字段的集合 + 链式配置 API
  • Context 桥接:WithValues/WithValue/ValuesFromContext/ValueFromContext

设计原则:

  • context key 使用自定义 struct{} 类型,防止跨包冲突(Go 官方规范)
  • 所有字段统一存储在单一 traceBag map 中,减少 ctx.Value 查找次数
  • TraceField 的零值安全:Extractor/Generator 可为 nil

Index

Constants

View Source
const (
	FieldRequestID = "request_id"
	FieldTraceID   = "trace_id"
	FieldSpanID    = "span_id"
	FieldUserID    = "user_id"
)

默认字段名(与日志 JSON key 完全一致)

View Source
const (
	HeaderRequestID = "X-Request-Id"
	HeaderTraceID   = "X-Trace-Id"
	HeaderSpanID    = "X-Span-Id"
	HeaderUserID    = "X-User-Id"
)

默认 HTTP Header 名

View Source
const DefaultNanoIDAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-"

DefaultNanoIDAlphabet 默认字母表:A-Z a-z 0-9 _ -(共 64 个字符,URL-safe) 参考 https://github.com/ai/nanoid 规范

View Source
const DefaultNanoIDSize = 32

DefaultNanoIDSize 默认长度 32 字符 在 1000 IDs/s 速率下,需约 149 年才有 1% 的碰撞概率

Variables

DefaultGenerator 默认生成器:NanoID(21) —— 作为 TraceField 未显式指定 Generator 时的回退

Functions

func DetachedContext added in v1.2.67

func DetachedContext(parent context.Context) context.Context

DetachedContext 脱离父 ctx 的 Deadline / Cancel,但完整保留 traceBag。

典型场景:

  • HTTP / gRPC 请求处理器中 fork 出一个长生命周期 goroutine
  • 父 ctx 会在响应返回后立即 Cancel,但异步任务希望继续使用原 request_id 写日志

使用示例:

func Handler(ctx context.Context) {
    asyncCtx := trace.DetachedContext(ctx)
    go func() {
        // 即便父请求已返回,这里的 logger 仍携带原 request_id
        logger.Ctx(asyncCtx).Info("async done")
    }()
}

如传入 nil,返回携带空 bag 的 context.Background()。

func EnsureRequestID

func EnsureRequestID(ctx context.Context) (context.Context, string)

EnsureRequestID 确保 ctx 中存在 request_id,没有则生成;返回新 ctx 与 id

func Process

func Process(
	ctx context.Context,
	cfg *TraceConfig,
	src ExtractSource,
	writeHeader func(key, value string),
) (context.Context, map[string]string)

Process 执行字段提取、生成、ctx 注入、响应头回写的完整流程

参数:

  • ctx: 入参 context(来自请求对象)
  • cfg: 追踪配置
  • src: 抽象请求源(由框架中间件适配产生)
  • writeHeader: 响应头写入函数(可为 nil,表示不回写)

返回:

  • 注入了追踪字段的新 ctx
  • 本次提取/生成得到的所有字段值(便于中间件日志打点)

func RegisterContextAdapter

func RegisterContextAdapter(a ContextAdapter)

RegisterContextAdapter 注册一个 Adapter(通常在中间件包的 init() 中调用)

多次注册时按注册顺序依次尝试,第一个返回 true 的命中即止

func RequestIDFromContext

func RequestIDFromContext(ctx context.Context) string

RequestIDFromContext 快捷读取 request_id

func ValueFromContext

func ValueFromContext(ctx context.Context, name string) string

ValueFromContext 返回单个字段值(不存在返回空串)

func ValuesFromContext

func ValuesFromContext(ctx context.Context) map[string]string

ValuesFromContext 返回 context 中所有追踪字段(只读拷贝;无字段返回 nil)

func WithRequestID

func WithRequestID(ctx context.Context, id string) context.Context

WithRequestID 快捷写入 request_id 若 id 为空,使用 DefaultGenerator 自动生成

func WithValue

func WithValue(ctx context.Context, name, value string) context.Context

WithValue 向 context 写入单个追踪字段

func WithValues

func WithValues(ctx context.Context, kv map[string]string) context.Context

WithValues 向 context 批量写入追踪字段(不可变语义,返回新 ctx) 若 ctx 中已有 traceBag,则合并(新值覆盖旧值)

Types

type ContextAdapter

type ContextAdapter func(any) (context.Context, bool)

ContextAdapter 将"任意对象"转换为携带追踪字段的标准 context.Context

返回值:

  • 成功命中时返回 (ctx, true)
  • 不认识该对象时返回 (nil, false)

type ExtractSource

type ExtractSource struct {
	// Headers 读取 HTTP Header 或 gRPC metadata(大小写不敏感由实现方保证)
	Headers func(key string) string

	// Query 读取 URL query 参数
	Query func(key string) string

	// Cookie 读取 HTTP Cookie 值
	Cookie func(key string) string

	// Metadata 读取 gRPC metadata(与 Headers 的区别:Metadata 严格小写;Headers 兼容 HTTP 大小写)
	// 对于 HTTP 中间件,此字段通常与 Headers 相同或为 nil
	Metadata func(key string) string

	// Raw 原始请求对象(逃生舱)——供自定义提取器在特殊场景下使用
	//   - net/http:   *http.Request
	//   - gin:        *gin.Context
	//   - fiber:      *fiber.Ctx
	//   - go-restful: *restful.Request
	//   - gRPC:       metadata.MD
	Raw interface{}
}

ExtractSource 抽象的请求数据源 所有 getter 都可以为 nil,提取器内部需做空值保护

type ExtractorFunc

type ExtractorFunc func(source ExtractSource) (string, bool)

ExtractorFunc 函数式适配器,便于快速定义自定义提取器

func (ExtractorFunc) Extract

func (f ExtractorFunc) Extract(s ExtractSource) (string, bool)

Extract 实现 FieldExtractor 接口

type FieldExtractor

type FieldExtractor interface {
	// Extract 从 source 中提取字段值
	// 返回 (value, ok),ok=false 表示未提取到(外层会继续尝试下一个策略或 Generator)
	Extract(source ExtractSource) (string, bool)
}

FieldExtractor 字段提取器抽象

func ChainExtractor

func ChainExtractor(extractors ...FieldExtractor) FieldExtractor

ChainExtractor 按顺序组合多个提取器,第一个命中即返回 实现"混合提取策略":如优先从 Header 读取,其次从 Query,再次从 Cookie

示例:

trace.ChainExtractor(
    trace.HeaderExtractor("X-Request-Id"),
    trace.QueryExtractor("request_id"),
    trace.CookieExtractor("req_id"),
)

func CookieExtractor

func CookieExtractor(keys ...string) FieldExtractor

CookieExtractor 从 HTTP Cookie 读取

func HeaderExtractor

func HeaderExtractor(keys ...string) FieldExtractor

HeaderExtractor 从 HTTP Header 读取 支持多个 key,按顺序尝试,第一个命中即返回(便于兼容多种头名,如 X-Request-Id/X-Trace-Id)

func MetadataExtractor

func MetadataExtractor(keys ...string) FieldExtractor

MetadataExtractor 从 gRPC metadata 读取

func QueryExtractor

func QueryExtractor(keys ...string) FieldExtractor

QueryExtractor 从 URL query 参数读取

type FieldOption

type FieldOption func(*TraceField)

FieldOption 单个字段的链式配置选项

func WithExtractor

func WithExtractor(e FieldExtractor) FieldOption

WithExtractor 自定义提取器

func WithFieldName

func WithFieldName(name string) FieldOption

WithFieldName 自定义字段名(日志 key + context key)

func WithGenerator

func WithGenerator(g GeneratorFunc) FieldOption

WithGenerator 自定义生成器

func WithHeaderName

func WithHeaderName(name string) FieldOption

WithHeaderName 自定义 HTTP Header / gRPC metadata 键名

func WithRequired

func WithRequired(r bool) FieldOption

WithRequired 设置是否为必需字段

func WithResponseWrite

func WithResponseWrite(w bool) FieldOption

WithResponseWrite 设置是否回写到响应头

type GeneratorFunc

type GeneratorFunc func() string

GeneratorFunc ID 生成函数类型

func NanoIDGenerator

func NanoIDGenerator(size int) GeneratorFunc

NanoIDGenerator 返回一个使用默认字母表、指定长度的 NanoID 生成器 size <= 0 时使用默认长度 32

func NanoIDGeneratorCustom

func NanoIDGeneratorCustom(alphabet string, size int) GeneratorFunc

NanoIDGeneratorCustom 返回一个使用自定义字母表与长度的 NanoID 生成器

实现说明:

  • 使用 crypto/rand 作为熵源,保证密码学强度
  • 使用位掩码采样法,确保字符分布均匀(不因 256 % len != 0 产生偏差)
  • 容错:字母表为空或 size <= 0 时,回退到默认配置

func UUIDGenerator

func UUIDGenerator() GeneratorFunc

UUIDGenerator 返回一个 UUID v4 生成器(输出带连字符的 36 字符标准格式)

type TraceConfig

type TraceConfig struct {
	Fields []*TraceField
}

TraceConfig 中心化追踪配置

func DefaultConfig

func DefaultConfig() *TraceConfig

DefaultConfig 返回默认配置:仅包含一个 request_id 字段

  • 字段名: request_id
  • Header: X-Request-Id
  • 提取: 从 X-Request-Id Header 读取
  • 生成: NanoID(21)
  • 响应回写: true
  • Required: true

func NewConfig

func NewConfig() *TraceConfig

NewConfig 创建一个空配置

func (*TraceConfig) AddField

func (c *TraceConfig) AddField(f *TraceField) *TraceConfig

AddField 追加一个自定义字段

func (*TraceConfig) WithRequestID

func (c *TraceConfig) WithRequestID(opts ...FieldOption) *TraceConfig

WithRequestID 添加 request_id 字段(可通过 opts 覆盖默认值)

func (*TraceConfig) WithSpanID

func (c *TraceConfig) WithSpanID(opts ...FieldOption) *TraceConfig

WithSpanID 添加 span_id 字段

func (*TraceConfig) WithTraceID

func (c *TraceConfig) WithTraceID(opts ...FieldOption) *TraceConfig

WithTraceID 添加 trace_id 字段(可通过 opts 覆盖默认值)

func (*TraceConfig) WithUserID

func (c *TraceConfig) WithUserID(opts ...FieldOption) *TraceConfig

WithUserID 添加 user_id 字段(默认不自动生成,仅从请求透传)

type TraceField

type TraceField struct {
	// Name 日志输出时的字段名(如 "request_id"),也作为 context 存储键
	Name string

	// HeaderName HTTP/gRPC metadata 传输时使用的键名(如 "X-Request-Id")
	// 为空表示该字段不参与协议层透传
	HeaderName string

	// Extractor 从请求中提取值的策略;为 nil 表示不尝试提取
	Extractor FieldExtractor

	// Generator 当 Extractor 提取不到时生成值的策略;为 nil 表示不自动生成
	Generator GeneratorFunc

	// WriteResponse 是否将最终值回写到响应头
	WriteResponse bool

	// Required 表示该字段在请求中必须存在
	//   - true  + Extractor 未命中 + Generator 存在 → 使用 Generator 生成
	//   - true  + Extractor 未命中 + Generator 为 nil → 使用 DefaultGenerator 兜底
	//   - false + Extractor 未命中 + Generator 为 nil → 跳过该字段
	Required bool
}

TraceField 描述一个追踪字段的完整行为

Directories

Path Synopsis
Package middleware body.go 提供"从请求 Body 中提取 JSON 字段"的快捷方法。
Package middleware body.go 提供"从请求 Body 中提取 JSON 字段"的快捷方法。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址