Context传递架构本质是请求作用域的契约设计，核心在于明确“谁该传、传什么、不传什么”；应使用私有空结构体作键、仅存轻量元数据、显式透传、ctx必为函数首参，并严格遵循“必然需要且无法更清晰表达”才放入Context。
Context传递架构不是“怎么传”，而是“谁该传、传什么、不传什么”——它本质是请求作用域的契约设计，不是数据搬运工。
context.WithValue 的键必须是私有未导出类型
用 string 或 int 当键，等于把类型安全和语义信息全扔掉。运行时一旦键名拼错或重复，ctx.Value() 返回 nil 或错误类型，且编译器完全不报错。
正确做法是定义不可导出的空结构体作为键：
type userKey struct{}
然后封装存取逻辑：
立即学习“go语言免费学习笔记（深入）”；
func WithUser(ctx context.Context, u *User) context.Context { return context.WithValue(ctx, userKey{}, u) }func UserFrom(ctx context.Context) (*User, bool) { u, ok := ctx.Value(userKey{}).(*User); return u, ok }
这样既避免键冲突，又把类型断言收口到一处，后续改类型也不用满代码库搜 .(User)。
绝不往Context里塞业务实体或大对象
context.WithValue 适合存轻量元数据：请求ID（string）、用户ID（int64）、租户标识（uuid.UUID）、traceID（string）等。业务实体如 *Order、map[string]interface{}、JSON字节流，都属于反模式。
原因很直接：
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 内存泄漏风险：Context生命周期常覆盖整个请求，大对象无法及时 GC
- 隐蔽耦合：下游函数靠
ctx.Value()拿业务对象，等于绕过参数签名，调用关系不透明 - 测试困难：单元测试时需手动构造完整 Context 链，而非直接传参
真正需要传递的业务数据，应显式作为函数参数；Context 只负责透传“上下文身份”，不是“数据中转站”。
HTTP 中间件链必须显式透传 Context
Go 的 http.Handler 接口不带 context.Context 参数，所以中间件必须自己从 http.Request 提取并注入 Context，再调用下一层 handler。常见错误是忘记重赋值 r = r.WithContext(newCtx)：
func authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// ✅ 正确：提取 token 后创建新 ctx，并写回 request
ctx := r.Context()
userID := parseUserID(r.Header.Get("X-User-ID"))
ctx = context.WithValue(ctx, userKey{}, userID)
r = r.WithContext(ctx) // ← 这行漏掉，下游拿不到
next.ServeHTTP(w, r)
})
}
漏掉这行，下游所有 r.Context().Value() 都是空的。这不是 bug，是设计契约没履行。
跨 goroutine 传递时，Context 必须作为第一个参数
这是 Go 社区事实标准，也是 go vet 会检查的规范。函数签名形如：
func ProcessOrder(ctx context.Context, orderID string) error
而不是：
func ProcessOrder(orderID string, ctx context.Context) error // ❌
原因有三：
- 取消信号必须可被所有子 goroutine 观察到，第一个参数最易被统一处理
- 工具链（如 trace、metrics 注入）依赖此约定自动提取 ctx
- 多人协作时，看到函数以
ctx context.Context开头，立刻知道它支持取消/超时
如果某个函数内部启动了 goroutine 却没把 ctx 传进去，那个 goroutine 就成了“孤儿协程”——父请求已取消，它还在跑，资源不释放，日志无上下文，debug 时根本找不到它。
最难的从来不是怎么写 WithValue，而是每次想往 Context 塞东西前，先问一句：这个值是不是所有下游函数都**必然需要**，且**无法通过参数或返回值更清晰地表达**？如果不是，就别塞。
