Go context.WithValue 的 key 为什么建议用私有类型

context.WithValue 建议使用包内私有的定义类型作为 key，主要是为了隔离不同包的键身份，避免大家都用同一个字符串而相互遮蔽。键的匹配同时涉及动态类型和值：独立定义的私有类型即使底层值一样，也不会与其他包的同名字符串键相等。再用写入、读取函数封装，可以把类型断言与缺失处理留在一个地方。

官方地址：https://pkg.go.dev/context

我更倾向于把这种做法看成包接口的设计：调用者应当表达“附加请求编号”或“取得请求编号”，不必知道编号藏在哪个键里。这里的私有是命名与协作边界，并不是数据保密机制。

为什么字符串键会冲突

假设两个包都选用字符串 request_id。当它们对同一条 Context 派生链写入这个键时，后面的值会在该子上下文的查询中遮蔽前面的值。若一个包放字符串，另一个包放整数，读取端还可能拿到不符合预期类型的值。

给字符串加包名前缀能降低碰巧重名的概率，但没有从类型上隔离键身份。Context 的 Value 也不会替你检查“这个键应该只存字符串”；写入的值和读取约定仍由包自己维护。

私有定义类型如何隔离键身份

写成 type contextKey uint8 会创建一个新的定义类型。其他包即使也声明相同拼写的私有类型，仍是独立的类型。将该类型的值作为键，可以避免与内置字符串、整数及其他包定义的类型意外相等。

要注意定义类型与类型别名的区别。type contextKey = string 只是 string 的别名，并没有创建新的类型身份，无法提供同样的隔离。仅把变量名写成小写、但变量里仍保存普通字符串，也没有改变键的动态类型。

同一个包内部仍要为不同用途分配不同的键值。私有类型能隔离包之间的命名空间，却不能自动识别同一类型、同一值被复用于多个业务字段的错误。

用写入与读取函数封装

下面是一份可放入 requestmeta 包的完整实现。键类型、键值都不导出，对外只提供有业务含义的函数：

package requestmeta

import "context"

// 私有定义类型与私有键，调用方只接触访问函数。
type contextKey uint8
const requestIDKey contextKey = 0

func WithRequestID(parent context.Context, id string) context.Context {
    return context.WithValue(parent, requestIDKey, id)
}

func RequestID(ctx context.Context) (string, bool) {
    // 双返回值断言避免缺失或类型不符时直接 panic。
    id, ok := ctx.Value(requestIDKey).(string)
    return id, ok
}

调用方将请求的已有 Context 传给 WithRequestID，保存返回的派生 Context，并继续传给下游函数。读取时调用 RequestID，根据 bool 决定缺失处理。这样以后调整键实现，不需要每个调用点都同步修改。

这个实现允许空字符串作为一个已存在的值，因此空字符串与“没有存入”可以通过 bool 区分。如果业务不允许空编号，应在入口明确检查；不要用类型断言是否成功替代业务合法性判断。

哪些数据适合放入 Context

官方建议把 Value 用于跨 API 边界传递的请求范围数据，不作为给函数传可选参数的通用工具。请求编号、跟踪相关元数据这类与请求生命周期紧密关联的内容，是常见的使用方向。

函数完成任务必须拿到的业务参数，通常更适合显式参数；数据库连接池、全局配置、服务实例等长期依赖，更适合由结构体或构造函数管理。否则调用签名看似简单，真实依赖却需要读完整条调用链才能发现。

Context 可以供多个协程使用，不意味着存进去的 map、指针对象就自动线程安全。如果值本身可变，仍需按该对象的同步约定访问。私有键也不会阻止读取函数的调用者取得数据，更不提供加密或访问授权。

处理派生上下文与缺失值

WithValue 返回新的派生 Context，不会原地改写父对象。只调用写入函数却继续传旧 Context，下游当然取不到刚存入的值。相同键的新值只影响相应子上下文及其后续派生链，不会回写父 Context。

键必须非 nil 且可比较。本文的 uint8 定义类型满足要求；不要把 slice 或 map 当作键。值可以是多种类型，但访问函数应让一类键始终对应稳定的数据类型，并以安全断言处理缺失。

直接用空结构体作为键可以吗？

关键在于类型身份。所有直接使用 struct{} 类型的零值都属于相同类型，不能隔离不同用途；独立定义私有结构体类型则有不同身份。本文选用私有整数定义类型，便于同包内分配多个键。

私有 key 是不是外部完全读不到？

它用于避免误碰键与约束包接口，不是保密边界。暴露的读取函数仍然可以返回对应数据。

找不到值应该返回错误还是默认值？

由业务决定。示例返回 string 与 bool，让上层区分没有值和有空值；是否拒绝请求、生成编号或省略日志字段，应在相应业务层明确处理。

参考：Go WithValue 约定、Go 类型身份规则。