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 定义所有中间件共享的"请求处理核心"。
职责:
- 按 TraceConfig.Fields 顺序,逐字段尝试 Extractor → Generator
- 将提取到的值合并写入 ctx
- 调用 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
- Variables
- func DetachedContext(parent context.Context) context.Context
- func EnsureRequestID(ctx context.Context) (context.Context, string)
- func Process(ctx context.Context, cfg *TraceConfig, src ExtractSource, ...) (context.Context, map[string]string)
- func RegisterContextAdapter(a ContextAdapter)
- func RequestIDFromContext(ctx context.Context) string
- func ValueFromContext(ctx context.Context, name string) string
- func ValuesFromContext(ctx context.Context) map[string]string
- func WithRequestID(ctx context.Context, id string) context.Context
- func WithValue(ctx context.Context, name, value string) context.Context
- func WithValues(ctx context.Context, kv map[string]string) context.Context
- type ContextAdapter
- type ExtractSource
- type ExtractorFunc
- type FieldExtractor
- type FieldOption
- type GeneratorFunc
- type TraceConfig
- func (c *TraceConfig) AddField(f *TraceField) *TraceConfig
- func (c *TraceConfig) WithRequestID(opts ...FieldOption) *TraceConfig
- func (c *TraceConfig) WithSpanID(opts ...FieldOption) *TraceConfig
- func (c *TraceConfig) WithTraceID(opts ...FieldOption) *TraceConfig
- func (c *TraceConfig) WithUserID(opts ...FieldOption) *TraceConfig
- type TraceField
Constants ¶
const ( FieldRequestID = "request_id" FieldTraceID = "trace_id" FieldSpanID = "span_id" FieldUserID = "user_id" )
默认字段名(与日志 JSON key 完全一致)
const ( HeaderRequestID = "X-Request-Id" HeaderTraceID = "X-Trace-Id" HeaderSpanID = "X-Span-Id" HeaderUserID = "X-User-Id" )
默认 HTTP Header 名
const DefaultNanoIDAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-"
DefaultNanoIDAlphabet 默认字母表:A-Z a-z 0-9 _ -(共 64 个字符,URL-safe) 参考 https://github.com/ai/nanoid 规范
const DefaultNanoIDSize = 32
DefaultNanoIDSize 默认长度 32 字符 在 1000 IDs/s 速率下,需约 149 年才有 1% 的碰撞概率
Variables ¶
var DefaultGenerator = NanoIDGenerator(DefaultNanoIDSize)
DefaultGenerator 默认生成器:NanoID(21) —— 作为 TraceField 未显式指定 Generator 时的回退
Functions ¶
func DetachedContext ¶ added in v1.2.67
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 ¶
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 ¶
RequestIDFromContext 快捷读取 request_id
func ValueFromContext ¶
ValueFromContext 返回单个字段值(不存在返回空串)
func ValuesFromContext ¶
ValuesFromContext 返回 context 中所有追踪字段(只读拷贝;无字段返回 nil)
func WithRequestID ¶
WithRequestID 快捷写入 request_id 若 id 为空,使用 DefaultGenerator 自动生成
Types ¶
type ContextAdapter ¶
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 WithFieldName ¶
func WithFieldName(name string) FieldOption
WithFieldName 自定义字段名(日志 key + context key)
func WithHeaderName ¶
func WithHeaderName(name string) FieldOption
WithHeaderName 自定义 HTTP Header / gRPC metadata 键名
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 (*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 字段"的快捷方法。 |