应使用未导出私有类型作 context key（如 versionKey），避免 string/int 字面量导致冲突；在中间件解析校验版本后注入 Context；透传时需显式读取并设置 header/metadata，不可依赖自动机制。
Context里不能直接塞版本号字符串
Go 的 context.Context 本身不存储任意数据，必须通过 context.WithValue 显式挂载。但直接传 "v1" 这类裸字符串极易引发类型冲突和 key 冲突——不同包都用 string 当 key，一覆盖就丢数据。
正确做法是定义私有类型作为 key：
type versionKey struct{}
func WithAPIVersion(parent context.Context, version string) context.Context {
return context.WithValue(parent, versionKey{}, version)
}
func GetAPIVersion(ctx context.Context) (string, bool) {
v, ok := ctx.Value(versionKey{}).(string)
return v, ok
}
- key 必须是未导出类型（如
versionKey），避免跨包污染 - 不要用
int或string字面量当 key，哪怕看起来“唯一”也不安全 -
GetAPIVersion做类型断言并返回bool，调用方必须检查是否获取成功
HTTP handler 中提取并校验版本信息
API 版本通常从请求头（如 X-API-Version）或 URL 路径（如 /v2/users）来。Context 只负责透传，解析和校验要提前做。
常见错误是：在中间件里解析完版本，却忘了写入 Context，导致下游 handler 拿不到；或者写了但没校验合法性，让非法版本（如 v999）一路透传下去。
- 推荐在最外层路由/中间件中完成解析 + 校验 + 注入三步，例如：
- 若版本非法，应立即返回
400 Bad Request或406 Not Acceptable，不要依赖下游判断 - 路径中的版本前缀（如
/v1/）建议由路由器（如gorilla/mux或chi）提取后传入，而非手动strings.Split(r.URL.Path, "/")
下游服务调用时透传版本信息
当你用当前请求的 Context 发起 HTTP 或 gRPC 调用时，版本信息不会自动附到请求头里——context.WithValue 只影响 Go 层逻辑，不修改 wire 协议。
必须显式读取并注入：
if ver, ok := GetAPIVersion(r.Context()); ok {
req.Header.Set("X-API-Version", ver)
}
resp, err := http.DefaultClient.Do(req)
- gRPC 场景下要用
metadata.MD手动附加：metadata.Pairs("x-api-version", ver) - 如果调用链涉及多个跳转（A→B→C），每跳都要重复这个“读取→设置 header/metadata”的动作
- 别假设下游服务会忽略未知版本头——它可能拒收、降级或静默 fallback，行为必须明确约定
为什么不用中间件自动加 header？
看似可以封装成通用中间件，但实际容易踩坑：
- 不是所有 outbound 请求都需要透传版本（比如调第三方支付 API，对方根本不认
X-API-Version） - 有些下游服务要求版本放在 query 参数（
?api_version=v2）而非 header，硬统一反而增加耦合 - 测试时容易漏掉 mock 的 outbound client，导致版本丢失却无报错
更稳妥的做法是：只在真正需要透传的调用点，显式读取 + 显式设置。代码略冗余，但意图清晰、可测、不易遗漏。
真正的难点不在怎么塞进 Context，而在于版本语义的一致性——同一个 v1 在不同服务里是否代表相同字段格式、兼容策略和生命周期？这得靠接口契约和文档，Context 只是搬运工。
