context.WithValue 的 key 怎样避免跨包冲突

在多个 Go 包共同处理一个请求时，context.WithValue 的 key 如果使用字符串或导出的基础类型，最容易出现的不是编译错误，而是不同包“恰好用了同一个 key”，导致值被覆盖或读取到了错误类型。稳妥做法是：把 key 类型和 key 值都留在拥有这份请求数据的包内，再提供类型化的写入、读取函数。

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

跨包避免冲突的核心不是给字符串加前缀，而是让 key 的定义类型保持包内私有，并让其他包只能通过访问函数取得值。

为什么字符串 key 会留下跨包冲突

WithValue 会返回一个带有键值对的派生 Context，之后通过 Value(key) 查找。key 必须是可比较的值；它不会替你建立“这个字符串属于哪个包”的命名空间。

下面的写法在小程序里看似直观，但随着中间件和业务包增多会变得脆弱：

package middleware

import "context"

func AttachUserID(ctx context.Context, id int64) context.Context {
	// 字符串属于共享命名空间，其他包也可能使用同一个字面量。
	return context.WithValue(ctx, "userID", id)
}

func UserID(ctx context.Context) (int64, bool) {
	// key 一旦被其他包复用，读取到的值就可能不是本包写入的值。
	id, ok := ctx.Value("userID").(int64)
	return id, ok
}

另一个问题是，调用方可以直接依赖这个字符串，久而久之 key 就成了没有类型约束的隐式 API。改名、换值类型或引入第三方中间件时，问题通常只在运行时暴露。

把 key 类型和 key 值藏在所属包

Go 官方 context 文章给出的思路是定义未导出类型，让本包的 key 与其他包的同名 key 在类型层面天然不同。下面用一个专门的 key 类型保存请求 ID：

package requestmeta

import "context"

// requestIDKey 只在本包可见，其他包无法声明同一命名类型的 key。
type requestIDKey struct{}

// requestIDKeyValue 是本包唯一的请求 ID key，不导出给调用方。
var requestIDKeyValue requestIDKey

// WithRequestID 只负责把请求 ID 放入派生 Context。
func WithRequestID(ctx context.Context, id string) context.Context {
	return context.WithValue(ctx, requestIDKeyValue, id)
}

// RequestID 返回请求 ID；缺失或类型不符时返回 false。
func RequestID(ctx context.Context) (string, bool) {
	id, ok := ctx.Value(requestIDKeyValue).(string)
	return id, ok
}

这里的关键不在变量名，而在 requestIDKey 是未导出且由当前包定义的类型。另一个包即使也写出 type requestIDKey struct{}，那也是另一个定义类型，放入 Context 的 key 不会相等。

用访问函数隔离写入和类型断言

不要让业务包直接调用 ctx.Value 并自行断言。把写入、读取和缺失值策略放到同一个包，调用方只依赖语义明确的函数：

package handler

import (
	"context"
	"fmt"

	"example.com/app/requestmeta"
)

func handle(ctx context.Context) error {
	// 入口统一写入，后续函数只接收普通 context.Context。
	ctx = requestmeta.WithRequestID(ctx, "req-20261113-001")
	return audit(ctx)
}

func audit(ctx context.Context) error {
	// 读取函数同时完成查找和类型断言，调用方不接触私有 key。
	id, ok := requestmeta.RequestID(ctx)
	if !ok {
		// 缺失值按业务约定处理，避免把空字符串误当成有效 ID。
		return fmt.Errorf("request id is missing")
	}
	fmt.Println("audit request", id)
	return nil
}

这种封装还有一个工程收益：将来把值从字符串改成结构体，或者增加格式校验时，只修改所属包的访问函数，调用方的依赖面不会扩张。

同一个包需要多个 key 时怎么区分

一个包如果要存放用户 ID、租户 ID 和追踪标识，不要共用一个 key 再依赖值类型猜含义。可以为每个语义定义独立的未导出类型；如果使用同一个 key 类型，则至少让不同 key 值可区分。

package requestmeta

import "context"

// 每种请求元数据使用自己的未导出类型，避免语义混用。
type tenantKey struct{}
type traceKey struct{}

var tenantKeyValue tenantKey
var traceKeyValue traceKey

func WithTenant(ctx context.Context, tenant string) context.Context {
	// tenantKeyValue 只负责租户标识，不与 traceKeyValue 复用。
	return context.WithValue(ctx, tenantKeyValue, tenant)
}

func WithTraceID(ctx context.Context, traceID string) context.Context {
	// traceKeyValue 只负责链路标识，读取时类型保持稳定。
	return context.WithValue(ctx, traceKeyValue, traceID)
}

如果选择用一个未导出整数类型承载多个 key，也要保证每个常量值不同；不过独立类型更容易在代码审查中看出用途，通常更适合长期维护。

四类写法要在审查时直接拦截

官方文档还特别强调，Context value 应用于跨 API 传递的请求范围数据，而不是可选参数。比如认证身份、请求 ID、租户标识可以放进去；分页大小、排序字段、业务开关则更适合成为函数参数或业务对象字段。

发布前用这份清单检查

在提交涉及 context.WithValue 的代码前，可以按下面顺序快速检查：

1. key 的定义类型是否由所属包私有声明，调用方能否直接构造？
2. 同一个包内的不同语义是否使用了不同 key？
3. 是否提供了成对的写入函数和读取函数，并在读取处统一处理缺失值？
4. 值是否只在请求生命周期内有效，且能安全地被多个 goroutine 同时读取？
5. 这个数据是否其实是函数必需参数；如果是，就不要隐藏到 Context 里？

归纳起来，避免跨包冲突要靠“私有定义类型 + 私有 key 值 + 类型化访问函数”三件套。它既解决 key 的唯一性，也把值类型和缺失值策略固定在一个包的边界内。

相关问题

两个包都使用字符串 userID，会立刻冲突吗？

只要它们作用在同一个 Context 链上，就可能读取或覆盖同名 key 对应的值；是否立刻出错取决于值类型和调用顺序，正因为不稳定才应该避免。

key 使用指针一定比未导出类型更安全吗？

指针可以表达实例身份，但并不能替代包内封装。对单个包的请求元数据，未导出类型配合未导出 key 值已经足够清晰；关键是不要把 key 暴露成公共 API。

Context value 适合存放大型对象吗？

通常不适合。Context value 应保持为少量请求范围元数据；大型对象、可变业务状态和可选配置应使用明确的数据结构管理。