Go context.WithValue 怎么避免把业务参数塞进上下文

如果一个函数只有拿不到 userID 或订单号才能完成工作，就把它们写进函数参数；如果一个值代表请求链路中的元数据，例如 trace_id、认证主体或租户标识，才考虑用 context.WithValue 传播。这样做的核心不是“少写几个参数”，而是让取消、超时和业务数据各自留在清晰的边界里。

WithValue 该放什么：请求元数据，不是业务参数

判断一个值是否适合放进 Context，可以问一句：它是否随着一次请求跨越多个 API 边界，并且不属于某个业务动作本身？链路追踪 ID、认证后的主体、租户标识通常符合；“查询哪一页”“要买哪个商品”“是否只看已支付订单”则不符合。后者改变业务结果，应该在签名中可见。

把业务输入移回函数签名，调用关系才不会隐形

把订单号塞进 Context 的短期好处是少传一个参数，长期代价是函数的真实依赖消失了：调用者看不出它需要什么，测试还得先构造一棵 Context 链。迁移时可以先把读取逻辑改成显式参数，再逐层删除旧的 Value。

type OrderService struct {
	repo OrderRepository
}

func (s *OrderService) Load(ctx context.Context, userID, orderID string) (Order, error) {
	// userID 和 orderID 是业务动作的必需输入，直接写在签名里。
	if userID == "" || orderID == "" {
		return Order{}, errors.New("userID and orderID are required")
	}
	// ctx 只负责把取消和超时信号传给下游 I/O。
	return s.repo.Find(ctx, userID, orderID)
}

这里的 ctx 仍然重要，但它表达的是“这次工作还能不能继续”，不是“这次工作要查哪个订单”。如果未来增加权限校验或审计，调用者也能从参数和返回值中看到完整契约。

用私有 key 和访问器把类型断言收口

请求元数据确实需要跨层传递时，不要使用字符串 key，也不要让每个调用方重复写 value := ctx.Value(...)。用包内私有类型作 key，再提供类型化的写入和读取函数，把实现细节关在一个小范围内。

package requestmeta

import "context"

type requestIDKey struct{}

func WithRequestID(ctx context.Context, id string) context.Context {
	// 空 ID 不产生有意义的元数据，保留原 Context 更容易排查。
	if id == "" {
		return ctx
	}
	return context.WithValue(ctx, requestIDKey{}, id)
}

func RequestID(ctx context.Context) (string, bool) {
	// 断言集中在访问器中，调用方不需要知道 key 的具体类型。
	id, ok := ctx.Value(requestIDKey{}).(string)
	return id, ok
}

key 也可以定义为包级变量，但私有空结构体类型更不容易和其他包发生碰撞。访问器返回 (value, ok)，比缺失时悄悄得到零值更容易发现中间件漏挂或请求链路不完整。

按 API 边界传播，再用清单收口旧代码

每个需要取消或超时的函数都把 context.Context 放在第一个参数位置，并继续传给数据库、HTTP 客户端等下游调用；不要把 Context 存进结构体，也不要用 nil 代替未知上下文。进入迁移收尾时，逐项检查：

• 删掉 ctx.Value("userID")、ctx.Value("orderID") 这类业务读取，并改为显式参数。
• 保留 trace、认证主体、租户等请求范围元数据，并为每类元数据提供私有 key 与访问器。
• 检查 goroutine、数据库和 HTTP 调用是否监听 ctx.Done() 或把 ctx 继续下传。
• 测试缺失元数据、空业务参数和已取消 Context，确认错误能落在正确的层。

常见问题

把 userID 放进 Context 能不能少改很多函数？

可以暂时减少参数改动，但会隐藏业务依赖；新代码应优先使用显式参数，迁移旧代码时也应逐步拆出。

Context Value 能不能存一个业务配置结构体？

只有当它是请求范围的元数据并且需要跨 API 边界传播时才合适。业务配置、筛选条件和领域对象更适合显式传递。

读取不到请求 ID 时应该直接 panic 吗？

通常不应该。访问器返回布尔值，让边界层决定记录日志、补默认值或拒绝请求；核心业务不要把缺失元数据当成正常业务输入。