Go context.WithValue 取不到值通常是哪里不一致

我在排查一条请求链时遇到过这种现象：入口函数明明调用了 context.WithValue，下游却一直拿到 nil。这类问题通常不是值“自动消失”，而是写入和读取之间有一处不一致：键的动态类型不同、键的具体值不同、传下去的不是派生 Context，或者取出来后的类型断言不匹配。

官方文档：https://pkg.go.dev/context

先判断：到底是哪一种不一致

WithValue(parent, key, val) 返回的是指向 parent 的派生 Context。只有从这个派生 Context 或它的后代读取，才会沿链找到值；如果写入后继续传原来的 parent，读取自然是 nil。另外，键不是按“打印出来的文字”匹配，而是按动态类型和值匹配。

例如，下面两个键的文本都像是 user-id，但一个是未命名字符串类型，一个是自定义类型，它们不会互相命中。即使类型相同，具体值不同也不会命中。

用私有键类型和访问器固定读写契约

最稳妥的做法是让保存键的包同时提供写入函数和读取函数。调用方不需要知道键的具体实现，也不会在不同文件里各自声明一个“看起来一样”的键。官方文档也建议使用未导出的键类型来减少包间碰撞。

package requestmeta

import "context"

// userIDKey 只在本包内可见，避免调用方用字符串或同名类型碰撞。
type userIDKey struct{}

// WithUserID 返回新的派生 Context，调用方必须继续传递这个返回值。
func WithUserID(ctx context.Context, id string) context.Context {
	// 空字符串仍可由业务决定是否接受，这里只负责保存请求级元数据。
	return context.WithValue(ctx, userIDKey{}, id)
}

// UserID 统一处理取值和类型断言，避免业务代码重复写断言。
func UserID(ctx context.Context) (string, bool) {
	value, ok := ctx.Value(userIDKey{}).(string)
	return value, ok
}

// handleRequest 展示派生 Context 如何沿调用链传给下游。
func handleRequest(ctx context.Context, id string) {
	ctx = WithUserID(ctx, id) // 接住新 Context，不能继续使用旧变量。
	downstream(ctx)
}

这里每次写入和读取都使用 userIDKey{}。空结构体值相等，因此这种写法可以稳定命中；如果键类型包含字段，就要保证读取时构造出的字段值也一致。访问器返回 (value, ok)，比把不存在的值和合法的零值混在一起更容易判断。

取不到值时按四个检查点排查

排查时不要只在写入点打印一个值。沿着函数参数记录“写入的键类型、传递的 Context 变量、读取的键和断言目标类型”，通常很快就能发现其中一项发生了变化。尤其要注意中间函数是否把 ctx 丢掉后重新使用了 context.Background()。

Context Value 的适用边界

Context Value 适合携带请求范围内、需要穿过 API 边界的数据，例如认证后的请求标识、链路追踪信息或租户标识。它不适合替代函数的可选参数、业务配置或必需依赖；这些信息应通过明确的函数参数或结构体传入，否则调用关系会变得隐蔽。

还要记住两点：键必须是可比较类型，不能使用切片、函数或包含不可比较字段的结构体；值为 nil 时，即使键匹配，也会让调用方难以区分“没有值”和“存的是 nil”。如果业务需要清晰状态，优先把指针、结构体或显式结果封装在访问器里。

两个容易混淆的问题

为什么同样写成 user-id 还是取不到？

因为 Value 不按格式化后的字符串匹配，而是按键的动态类型和值匹配。命名字符串、未命名字符串和不同包声明的自定义类型都可能不相等。

WithValue 会修改原来的 Context 吗？

不会。它返回一个新的派生 Context，原 Context 保持不变。忽略返回值或把旧 Context 继续传给下游，是最常见的原因之一。