只在 Context 中携带请求级元数据而不传业务参数

Go 的 context.Context 适合沿请求链传递 trace ID、租户标识、语言偏好这类请求级元数据；订单号、分页条件、筛选器等业务输入应该继续作为显式参数传递。这样做的关键不是“少写几个参数”，而是让函数签名清楚表达业务依赖，让 Context 只承担跨 API 的请求控制和小型元数据。

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

一、先划清 Context 与业务参数的边界

一个实用判断标准是：这个值是否会随着同一个请求跨越多个 API 边界？如果答案是“会”，且它描述的是请求环境而不是业务对象，可以考虑放进 Context。trace_id、请求来源和语言偏好属于这一类；orderID、商品数量、页码和排序字段则决定业务行为，应保留在参数列表或请求结构体中。

不要用 ctx.Value("orderID") 把业务参数藏起来。调用方看函数签名无法知道它依赖什么，测试也必须额外构造一棵 Context 树；一旦 key 拼写改变，错误可能只在运行时出现。

二、用私有类型键安全地写入和读取元数据

WithValue 的 key 不建议直接使用字符串。包内定义一个私有类型，再为不同元数据定义常量，可以避免不同包使用相同字符串造成碰撞；读取时用类型断言，缺失值则明确返回。

package requestmeta

import "context"

// key 是包私有类型，避免与其他包的 Context key 发生碰撞。
type key int

const traceIDKey key = iota

// WithTraceID 只写入请求级追踪信息，不接收订单等业务参数。
func WithTraceID(ctx context.Context, id string) context.Context {
	return context.WithValue(ctx, traceIDKey, id)
}

// TraceID 在缺少元数据时返回空字符串，让调用方决定是否降级。
func TraceID(ctx context.Context) string {
	id, _ := ctx.Value(traceIDKey).(string)
	return id
}

这里的值应该小而稳定，通常用于日志、链路追踪或请求级策略。不要把可变的大对象、密码、数据库事务状态塞进 Value；这些内容要么应显式传递，要么应由专门的依赖注入或业务对象管理。

三、让 API 签名表达真实依赖

Context 应放在第一个参数，业务参数继续保持可见。下面的服务方法可以同时访问请求级 trace ID 和订单号，但两者的来源清楚可见：

type OrderService struct {
	repo OrderRepository
}

// Load 让 ctx 负责请求控制，让 orderID 明确表达业务输入。
func (s *OrderService) Load(ctx context.Context, orderID string) (Order, error) {
	if err := ctx.Err(); err != nil {
		return Order{}, err // 请求已取消时，不再发起下游读取。
	}
	return s.repo.Find(ctx, orderID)
}

调用代码也更容易审查：service.Load(ctx, orderID) 一眼能看出业务参数是什么。若以后加入分页或租户隔离，可以扩展参数结构体，而不是在 Context 中不断增加隐式字段。

四、把取消传播与测试边界补齐

元数据和取消信号可以在同一棵 Context 派生链上共存，但它们的职责不同。请求入口创建超时 Context，下游 API 和存储层接收同一个 ctx；调用结束后执行 cancel，避免定时器和派生 Context 长时间存活。

func Handle(ctx context.Context, orderID string) error {
	// 由当前请求派生超时边界，结束时释放相关资源。
	ctx, cancel := context.WithTimeout(ctx, 800*time.Millisecond)
	defer cancel()

	ctx = requestmeta.WithTraceID(ctx, "trace-demo")
	if err := loadAndStore(ctx, orderID); err != nil {
		if errors.Is(err, context.DeadlineExceeded) {
			return fmt.Errorf("订单读取超时: %w", err) // 保留可判断的根因。
		}
		return err
	}
	return nil
}

测试时分别覆盖三种边界：没有 trace ID 时日志是否能降级；业务参数为空时是否按业务规则报错；ctx 被取消后下游是否停止等待。这样能避免把“元数据缺失”和“业务参数非法”混成同一种错误。

五、适用范围与检查清单

最后检查四点：ctx 是否位于第一个参数；下游是否继续接收并使用 ctx；每个 WithCancel、WithTimeout 是否有对应的 cancel；Value 的 key 是否为私有类型。四项都满足时，Context 才是在传递请求级信息，而不是在掩盖 API 设计问题。

相关问题

Context 能不能保存用户 ID？

如果用户 ID 只用于本次请求的审计或鉴权传播，可以作为请求级元数据；若它是业务查询条件，仍应作为显式参数传递。

为什么不建议用字符串作为 Context key？

不同包可能使用相同字符串，私有 key 类型能把冲突从运行时风险降为编译期隔离。

WithTimeout 到期后还要调用 cancel 吗？

要。超时会触发取消，但 defer cancel 能及时释放派生 Context 关联的资源，并让代码在提前返回时也保持正确。