Go context 的键为什么不该直接使用字符串

我在排查一条请求链上的用户身份偶尔变成追踪编号时，先怀疑的是值被覆盖，后来才发现两个包都把 "request-id" 当成了 Context 键。Go 的 Context 会按键的相等性查找值，两个包里的内置字符串只要内容相同，就没有包边界可言。因此，context.WithValue 可以接受字符串，但不应把普通字符串直接当作跨包协议。

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

字符串键的碰撞不是偶然丢值

假设认证包写入用户对象，追踪包写入链路编号，两个包都使用 string("request-id")。Context 的键比较看的是动态类型和值；这里两次键的动态类型都是 string，值也相同，所以它们是相等键。Context 链仍然存在，问题只是调用方取到的值可能与自己的预期不同。

package main

import (
	"context"
	"fmt"
)

func main() {
	ctx := context.Background()
	// 两个包若各自使用相同的 string 字面量，就共享了一个易碰撞的键空间。
	ctx = context.WithValue(ctx, "request-id", "user-42")
	ctx = context.WithValue(ctx, "request-id", "trace-9f")

	// 第二次写入使用了相等键，读取结果不再能代表第一个包的意图。
	fmt.Println(ctx.Value("request-id"))
}

这也是为什么“我已经把字符串写得很长了”不是可靠修复。只要其他包能构造出同一个字符串，碰撞仍然存在；前缀只能降低概率，不能形成类型层面的隔离。更隐蔽的情况是某个中间件升级后新增同名键，原本正常的读取逻辑会悄悄改变。

可比较不等于跨包唯一

WithValue 要求 key 支持相等比较，所以切片、映射和函数不能作为键；字符串、整数、指针和结构体等类型通常可以比较。但“能比较”回答的是 API 能不能接收，“谁拥有这个键”回答的才是工程隔离问题。

官方文档推荐包定义自己的键类型，并用未导出的类型或键变量避免碰撞。即使两个包都声明了名字相同的 type key struct{}，它们仍是不同的命名类型；真正需要避免的是把键本身导出，让外部代码依赖实现细节。

用私有键类型和访问器收窄边界

把键和值的规则收回所属包，调用方只看到 WithUser 和 FromContext。这样做不只是换一种写法：写入位置统一，读取时的类型断言统一，后续替换值结构也不会让所有调用方同时修改。

package userctx

import "context"

type User struct {
	ID string
}

// contextKey 只服务于本包，避免与其他包的键相等。
type contextKey struct{}

// userKey 不导出，调用方不能拿一个字符串或外部变量绕过访问器。
var userKey contextKey

func WithUser(ctx context.Context, user *User) context.Context {
	// 只把请求范围内确实需要跨 API 传递的用户对象放入 Context。
	return context.WithValue(ctx, userKey, user)
}

func FromContext(ctx context.Context) (*User, bool) {
	// 把 any 到 *User 的断言集中在包内，避免调用方重复断言。
	user, ok := ctx.Value(userKey).(*User)
	return user, ok
}

访问器返回 bool 很重要：Context 中可能没有用户，也可能值类型不符合约定，调用方不能把缺失值误当成匿名用户。若值本身是可选参数、函数配置或临时开关，也不要为了少传一个参数就塞进 Context；官方建议 Context 值只承载请求范围的数据，并沿 API 边界传播。

迁移已有代码时先查这份清单

• 搜索 context.WithValue 的第二个参数，找出字符串、通用整数和导出变量。
• 确认键的所有读写是否都属于同一个包；跨包共享时优先暴露访问器，而不是暴露 key。
• 检查 ctx.Value 后的类型断言，把重复断言和默认值策略收回拥有者包。
• 确认放入 Context 的确实是请求范围数据，不要把业务可选项伪装成隐式参数。
• 为旧键与新键安排兼容窗口时，明确两者是否需要同时读取，避免用字符串前缀制造长期双写。

相关问题

自定义字符串类型能不能当 Context 键？

可以，只要它是可比较类型；例如包内未导出的 type key string 与内置 string 不相等。但若键类型或变量被导出，调用方仍可能依赖实现，通常不如私有空结构体清晰。

Context 键使用指针是不是一定更好？

不一定。指针可作为键，但需要管理其身份；对单一包内的请求值，私有 struct{} 键通常更直观。选择重点是所有权、不可碰撞和访问器边界。

把 key 导出后让其他包直接读取可以吗？

技术上可以，但会让外部代码绑定键和值类型，后续无法安全演进。更稳妥的 API 是导出写入和读取函数，把底层键留在定义它的包内。