Go context.WithValue 传 trace id 时 key 和类型怎么设计

在 HTTP 服务里，trace id 通常要从入口一路带到日志、RPC 或数据库调用。用 context.WithValue 可以做到，但设计重点不是“把字符串放进去”，而是同时约束 key 的身份、value 的类型和使用范围：key 用包内私有类型，value 固定为 string，读写通过小函数封装，业务参数仍然显式传递。

推荐的最小方案是：定义一个未导出的 key 类型，使用一个未导出的 key 实例保存 trace id，再提供类型化的写入和读取函数。这样调用方无需知道 Context 内部的 key，也不会因为另一个包恰好使用了 "trace_id" 而读到错误数据。

先把 trace id 定义成请求范围的数据

Go 官方 context 文档把 Value 定位为跨 API 和进程传递的 request-scoped data，并明确不建议用它传递可选参数。trace id 正好属于这类元数据：它跟随一次请求，在中间件、handler 和下游客户端之间流动；而订单号、分页大小、是否开启某个业务开关，应该继续作为函数参数出现。

还要区分“值的传播”和“取消”。WithValue 只创建带值的派生 Context，不会替你设置超时；入口如果已经有请求 Context，就在它上面附加值，不能在下游重新从 context.Background() 开一棵树，否则 trace id 和取消信号都会断掉。

用包内私有 key 避免跨包碰撞

WithValue 要求 key 可比较。直接写 context.WithValue(ctx, "trace_id", id) 虽然能编译，但不同包只要使用相同字符串就共享了同一个 key 身份，重构或接入中间件时很容易误读。官方建议由使用方定义自己的 key 类型；空结构体通常不产生额外数据，适合做不需要导出的 key 类型。

package tracectx

import "context"

// key 是包内私有类型，避免与其他包的 Context key 发生碰撞。
type key struct{}

// traceIDKey 是唯一的 key 实例；调用方不需要也不能直接访问它。
var traceIDKey key

// WithTraceID 只把请求级 trace id 附加到已有 Context 上。
func WithTraceID(ctx context.Context, id string) context.Context {
	// 空 id 由上层决定是否拒绝；这里保持写入逻辑单一。
	return context.WithValue(ctx, traceIDKey, id)
}

这里的关键不是变量名，而是“自定义类型 + 包内私有身份”。如果确实需要跨包暴露 key，静态类型应是指针或接口并由当前包控制；对 trace id 这种内部约定，直接保持 key 私有更容易维护。

用类型化存取函数封住 any

Context 的 Value 返回 any，因此不要让每个调用点都写一次类型断言。把断言集中到读取函数，可以统一处理 key 不存在、类型不对和空字符串，并且以后把 trace id 从 string 换成别的内部表示时，改动面只在一个包。

package tracectx

import "context"

// TraceIDFromContext 读取 trace id；false 表示没有可用的 string 值。
func TraceIDFromContext(ctx context.Context) (string, bool) {
	// 类型断言同时过滤 nil、错误类型和未写入三种情况。
	id, ok := ctx.Value(traceIDKey).(string)
	if !ok || id == "" {
		return "", false
	}
	return id, true
}

如果业务允许空字符串有特殊含义，可以去掉 id == "" 的判断，把“存在”和“内容非空”交给不同的校验层。不要用 ctx.Value(traceIDKey).(string) 的强制断言直接向上抛 panic，日志链路缺字段不应该把整个请求打崩。

沿请求链传递并处理缺失值

入口中间件负责生成或提取 trace id，然后把返回的新 Context 传给后续函数。下游只接收 ctx，需要记录时调用读取函数；普通业务数据仍显式传参。这样既能让多个 goroutine 安全读取同一个 Context，也能保留函数签名对核心业务输入的可见性。

func handle(w http.ResponseWriter, r *http.Request) {
	// 真实项目可先校验上游请求头；示例只展示 Context 的传播。
	id := r.Header.Get("Traceparent")
	if id == "" {
		id = newTraceID()
	}
	ctx := tracectx.WithTraceID(r.Context(), id)

	// 把派生 Context 继续传下去，不能在 service 内改用 Background。
	if err := service.Process(ctx, r.URL.Query().Get("order")); err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}
	w.WriteHeader(http.StatusNoContent)
}

func Process(ctx context.Context, order string) error {
	// 缺失 trace id 时保留可诊断日志，但不把元数据当成业务参数。
	if id, ok := tracectx.TraceIDFromContext(ctx); ok {
		log.Printf("trace_id=%s order=%s", id, order)
	}
	return nil
}

不要把 Context 存进结构体字段，也不要在 goroutine 启动后把它替换成新的 Background。需要异步任务时，应先明确它是否仍属于原请求：属于就继续传入并监听 ctx.Done()，不属于就使用独立生命周期和明确的数据快照。

用最小验证检查 key、类型和取消边界

验证重点是身份和边界，不是打印一行“读取成功”。至少覆盖四个断言：同一 key 能取回值；同名字符串不能命中私有 key；缺失时返回 false；派生 Context 保留值但仍继承父 Context 的取消信号。

func TestTraceIDContext(t *testing.T) {
	// 先写入固定值，确认同一私有 key 可以读回。
	ctx := tracectx.WithTraceID(context.Background(), "req-42")
	if got, ok := tracectx.TraceIDFromContext(ctx); !ok || got != "req-42" {
		t.Fatalf("trace id = %q, %v", got, ok)
	}

	// 裸字符串只是另一个 key，不能覆盖包内私有 key。
	if ctx2 := context.WithValue(ctx, "trace_id", "wrong"); func() bool {
		got, ok := tracectx.TraceIDFromContext(ctx2)
		return ok && got == "wrong"
	}() {
		t.Fatal("string key unexpectedly matched")
	}
}

生产测试还应补上父 Context 取消后的下游退出检查，以及中间件未生成 id 时的行为。若系统跨进程传播 trace id，还要按所用追踪协议在 HTTP header 或 RPC metadata 层完成注入与提取；WithValue 本身不会自动把值发到网络另一端。

相关问题

key 用自定义 string 类型可以吗？

可以避免一部分与裸 string 的碰撞，但包内私有的 struct{} 类型更能隐藏 key 身份。无论选择哪种类型，都不要导出可被任意包复用的字符串常量。

trace id 应该放进 Context 还是函数参数？

沿请求边界、日志和 RPC 链路传递的元数据适合放 Context；函数真正需要的业务输入应继续显式传参。这样调用关系和数据依赖更容易阅读。

参考：Go context 包官方文档；Go Blog：Context 并发模式。