不能将 context.context 当普通参数塞入 struct，因其不可变且携带取消、超时、值等动态状态，长期持有会导致 goroutine 泄漏、取消失效、值传递错乱；应显式传参、派生使用、不缓存不嵌入。
为什么不能把 context.Context 当普通参数随便塞进 struct？
因为 context.Context 是不可变（immutable）且携带取消信号、超时、值等动态状态的“运行时上下文”，一旦被封装进 struct 并长期持有，就容易导致：goroutine 泄漏（比如子 context 被父 context 取消后，struct 仍强引用它，阻止 GC）、取消信号失效（struct 持有旧 context，新 cancel 不生效）、值传递错乱（context.WithValue 链断裂）。
正确做法是：每个函数显式接收 ctx context.Context 参数，并在调用下游时传入派生出的新 context（如 context.WithTimeout 或 context.WithValue），不缓存、不嵌入、不跨 goroutine 长期保存。
- 所有 I/O 操作（
http.Client.Do、sql.DB.QueryContext、time.Sleep等）必须传入当前ctx - 若需携带业务数据，用
context.WithValue+ 自定义 key 类型（绝不用string），且仅限必要元数据（如 traceID、user.ID） - 避免在 handler 中直接用
context.Background()创建子 context——应从入参ctx派生
context.WithCancel 和 context.WithTimeout 的取消时机差异
两者都返回 cancel() 函数，但触发条件不同：WithCancel 是手动调用 cancel() 才触发；WithTimeout 在时间到达或手动调用 cancel() 时都会触发。关键区别在于：超时是单次倒计时，不可重置，而 cancel 是可多次调用（后续调用无效果）的幂等操作。
常见误用：在 for-select 循环中反复调用 context.WithTimeout(ctx, time.Second)，每次都会新建 timer，造成 goroutine 泄漏（timer 不被回收）。正确方式是复用同一个带 timeout 的 context，或用 time.AfterFunc + 显式控制。
-
context.WithDeadline更精确（指定绝对时间点），适合服务间 SLA 对齐；WithTimeout更常用，但注意其基于time.Now()计算，受系统时间跳变影响 - 取消后，
ctx.Err()返回context.Canceled或context.DeadlineExceeded，应据此清理资源（如关闭 channel、释放锁） - 不要依赖
ctx.Done()关闭后的 channel 状态做逻辑分支——它只保证关闭，不保证立即可读
HTTP handler 中如何透传 traceID 并注入到 downstream request？
链路追踪依赖 traceID 在整个调用链中稳定传递。Go 标准库不自动解析 HTTP header 中的 traceID，必须手动提取并注入到新 context 中。典型流程是：从 req.Header.Get("X-Trace-ID") 获取，用自定义 key 注入 context，再通过 req.WithContext 透传给下游 HTTP client。
type traceKey struct{}
func extractTraceID(ctx context.Context, r *http.Request) context.Context {
traceID := r.Header.Get("X-Trace-ID")
if traceID == "" {
traceID = uuid.New().String()
}
return context.WithValue(ctx, traceKey{}, traceID)
}
// 下游调用时
req, _ := http.NewRequestWithContext(ctx, "GET", "http://svc-b/", nil)
req.Header.Set("X-Trace-ID", ctx.Value(traceKey{}).(string))
- key 必须是 unexported 类型（如
traceKey struct{}），防止第三方包冲突；绝不用string或int作 key - 下游服务收到请求后，也应同样提取并注入自己的 context，形成链路闭环
- 若使用 OpenTelemetry，优先用
otel.GetTextMapPropagator().Inject替代手写 header 传递，兼容 W3C TraceContext 标准
goroutine 启动时忘记传 ctx 导致无法协同取消
这是最隐蔽的泄漏源：一个匿名 goroutine 内部没检查 ctx.Done()，也没把 ctx 传给它调用的任何阻塞操作（如 time.Sleep、ch := make(chan int); select { case ），结果父 context 取消后，goroutine 继续运行，直到自然结束或 panic。
尤其注意第三方库调用——比如 log.Printf 没问题，但 grpc.DialContext、redis.Client.Do 等必须传 ctx，否则连接建立过程无法中断。
- 启动 goroutine 前，先确认是否已从上游拿到有效
ctx；若没有，至少用context.Background()，但要清楚这意味着无法被外部取消 - 对 channel 操作，永远用
select包裹，且第一个 case 必须是 - 避免在 goroutine 中直接调用
time.Sleep—— 改用time.After或time.NewTimer并监听ctx.Done()
context.WithCancel 就能跑通的，而是每个函数签名、每次 goroutine 启动、每条 HTTP 请求头、每一个第三方库调用，都要持续对齐 context 的生命周期。最容易被忽略的，其实是那些“看起来不耗时”的小操作——它们恰恰最容易漏掉 ctx，最后卡住整个取消链。
