Go context.Value 传递请求元数据的边界

Go 的 context.Value 适合在请求调用链中携带少量、请求级、只读的元数据，例如 trace ID、租户标识或认证后的主体摘要。它不是通用参数袋：可选参数、业务必需参数、大型对象和可变状态都应该通过显式参数或专用依赖传递。

官方文档入口：https://pkg.go.dev/context。本文只讨论自定义 key、值的生命周期和“什么不该放进去”，不把 context 当作跨请求缓存。

先用请求边界判断是否适合 Value

我在拆 HTTP 服务调用链时，最容易犯的错是看到函数参数变多，就把参数全部塞进 context。这样虽然短期内少写几个参数，长期却让函数的真实依赖变得不可见。一个更稳的判断是：这个值是否只属于当前请求，是否需要跨越多个 API 边界，是否足够轻量，并且是否不会被下游随意修改？四个条件不能满足，就不应该优先选择 Value。

Go 官方对 Value 的定位是传递跨进程和 API 边界的请求级数据，而不是给函数传可选参数。比如 trace ID 可以随着请求向日志、远端调用和数据库适配层传播；分页大小、排序字段、业务对象则应该继续出现在函数签名或明确的配置对象中。

用包私有 key 建立类型边界

context.WithValue 返回一个派生 context，读取时沿着这条链寻找匹配的 key。不要直接用字符串作为 key，因为不同包可能无意中使用同名字符串。更稳的方式是在拥有数据的包内定义不可导出的 key 类型，并把写入和读取封装成函数。

package requestmeta

import "context"

// requestIDKey 使用不可导出的类型，避免其他包用相同字符串覆盖值。
type requestIDKey struct{}

// WithRequestID 只把当前请求的轻量标识写入派生 context。
func WithRequestID(ctx context.Context, id string) context.Context {
	return context.WithValue(ctx, requestIDKey{}, id)
}

// RequestID 统一处理缺失值，调用方不需要重复做类型断言。
func RequestID(ctx context.Context) (string, bool) {
	id, ok := ctx.Value(requestIDKey{}).(string)
	return id, ok && id != ""
}

这里的 key 是空结构体值，每次写入和读取都使用同一 key 类型和值语义；读取函数把类型断言收在包内部，调用方只面对 (string, bool)。如果缺少 request ID，业务可以选择补充日志字段或走降级分支，而不是让一次断言 panic。

沿派生链传递，但不要把 Context 存进结构体

中间件通常从请求取得根 context，再用 WithValue 派生一个子 context，最后把它交给后续 handler。这个关系表达的是“当前请求带着一项元数据继续前进”，不是把数据写进一个全局 map。派生 context 仍然受父 context 的取消和生命周期影响。

func withRequestID(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// 请求头只负责提供候选值，生产代码还应按自身协议校验格式。
		requestID := r.Header.Get("X-Request-ID")
		ctx := requestmeta.WithRequestID(r.Context(), requestID)

		// 用 WithContext 替换请求上下文，不把 context 保存到全局状态。
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

func handleOrder(w http.ResponseWriter, r *http.Request) {
	requestID, ok := requestmeta.RequestID(r.Context())
	if !ok {
		// 缺失元数据是可处理的请求状态，不把它当成类型断言异常。
		http.Error(w, "missing request id", http.StatusBadRequest)
		return
	}

	// 必需的订单号仍然显式来自路由或函数参数，而不是藏进 context。
	fmt.Fprintln(w, requestID)
}

示例里的 http.Handler、fmt 和 requestmeta import 省略了包声明细节，重点是数据边界：请求级标识从入口进入 context，订单号等业务输入仍由请求解析和函数参数表达。不要把 context.Context 作为 handler 结构体字段长期保存，否则调用关系和取消时机都会变得模糊。

值的生命周期跟着请求走

context 的值不是“存进去以后永远可取”的缓存。子 context 持有父链关系，父请求结束、取消或超时后，下游工作也应该停止。若代码自己创建了带取消或超时的派生 context，要在当前操作结束时调用返回的 cancel 函数，释放相关资源。

对 Value 来说，生命周期边界还意味着不要把请求结束后仍需使用的对象只放在 context 里。比如异步任务若会脱离原请求继续运行，应在任务入口构造明确的任务参数或持久化记录，而不是继续引用请求 context 里的可变对象。

四类内容不应该塞进 context.Value

第一类是必需业务参数。函数如果没有用户 ID、订单号或过滤条件就无法正确工作，就把它放在签名里，让编译器和调用方都看得见。

第二类是可选参数。可选的分页大小、排序方式或展示开关如果只在一个函数附近使用，就用参数或配置结构体表达，不要借 Value 隐藏默认值。

第三类是大型对象和连接资源。数据库连接、缓存客户端、文件句柄、请求体或大段响应数据会延长引用链并增加内存和并发管理难度；它们应由结构体字段、依赖注入或明确的资源管理流程持有。

第四类是可变共享状态。把 map、slice 或指针放进 context 并不会自动获得并发保护，也不会让所有读取者拥有一致的更新语义。需要共享状态时，使用明确的锁、所有权或消息传递方案。

把读取函数设计成可处理缺失值

读取 context Value 时，不要把“必然存在”当作接口契约，除非这项契约已经由同一个包的中间件强制建立。更通用的 getter 返回值和布尔状态；如果下游确实要求它存在，就在靠近入口的位置完成检查，并返回清晰的 HTTP 错误或业务错误。

类型断言也要和写入类型一致。写入的是字符串，读取就不要假设是自定义结构体；如果元数据需要多个字段，可以定义一个小而稳定的不可变值对象，但不要把大型业务聚合根整体塞入 Value。

落地时用一张边界清单做取舍

我的取舍顺序是：先让函数签名表达必需依赖，再把真正跨边界的请求元数据收进一个小包，最后为缺失值、取消和请求结束后的异步任务留下清晰分支。这样 context.Value 是调用链的辅助通道，而不是业务数据的隐藏仓库。

为什么不用字符串作为 context key？

字符串容易和其他包发生命名冲突。自定义、不可导出的 key 类型把读写约束在拥有这项元数据的包内，调用方通过 getter 使用它。

context.Value 能不能存用户对象？

只有在对象非常轻量、只属于当前请求且不会被下游修改时才勉强适合。若是核心业务对象、可变状态或大型结构，优先使用显式参数或专门的依赖边界。

context 中的值什么时候失效？

它跟随当前 context 链存在；父 context 被取消后，下游操作应结束。不要把请求 context 或其中的值当作跨请求缓存，也不要让脱离请求的异步任务隐式依赖它。