23.上下文取消与传播

卷三第 23 篇——聚焦 Go 服务端最核心的并发控制原语：context。本篇从 context.Context 接口出发，拆解四种内置实现的内部结构、取消信号的传播算法、WithTimeout 的定时器联动、以及 Go 1.20+ 引入的 WithCancelCause 和 AfterFunc。关键词：cancelCtx 子节点链表、Done() 管道关闭、timerCtx 定时器、valueCtx O(N) 查找、取消传播的递归深度、goroutine 泄漏的 context 根因。

目录介绍

• 1. 案例引入
  • 1.1 一段崩在哪
  • 1.2 顺藤摸到根因
  • 1.3 我们要回答什么
• 2. 架构概览
  • 2.1 Context 树形结构
  • 2.2 为什么不用全局变量
• 3. Context 接口与 emptyCtx
  • 3.1 接口的四方法设计
  • 3.2 Background 与 TODO 本质
• 4. cancelCtx 取消实现
  • 4.1 cancelCtx 内部结构
  • 4.2 WithCancel 创建链路
  • 4.3 cancel 的传播算法
• 5. timerCtx 超时机制
  • 5.1 timerCtx 与 cancelCtx 的关系
  • 5.2 WithTimeout 的定时器联动
  • 5.3 超时后的清理路径
• 6. valueCtx 链式查找
  • 6.1 valueCtx 的链表结构
  • 6.2 O(N) 查找的代价
  • 6.3 valueCtx 与其他 Ctx 共存
• 7. 取消传播深层剖析
  • 7.1 Done 管道的创建时机
  • 7.2 父子取消的并发安全
  • 7.3 取消原因的传播链
• 8. 高级特性
  • 8.1 WithCancelCause 错误传播
  • 8.2 AfterFunc 回调注册
• 9. 诊断与陷阱
  • 9.1 未调 cancel 的 goroutine 泄漏
  • 9.2 pprof 定位 context 泄漏
  • 9.3 常见反模式
• 10. 综合案例串讲
  • 10.1 案例真相揭晓
  • 10.2 一次 context 取消的完整路径
  • 10.3 设计哲学回扣
  • 10.4 速查表

1. 案例引入

1.1 一段崩在哪

某个支付网关服务——用户发起一笔支付请求，网关并行调三个下游服务做风控校验、余额检查、库存锁定。稳定运行半年后，某天下午突然 goroutine 数从 200 飙升到 35000，RSS 从 400MB 涨到 8GB，K8s OOM Kill 后重启循环。

// payment_gateway.go —— 支付网关核心路径
package main

import (
    "context"
    "errors"
    "fmt"
    "sync"
    "time"
)

func handlePayment(ctx context.Context, orderID string) error {
    // 创建 3 秒超时的支付级 context
    payCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()  // ← 这里写了 defer cancel，但是...

    var wg sync.WaitGroup
    errCh := make(chan error, 3)

    // 并行调用三个下游
    wg.Add(3)

    // 风控校验
    go func() {
        defer wg.Done()
        // 注意：这里传的是 payCtx
        errCh <- fraudCheck(payCtx, orderID)
    }()

    // 余额检查
    go func() {
        defer wg.Done()
        errCh <- balanceCheck(payCtx, orderID)
    }()

    // 库存锁定
    go func() {
        defer wg.Done()
        errCh <- inventoryLock(payCtx, orderID)
    }()

    // 等待第一个结果——但有一个致命 bug
    wg.Wait()
    close(errCh)

    for err := range errCh {
        if err != nil {
            return err
        }
    }
    return nil
}

func fraudCheck(ctx context.Context, orderID string) error {
    // 风控需要 2.8 秒（第三方模型推理）
    select {
    case <-time.After(2800 * time.Millisecond):
        return nil  // 模拟风控通过
    case <-ctx.Done():
        return ctx.Err()
    }
}

func balanceCheck(ctx context.Context, orderID string) error {
    // 余额检查只需要 200ms
    select {
    case <-time.After(200 * time.Millisecond):
        // 假如余额不足
        return errors.New("insufficient balance")
    case <-ctx.Done():
        return ctx.Err()
    }
}

func inventoryLock(ctx context.Context, orderID string) error {
    // 库存锁定 500ms
    select {
    case <-time.After(500 * time.Millisecond):
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

现象：

• 正常时段：每次支付在 500ms 内完成，goroutine 数稳定
• 热点时段（促销）：大量余额不足的请求——balanceCheck 在 200ms 返回错误
• 但 fraudCheck 需要 2.8 秒——即使 handlePayment 已经知道余额不足，也必须等风控返回
• 更致命的是：wg.Wait() 等待所有三个 goroutine 完成后才返回——上游每次请求阻塞 2.8 秒
• 500 个并发请求 × 每个 3 个 goroutine = 1500 个 goroutine 同时在跑——但 QPS 继续升高
• 更严重的 bug：某次重构中，有人把部分下游调用的 context 直接从 payCtx 换成了 context.Background()——脱离了父 context 的取消控制

1.2 顺藤摸到根因

追查：

• 假设 1：是不是 wg.Wait() 阻塞太久？—— 是，但这是表象。真正的问题是：balanceCheck 已经返回错误了，为什么还需要等 fraudCheck？

• 假设 2：是不是应该用 errgroup？—— errgroup 会在第一个错误时取消其他 goroutine——但前提是所有 goroutine 都正确监听 context 的 Done 通道。本案例的 fraudCheck 确实监听了 ctx.Done()，但业务逻辑中 time.After 是独立于 context 的——即使 context 被取消了，time.After 的定时器仍在跑。

• 假设 3：有没有 goroutine 泄漏？—— 看 pprof：

$ go tool pprof http://localhost:6060/debug/pprof/goroutine
(pprof) top
Showing nodes accounting for 32487, 98% of 33150 total
      flat  flat%   sum%        cum   cum%
     11200 33.78% 33.78%      11200 33.78%  select
      8700 26.25% 60.03%       8700 26.25%  time.Sleep
      5400 16.29% 76.32%       5400 16.29%  runtime.gopark

$ curl http://localhost:6060/debug/pprof/goroutine?debug=2 | grep -c "fraudCheck"
11200

11200 个 goroutine 卡在 fraudCheck——但此时网关已经因为上游熔断不再接收新请求，这些 goroutine 应该被取消才对。

• 根本原因：handlePayment 中使用了 wg.Wait() 等待所有 goroutine 完成——但 payCtx 的 cancel() 只会在函数返回时执行（defer cancel()），而函数返回又被 wg.Wait() 阻塞。形成死锁式的循环等待：
  • wg.Wait() 等 fraudCheck goroutine 完成
  • fraudCheck 等 2.8 秒 time.After 或 ctx.Done()
  • ctx 的 cancel 在 defer 中——要等 wg.Wait() 返回才能执行

正确的做法：balanceCheck 返回错误后，立即调用 cancel() 通知 fraudCheck 和 inventoryLock 停止等待——但代码中 cancel 被 defer 绑在函数结尾，而函数结尾被 wg.Wait() 卡死。

这个事故藏着至少 7 个原理点：

① Context 接口定义了什么方法？Done() 通道什么时候关闭？          → 第 3 章
② WithCancel 创建的 cancelCtx 如何管理子 context 链表？         → 第 4 章
③ WithTimeout 内部如何把定时器和 cancel 机制合二为一？          → 第 5 章
④ WithValue 的值查找为什么是沿着父链 O(N) 遍历？               → 第 6 章
⑤ cancel() 如何递归通知所有派生 context？并发安全怎么保证？      → 第 7 章
⑥ WithCancelCause 相比 WithCancel 多了什么？                   → 第 8 章
⑦ pprof 如何定位「context 未取消导致的 goroutine 泄漏」？       → 第 9 章

1.3 我们要回答什么

这个支付网关的案例就是本篇的主线案例。我们从 context.Context 接口设计出发，逐个拆解四种内置实现——emptyCtx、cancelCtx、timerCtx、valueCtx——然后深入取消传播的并发算法，最后回到支付网关，给出基于 errgroup + 主动 cancel 的根治方案。

本篇路线：

接口设计 (第 3 章) ── Context 为什么只需要 4 个方法
   ↓
取消实现 (第 4 章) ── cancelCtx 的子节点链表与递归取消
   ↓
超时机制 (第 5 章) ── timerCtx 如何捆绑定时器 + cancel
   ↓
值传递 (第 6 章) ── valueCtx 的不可变链表与 O(N) 代价
   ↓
传播算法 (第 7 章) ── Done 管道创建时机 + 并发安全
   ↓
高级特性 (第 8 章) ── WithCancelCause + AfterFunc
   ↓
诊断实战 (第 9 章) ── pprof 定位 context 泄漏
   ↓
综合案例 (第 10 章) ── 回到支付网关，彻底修复

📌 本篇定位：context 是 Go 并发体系中最"薄"却最"泛"的组件——每个 goroutine 生命周期都挂在某个 context 的 Done 通道上。读完本篇，我们能回答："一个 ctx.Done() 背后发生了什么？cancel() 调用到底走了多少行代码、触达了多少个 goroutine？"

2. 架构概览

2.1 Context 树形结构

Go 的 context 不是一棵"可见的树"——它是由指针串联的隐式树。每个派生操作（WithCancel、WithTimeout、WithValue）创建新节点，通过内部字段链接到父节点：

              context.Background()   ← 根节点 (emptyCtx)
                      │
              ctx = WithTimeout(bg, 3s)   ← timerCtx {parent: bg, children: [...], timer: ...}
                      │
        ┌─────────────┼─────────────┐
        │             │             │
  WithCancel(ctx)  WithValue(ctx,   WithTimeout(ctx, 500ms)
    payCtx            "traceID",      lockCtx
    │                 "abc123")       │
    │                   │             │
  fraudCheck(payCtx)   balanceCheck   inventoryLock(lockCtx)
  (cancelCtx 子节点)   (valueCtx)     (timerCtx 子节点)

取消传播的方向：

父 cancel() 被调用 (如: payCtx 的 cancel)
  │
  ├── 父的 Done 通道被关闭
  │     → 所有监听 payCtx.Done() 的 goroutine 收到零值
  │
  ├── 遍历父的 children map
  │     ├── 子 cancelCtx → 递归调用子.cancel()
  │     │     → 子.Done 通道关闭
  │     │     → 子的 children 也被递归取消
  │     │
  │     ├── 子 timerCtx → 取消定时器 → 调用 timerCtx.cancelCtx.cancel()
  │     │
  │     └── 子 valueCtx → 跳过 (valueCtx 没有 cancel 方法)
  │
  └── 父的 children map 被清空

关键结构关系（context/context.go）：

类型	嵌入	核心字段	实现的功能
emptyCtx	int	无	Background() / TODO()
cancelCtx	Context	mu, done, children, err, cause	WithCancel
timerCtx	cancelCtx	timer, deadline	WithTimeout / WithDeadline
valueCtx	Context	key, val	WithValue

2.2 为什么不用全局变量

疑惑：为什么 Go 需要用 context.Context 传递取消信号和超时——直接用一个全局 map[string]chan struct{} 不就行了吗？

论证：

1. 生命周期隔离——全局变量的生命周期是整个进程。一个 HTTP 请求的 context 应该在该请求处理完毕后被垃圾回收。全局变量做不到"请求级别的生命周期"。

2. 并发隔离——1000 个并发请求各需要自己的超时和取消通道。全局 map 需要 key 来区分——谁来生成全局唯一的 key？请求处理完成时谁来清理 map？遗漏清理就是内存泄漏。

3. 隐式继承——子 goroutine 应该能"自动"感知父 goroutine 的取消。如果用全局变量，每个子 goroutine 需要显式查找父 goroutine 对应的 key。context 通过函数参数传递——编译器强制子 goroutine 接收父 context。

4. 不可变性——context 是不可变的（immutable）。WithValue 不修改父 context，而是创建新节点。这避免了并发读写全局变量的 data race。

结论：context.Context 不是"更优雅的全局变量"——它是请求作用域的生命周期管理器。它把"信号传递"和"作用域"绑在一起——这正是全局变量做不到的。

3. Context 接口与 emptyCtx

3.1 接口的四方法设计

context.Context 只有四个方法（context/context.go）：

type Context interface {
    Deadline() (deadline time.Time, ok bool)  // 返回截止时间和是否有截止时间
    Done() <-chan struct{}                    // 返回只读通道——取消时关闭
    Err() error                               // 取消原因：Canceled 或 DeadlineExceeded
    Value(key any) any                        // 沿父链查找 key 对应的值
}

四个方法的职责分离：

方法	谁实现	典型行为
Deadline()	timerCtx 返回截止时间；其他返回 ok=false	调用方判断是否需要在截止时间前完成
Done()	cancelCtx 在 cancel() 调用时关闭；emptyCtx 返回 nil	调用方用 select { case <-ctx.Done(): ... } 等待取消
Err()	cancelCtx 返回 Canceled；timerCtx 超时返回 DeadlineExceeded	调用方判断取消原因
Value()	valueCtx 沿父链查找；cancelCtx 转发给嵌入的 parent	传递请求级元数据（traceID 等）

Done() 返回 <-chan struct{} 而非 <-chan bool 的设计考量：

// 为什么是 struct{} 而不是 bool？
// struct{} 零大小——通道本身只需要一个"关闭"信号，不需要传输数据
// 关闭通道本身就是一个事件信号——所有等待方同时收到零值

3.2 Background 与 TODO 本质

context.Background() 和 context.TODO() 返回的都是 emptyCtx：

// context/context.go
type emptyCtx int

func (*emptyCtx) Deadline() (deadline time.Time, ok bool) { return }
func (*emptyCtx) Done() <-chan struct{}                   { return nil }
func (*emptyCtx) Err() error                              { return nil }
func (*emptyCtx) Value(key any) any                       { return nil }

var (
    background = new(emptyCtx)
    todo       = new(emptyCtx)
)

func Background() Context { return background }
func TODO() Context       { return todo }

Done() 返回 nil 的关键含义：emptyCtx 永远不会被取消。select { case <-ctx.Done(): } 在 ctx 是 Background() 时永远阻塞——<-nil 在 Go 中是永久阻塞。

Background 与 TODO 的区别：

场景	使用
main 函数、初始化、测试的顶层 context	context.Background()
尚未确定使用哪种 context 的占位符	context.TODO()

两者在实现上完全相同——区别仅在于语义，告诉代码阅读者"这是有意为之"还是"这是临时占位"。

4. cancelCtx 取消实现

4.1 cancelCtx 内部结构

// context/context.go (简化)
type cancelCtx struct {
    Context          // 嵌入父 context——组合而非继承

    mu       sync.Mutex            // 保护 done、children、err 字段
    done     atomic.Value          // 惰性创建：存储 chan struct{}，取消时 close
    children map[canceler]struct{} // 所有直接子 context（在 cancel 被调用时一次性取消）
    err      error                 // 取消原因：Canceled
    cause    error                 // WithCancelCause 设置的原因
}

关键设计：

• done 是 atomic.Value——不是 chan struct{}。通道是惰性创建的：第一次调用 Done() 时才分配。如果整个生命周期中没人调用 Done()，通道永远不会被创建。
• children 是 map[canceler]struct{}——key 是 canceler 接口（cancel(removeFromParent bool) 方法）。子节点在 WithCancel/WithTimeout 时注册进 children，在 cancel() 时遍历并递归取消。
• mu 保护 done 创建、children 增删、err 写入——它是互斥锁，保证 cancel() 的并发安全。

// context/context.go
type canceler interface {
    cancel(removeFromParent bool, err, cause error)
    Done() <-chan struct{}
}

canceler 接口：cancelCtx 和 timerCtx 都实现此接口。valueCtx 不实现——它不参与取消传播链。

4.2 WithCancel 创建链路

// context/context.go
func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
    if parent == nil {
        panic("cannot create context from nil parent")
    }
    c := newCancelCtx(parent)                // 1. 创建 cancelCtx
    propagateCancel(parent, &c)              // 2. 注册到父的 children
    return &c, func() { c.cancel(true, Canceled, nil) }  // 3. 返回 ctx 和 cancel 函数
}

func newCancelCtx(parent Context) cancelCtx {
    return cancelCtx{Context: parent}
}

propagateCancel 的注册逻辑（context/context.go）：

func propagateCancel(parent Context, child canceler) {
    done := parent.Done()
    if done == nil {
        return // 父是 emptyCtx——永远不会取消，不需要注册
    }

    select {
    case <-done:
        // 父已经被取消了——立即取消子
        child.cancel(false, parent.Err(), Cause(parent))
        return
    default:
    }

    if p, ok := parentCancelCtx(parent); ok {
        // 父是 *cancelCtx——直接操作其 children map
        p.mu.Lock()
        if p.err != nil {
            // 父在两次检查之间被取消——立即取消子
            child.cancel(false, p.err, p.cause)
        } else {
            if p.children == nil {
                p.children = make(map[canceler]struct{})
            }
            p.children[child] = struct{}{}  // 注册进父的 children
        }
        p.mu.Unlock()
    } else {
        // 父不是 *cancelCtx——可能是用户自定义的 Context 实现
        // 启动一个 goroutine 等待父的 Done 信号
        go func() {
            select {
            case <-parent.Done():
                child.cancel(false, parent.Err(), Cause(parent))
            case <-child.Done():
            }
        }()
    }
}

关键路径：当父是 *cancelCtx 时，子被直接加入 children map——O(1) 注册，零额外 goroutine。当父是自定义 Context 实现时，需要额外启动一个 goroutine 来桥接取消信号。

4.3 cancel 的传播算法

cancel() 是 context 包的核心算法——递归关闭所有子节点的 Done 通道：

// context/context.go (简化)
func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {
    if err == nil {
        panic("context: internal error: missing cancel error")
    }
    c.mu.Lock()
    if c.err != nil {
        c.mu.Unlock()
        return // 已经被取消——幂等操作
    }
    c.err = err
    c.cause = cause

    // 关闭 done 通道——通知所有等待方
    d, _ := c.done.Load().(chan struct{})
    if d == nil {
        c.done.Store(closedchan)  // 使用全局已关闭的通道
    } else {
        close(d)
    }

    // 递归取消所有子节点
    for child := range c.children {
        child.cancel(false, err, cause)
    }
    c.children = nil
    c.mu.Unlock()

    // 从父的 children 中移除自己
    if removeFromParent {
        removeChild(c.Context, c)
    }
}

传播算法的并发安全性：

cancel() 调用 (可能在任意 goroutine)
  │
  ├── mu.Lock()
  │     ├── 检查 c.err != nil → 已取消 → return (幂等)
  │     ├── 设置 c.err = Canceled
  │     ├── close(done) → 所有 <-ctx.Done() 的 goroutine 被唤醒
  │     └── 遍历 children: 对每个 child 调用 child.cancel(...)
  │           └── 递归进入子节点的 mu.Lock()
  │                 └── 释放子节点的 mu 后，子继续传播给它的 children
  │
  └── mu.Unlock()

为什么需要 mu：假如没有锁——两个 goroutine 同时调用 cancel()：

1. goroutine A 读到 c.err == nil，准备设置
2. goroutine B 读到 c.err == nil，也准备设置
3. A 调用 close(done)——通道成功关闭
4. B 调用 close(done)——panic: close of closed channel

mu 保证只有一个 goroutine 能成功执行 cancel() 的主体逻辑——其他 goroutine 在 c.err != nil 检查处立即返回（幂等）。

5. timerCtx 超时机制

5.1 timerCtx 与 cancelCtx 的关系

timerCtx 嵌入 cancelCtx——语义是"带定时器的取消上下文"：

// context/context.go (简化)
type timerCtx struct {
    cancelCtx                   // 继承 cancelCtx 的全部字段和方法
    timer    *time.Timer        // 超时定时器
    deadline time.Time          // 截止时间
}

func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
    return WithDeadline(parent, time.Now().Add(timeout))
}

func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
    // ...
    c := &timerCtx{
        cancelCtx: newCancelCtx(parent),
        deadline:  d,
    }
    propagateCancel(parent, c)   // 注册到父的 children
    // ...
    // 启动定时器
    if dur > 0 {
        c.timer = time.AfterFunc(dur, func() {
            c.cancel(true, DeadlineExceeded, nil)
        })
    }
    return c, func() { c.cancel(true, Canceled, nil) }
}

关键：timerCtx 有自己的 cancel() 方法——覆盖 cancelCtx.cancel()：

func (c *timerCtx) cancel(removeFromParent bool, err, cause error) {
    c.cancelCtx.cancel(false, err, cause)  // 调用 cancelCtx 的取消逻辑
    if removeFromParent {
        removeChild(c.cancelCtx.Context, c)
    }
    if c.timer != nil {
        c.timer.Stop()  // 停止定时器——防止定时器泄漏
        c.timer = nil
    }
}

timerCtx.cancel() 在继承的取消逻辑基础上，额外做了 timer.Stop()——保证定时器资源被回收。

5.2 WithTimeout 的定时器联动

完整的 WithDeadline 流程（context/context.go 核心路径）：

WithDeadline(parent, deadline)
  │
  ├── 1. 检查 parent.Deadline()
  │      ├── 父有 deadline 且比自己早 → newDeadline = 父的 deadline
  │      └── 父没有 deadline 或比自己晚 → newDeadline = d
  │
  ├── 2. 创建 timerCtx{deadline: newDeadline}
  │
  ├── 3. propagateCancel(parent, &c)
  │      → 注册到父的 children（如果父是 *cancelCtx）
  │
  ├── 4. 计算 dur = newDeadline - now
  │      ├── dur <= 0 → 截止时间已过 → 立即 cancel(DeadlineExceeded)
  │      └── dur > 0 → time.AfterFunc(dur, func() { c.cancel(true, ...) })
  │
  └── 5. 返回 ctx 和 cancel 函数

定时器触发后的连锁反应：

time.AfterFunc(dur, func() { c.cancel(true, DeadlineExceeded, nil) })
  │
  └── dur 时间后，runtime 定时器触发
        │
        └── c.cancel(true, DeadlineExceeded, nil)
              │
              ├── 关闭 c.done 通道 → 所有监听 ctx.Done() 的 goroutine 被唤醒
              ├── 遍历 c.children → 递归取消所有子 context
              ├── c.timer.Stop() (timerCtx.cancel 中)
              └── removeFromParent = true → 从父的 children 中移除

5.3 超时后的清理路径

疑惑：如果手动调用了 cancel()（提前取消），定时器怎么办？

论证：

ctx, cancel := context.WithTimeout(parent, 5*time.Second)
// ... 业务逻辑 ...
cancel()  // 1 秒后手动取消——5 秒的定时器还没触发

cancel() 调用的 timerCtx.cancel() 中执行 c.timer.Stop()——定时器被停止并回收。如果漏掉这个 Stop()，定时器对象会一直挂在堆上直到 5 秒后触发——虽然触发时发现 ctx 已经被取消不再做事，但定时器本身占用的内存不会被 GC（因为 time.AfterFunc 内部持有对回调函数的引用）。

结论：timerCtx 的 cancel() 总是会停止定时器——无论是超时触发还是手动取消。这防止了定时器泄漏。

6. valueCtx 链式查找

6.1 valueCtx 的链表结构

// context/context.go (简化)
type valueCtx struct {
    Context              // 嵌入父 context
    key, val any         // 存储的键值对
}

func WithValue(parent Context, key, val any) Context {
    if parent == nil {
        panic("cannot create context from nil parent")
    }
    if key == nil {
        panic("nil key")
    }
    if !reflectlite.TypeOf(key).Comparable() {
        panic("key is not comparable")
    }
    return &valueCtx{parent, key, val}
}

func (c *valueCtx) Value(key any) any {
    if c.key == key {
        return c.val
    }
    return value(c.Context, key)  // 递归沿父链查找
}

数据结构本质上是一个不可变链表：

valueCtx{key:"traceID", val:"abc"} → valueCtx{key:"userID", val:42} → cancelCtx → emptyCtx
         ↑ 头节点                                                                    ↑ 尾节点

每次 WithValue 在链表头部插入新节点——O(1) 创建。

6.2 O(N) 查找的代价

// context/context.go
func value(c Context, key any) any {
    for {
        switch ctx := c.(type) {
        case *valueCtx:
            if key == ctx.key {
                return ctx.val
            }
            c = ctx.Context  // 向父节点移动一个位置
        case *cancelCtx:
            // cancelCtx 不存储 value，直接跳到父节点
            c = ctx.Context
        case *timerCtx:
            // timerCtx 也不存储 value
            c = ctx.Context
        case *emptyCtx:
            return nil  // 到达根节点——未找到
        default:
            return c.Value(key)  // 用户自定义 Context
        }
    }
}

O(N) 带来的实际问题：

// ❌ 反模式：为每个参数创建一个 valueCtx 层
ctx = context.WithValue(ctx, "param1", v1)
ctx = context.WithValue(ctx, "param2", v2)
// ... 共 50 层
ctx = context.WithValue(ctx, "param50", v50)

// 每次查找 param50：O(1)——在头节点
// 每次查找 param1：O(50)——需要遍历 49 层到尾部

优化建议：将多个相关值打包进一个结构体，用一次 WithValue 传递：

// ✅ 优化：一个 key → 一个聚合值
type RequestMeta struct {
    TraceID string
    UserID  int64
    ClientIP string
}
ctx = context.WithValue(ctx, requestMetaKey, &RequestMeta{...})
// 查找 O(1)

6.3 valueCtx 与其他 Ctx 共存

valueCtx 包装 cancelCtx 的场景——取消传播不受影响：

cancelCtx (有取消能力)  ← 父
  │
valueCtx{key:"traceID"}  ← 子 (包装了 cancelCtx，但不实现 canceler 接口)
  │
业务代码: ctx.Value("traceID") → 找到
          ctx.Done() → 转发给嵌入的 cancelCtx → 正确接收取消信号
          ctx.Err()  → 转发给嵌入的 cancelCtx → Canceled

关键：valueCtx 不实现 canceler 接口，因此不会出现在 children map 中。但 valueCtx 的 Done() 方法会转发给嵌入的父 Context——取消信号能穿透 valueCtx 层向下传递。

7. 取消传播深层剖析

7.1 Done 管道的创建时机

Done() 通道不是 WithCancel 时创建的——是第一次调用 Done() 时惰性创建的：

// context/context.go (简化)
func (c *cancelCtx) Done() <-chan struct{} {
    d := c.done.Load()
    if d != nil {
        return d.(chan struct{})
    }
    c.mu.Lock()
    defer c.mu.Unlock()
    d = c.done.Load()
    if d == nil {
        d = make(chan struct{})
        c.done.Store(d)
    }
    return d.(chan struct{})
}

双重检查（double-check）模式：第一次 Load 是无锁的快速路径——如果通道已经创建，直接返回。如果没创建，加锁后再次检查（防止其他 goroutine 已经创建），仍未创建则 make(chan struct{})。

如果 Done() 从未被调用——通道永远不会创建。cancel() 中 c.done.Load() 返回 nil 时，直接 Store(closedchan) 使用全局预关闭的通道——不需要为主路径未使用的 context 分配管道。

7.2 父子取消的并发安全

最复杂的并发场景：父 cancel() 和子 WithCancel() 同时发生：

时间线：

goroutine A: 调用 parentCancel()          goroutine B: WithCancel(parent)
  ──────────────────────────────────       ───────────────────────────
  1. parent.mu.Lock()                      
  2. parent.err = Canceled                 1. propagateCancel(parent, child)
  3. close(parent.done)                       → parent.Done() 已关闭?
  4. 遍历 parent.children                      → select case <-parent.Done():
     → child.cancel()                              → child.cancel(false, ...)
  5. parent.children = nil                     → return (父已取消，不加入 children)
  6. parent.mu.Unlock()

propagateCancel 中的双重检查：

// 第一次检查：无锁快速路径
select {
case <-parent.Done():
    child.cancel(false, parent.Err(), Cause(parent))
    return
default:
}

// 第二次检查：加锁后
p.mu.Lock()
if p.err != nil {
    // goroutine A 在两次检查之间完成了 cancel
    child.cancel(false, p.err, p.cause)
} else {
    p.children[child] = struct{}{}
}
p.mu.Unlock()

为什么需要双重检查：第一次 select 和加锁之间存在窗口——父可能在窗口中被取消。如果只有第一次检查，子可能被加入一个"已取消"的父的 children 中，然后父因为 children != nil 以为还有未取消的子——但实际上子已经永远不会被取消了（父的 cancel 已经执行完毕）。

7.3 取消原因的传播链

context 包定义了两种标准错误：

// context/context.go
var Canceled = errors.New("context canceled")
var DeadlineExceeded = errors.New("context deadline exceeded")

取消原因沿 children 传播：

父 cancel(err=DeadlineExceeded) 被调用
  │
  ├── 子 1.cancel(err=DeadlineExceeded)
  │     └── 子1的子.cancel(err=DeadlineExceeded)
  │           └── ... 一直到底
  │
  ├── 子 2.cancel(err=DeadlineExceeded)
  │     └── ...
  │
  └── 所有被取消的 ctx.Err() 都返回 DeadlineExceeded

Go 1.20+ 的 WithCancelCause 让原因更丰富（见第 8 章）。

8. 高级特性

8.1 WithCancelCause 错误传播

Go 1.20 引入 WithCancelCause——让取消原因从官方的两种标准错误扩展为任意自定义错误：

// Go 1.20+ context/context.go
func WithCancelCause(parent Context) (ctx Context, cancel CancelCauseFunc) {
    c := withCancel(parent)
    return c, func(cause error) { c.cancel(true, Canceled, cause) }
}

func Cause(c Context) error {
    if cc, ok := c.Value(&cancelCtxKey).(*cancelCtx); ok {
        cc.mu.Lock()
        defer cc.mu.Unlock()
        return cc.cause
    }
    return nil
}

使用示例：

ctx, cancel := context.WithCancelCause(parent)

go func() {
    // 某个下游调用失败——传递具体原因
    cancel(fmt.Errorf("fraud check failed: model timeout after %v", elapsed))
}()

<-ctx.Done()

// 获取取消原因
cause := context.Cause(ctx)
fmt.Println(cause)  // "fraud check failed: model timeout after 2.8s"

相比标准 WithCancel 的优势：

特性	WithCancel	WithCancelCause
取消函数签名	func()	func(cause error)
获取原因	只能知道 Canceled	通过 context.Cause(ctx) 获取自定义原因
诊断能力	弱——只知道"被取消了"	强——知道"被谁、因为什么"取消

8.2 AfterFunc 回调注册

Go 1.21 引入 AfterFunc——在 context 被取消之后执行回调：

// Go 1.21+ context/context.go
func AfterFunc(ctx Context, f func()) (stop func() bool) {
    // 返回 stop 函数——如果回调还没执行，可以阻止它
}

与直接监听 <-ctx.Done() 的区别：

// ❌ 旧方式：需要额外 goroutine
go func() {
    <-ctx.Done()
    cleanup()
}()

// ✅ AfterFunc：不需要额外 goroutine
stop := context.AfterFunc(ctx, func() {
    cleanup()
})

// 如果不需要清理了，阻止回调执行
if stopped := stop(); stopped {
    // 回调被成功阻止
}

AfterFunc 的优势：

1. 零 goroutine 开销——回调注册进 cancelCtx 的内部列表，cancel() 时直接调用，不需要等待 goroutine 调度
2. 可取消——stop() 返回 true 表示回调还未执行且已被阻止
3. 确定执行——stop() 返回 false 表示回调已执行或 context 已取消

9. 诊断与陷阱

9.1 未调 cancel 的 goroutine 泄漏

最常见的 Context 泄漏模式：

// ❌ 泄漏：ctx 的 cancel 从未被调用
func process(ctx context.Context) {
    childCtx, _ := context.WithTimeout(ctx, 5*time.Second)
    //                  ↑ 忽略了 cancel 函数
    go func() {
        <-childCtx.Done()
        // 5 秒后这个 goroutine 退出
    }()
    // process 返回——但 childCtx 的定时器还在活跃
    // timerCtx 对象、定时器、goroutine 都不会被 GC
}

// ✅ 正确：始终调用 cancel
func process(ctx context.Context) {
    childCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()  // process 返回时取消 childCtx
    go func() {
        <-childCtx.Done()
    }()
}

更隐蔽的泄漏——返回 context 给调用方时需要特别注意：

// ❌ 泄漏：NewRequestContext 的调用方不知道需要 cancel
func NewRequestContext() context.Context {
    ctx, _ := context.WithTimeout(context.Background(), 30*time.Second)
    return ctx  // 30 秒后自动取消——但如果请求提前完成呢？
    // 调用方无法主动取消——context 和内部资源活到 30 秒
}

// ✅ 正确：返回 cancel 函数
func NewRequestContext() (context.Context, context.CancelFunc) {
    return context.WithTimeout(context.Background(), 30*time.Second)
}

9.2 pprof 定位 context 泄漏

步骤一：goroutine profile 看阻塞点

$ go tool pprof http://localhost:6060/debug/pprof/goroutine
(pprof) top10
      flat  flat%   sum%        cum   cum%
      5400 16.29% 76.32%       5400 16.29%  context.(*cancelCtx).Done
      3200  9.65% 85.97%       3200  9.65%  runtime.gopark

context.(*cancelCtx).Done 出现在 top 中——5400 个 goroutine 在等待某个 Done 通道。

步骤二：具体看卡在哪个函数

$ curl http://localhost:6060/debug/pprof/goroutine?debug=2 | grep -B5 "context.Done"
goroutine 4872 [select]:
main.fraudCheck(0x1400080c000, "ORD-12345")
    /app/payment_gateway.go:80 +0x8f
main.handlePayment.func1()
    /app/payment_gateway.go:45 +0x67
created by main.handlePayment
    /app/payment_gateway.go:42 +0x12b

fraudCheck 中 select { case <-ctx.Done(): } 在等待。

步骤三：看 heap profile——context 对象是否堆积

$ go tool pprof http://localhost:6060/debug/pprof/heap
(pprof) top
      flat  flat%
    320MB 40.00%  context.(*cancelCtx)
    180MB 22.50%  context.(*timerCtx)

大量 cancelCtx 和 timerCtx 对象在堆上未被回收——它们持有的 children map 还在引用其他 context，形成引用链阻止 GC。

9.3 常见反模式

反模式 1：用 string 做 WithValue 的 key

// ❌ 两个包可能碰巧使用相同的字符串
ctx = context.WithValue(ctx, "traceID", "abc")      // 包 A
ctx = context.WithValue(ctx, "traceID", "xyz")      // 包 B——覆盖了包 A 的值！

// ✅ 用自定义类型做 key——编译器保证唯一
type traceIDKey struct{}
ctx = context.WithValue(ctx, traceIDKey{}, "abc")

反模式 2：把 context 存进结构体

// ❌ context 应该流动——不是状态
type Server struct {
    ctx context.Context  // 生命周期混乱
}

// ✅ context 应该作为函数的第一个参数传递
func (s *Server) Handle(ctx context.Context, req *Request) error { ... }

反模式 3：用 context.Value 传业务参数

// ❌ context 不是参数包
ctx = context.WithValue(ctx, "userID", 123)
ctx = context.WithValue(ctx, "amount", 99.9)
processPayment(ctx)  // processPayment 需要"知道"这些 key——隐式契约

// ✅ 显式函数参数
processPayment(ctx, 123, 99.9)

反模式 4：在循环中创建 context 但不 cancel

// ❌ 每次循环泄漏一个 timerCtx
for _, item := range items {
    ctx, _ := context.WithTimeout(parentCtx, time.Second)
    processItem(ctx, item)
}

// ✅
for _, item := range items {
    ctx, cancel := context.WithTimeout(parentCtx, time.Second)
    processItem(ctx, item)
    cancel()
}

10. 综合案例串讲

10.1 案例真相揭晓

回到第 1 章支付网关的七个疑问，逐条作答：

疑问	答案
① Context 接口的 Done() 何时关闭？	第 3 章：cancelCtx.cancel() 中 close(done)——取消时关闭
② cancelCtx 如何管理子 context？	第 4 章：children map[canceler]struct{}——cancel 时遍历递归取消
③ WithTimeout 内部如何关联定时器？	第 5 章：time.AfterFunc 回调中调用 c.cancel(true, DeadlineExceeded, nil)
④ WithValue 查找为什么 O(N)？	第 6 章：不可变链表——每次 Value() 沿父链逐层匹配直到根
⑤ cancel() 递归通知如何保证并发安全？	第 7 章：sync.Mutex + 双重检查 + c.err != nil 幂等判断
⑥ WithCancelCause 多了什么能力？	第 8.1：自定义错误原因 + context.Cause(ctx) 获取
⑦ pprof 如何定位 context 泄漏？	第 9.2：goroutine profile 看 cancelCtx.Done 堆积 → goroutine?debug=2 看具体卡在哪

案例根因链条：

handlePayment 创建 payCtx (WithTimeout 3s)
  → 并行启动 3 个 goroutine：fraudCheck, balanceCheck, inventoryLock
  → balanceCheck 在 200ms 返回错误 ("insufficient balance")
  → 但 handlePayment 中的 wg.Wait() 还在等 fraudCheck(需要 2.8s)
  → defer cancel() 被卡在函数结尾——无法通知 fraudCheck 停止
  → 500 个并发请求 → 500 × 3 = 1500 goroutine 同时活跃
  → 其中 fraudCheck 的 goroutine 要 2.8s 后才能退出
  → QPS 继续升高 → goroutine 堆积到 35000
  → 每个 goroutine 持有 payCtx 引用 → cancelCtx + timerCtx 对象无法 GC
  → 内存 8GB → OOM Kill

修复方案——用 errgroup 替代手动 WaitGroup：

import "golang.org/x/sync/errgroup"

func handlePayment(ctx context.Context, orderID string) error {
    payCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()

    g, gCtx := errgroup.WithContext(payCtx)

    // fraudCheck：接收 gCtx——errgroup 会在第一个错误时取消 gCtx
    g.Go(func() error {
        return fraudCheck(gCtx, orderID)
    })

    // balanceCheck
    g.Go(func() error {
        return balanceCheck(gCtx, orderID)
    })

    // inventoryLock
    g.Go(func() error {
        return inventoryLock(gCtx, orderID)
    })

    // g.Wait() 在第一个错误返回时立即取消 gCtx → 其他 goroutine 的 ctx.Done() 被唤醒
    return g.Wait()
}

修复后的执行流程：

balanceCheck 在 200ms 返回错误
  → errgroup 收到错误
  → 立即 cancel(gCtx) → gCtx 的 done 通道关闭
  → fraudCheck 的 select { case <-gCtx.Done() } 被唤醒 → 返回 ctx.Err()
  → inventoryLock 同样被唤醒
  → 所有 goroutine 在 ~200ms 内退出
  → wg.Wait() 不再需要等待 2.8 秒

10.2 一次 context 取消的完整路径

支付网关中，errgroup 收到 balanceCheck 错误后调用 cancel(gCtx)：
───────────────────────────────────────────────────────────

1. errgroup.Wait() 返回第一个错误
     → 调用 group.cancel(err)

2. gCtx 是 *cancelCtx（由 errgroup.WithContext 创建）
     → cancelCtx.cancel(true, Canceled, nil)
       │
       ├── mu.Lock()
       ├── c.err = Canceled
       ├── close(done) → fraudCheck 和 inventoryLock 的 select 被唤醒
       ├── 遍历 c.children:
       │     ├── 子 cancelCtx_1 (由 fraudCheck 内部创建的派生 context)
       │     │     → child.cancel(false, Canceled, nil)
       │     │       → close(done) → 子 goroutine 被唤醒
       │     │
       │     └── 子 timerCtx_1 (由 inventoryLock 内部 WithTimeout 创建)
       │           → timerCtx.cancel(false, ...)
       │             → cancelCtx.cancel(false, ...) 继续传播
       │             → timer.Stop() 防止定时器泄漏
       │
       ├── c.children = nil
       ├── mu.Unlock()
       └── removeFromParent: c 从 payCtx 的 children 中移除

3. payCtx (父) 仍在活跃——它的 deadline 还没到
     → payCtx 的 children 中少了 gCtx
     → payCtx 的 cancel 不再需要遍历已取消的 gCtx

4. 所有 fraudCheck/inventoryLock 的 goroutine 收到 ctx.Done() 信号
     → 返回 ctx.Err() = "context canceled"
     → goroutine 退出 → 栈释放

总耗时：约 5-10μs（遍历 children + close channels + timer.Stop）

10.3 设计哲学回扣

哲学 1：用组合代替继承——接口嵌入的设计智慧

cancelCtx 嵌入 Context 接口（而非具体类型），timerCtx 嵌入 cancelCtx 结构体。这种分层嵌入让每一层只关心自己的职责：cancelCtx 管取消传播，timerCtx 管定时器，valueCtx 管键值存储。它们可以任意组合（WithValue(WithTimeout(WithCancel(bg)))）而不破坏各自的行为——这是接口嵌入优于类继承的经典案例。

哲学 2：用惰性创建避免"为不走的路径付费"

cancelCtx 的 done 通道在第一次 Done() 时才创建。如果整个生命周期中没有任何 goroutine 调用 ctx.Done()——通道永远不会被分配。context 代码中大量使用 atomic.Value + double-check——大部分 goroutine 走无锁快速路径，只有创建者走加锁慢速路径。

哲学 3：用幂等性消除竞态

cancel() 的核心逻辑——if c.err != nil { return }——保证无论多少个 goroutine 同时调用 cancel()，只有第一个能执行主体逻辑。后续的调用立即返回——零副作用。这种"唯一一次执行"的幂等设计，让调用方无需关心"是不是已经取消过了"。

哲学 4：让取消信号沿树传播——而非通过全局状态

context 的取消传播是单向、跨 goroutine 的树遍历。每个节点只需通知它的直接子节点——子节点递归通知它们的子节点。没有全局锁、没有广播通道、没有中央协调器。这种分布式通知模型让 context 树可以无限扩展——10 层、100 层——传播成本只跟树的大小成正比，不跟 goroutine 总数成正比。

10.4 速查表

四种 Context 实现：

类型	创建函数	核心能力	Done 行为	children
emptyCtx	Background()/TODO()	根节点、永不取消	返回 nil	无
cancelCtx	WithCancel()	手动取消 + 子节点传播	cancel() 时关闭	有（map[canceler]）
timerCtx	WithTimeout()/WithDeadline()	超时自动取消	超时或手动 cancel 时关闭	继承 cancelCtx 的 children
valueCtx	WithValue()	键值存储、沿父链查找	转发给父	无（不实现 canceler）

取消传播参数：

项	值
cancel() 并发安全	sync.Mutex + 幂等检查 c.err != nil
子节点存储	map[canceler]struct{}——O(1) 注册，O(N) 遍历
传播深度	递归——直到没有子节点
定时器清理	timer.Stop()——超时触发或手动 cancel 都停止
value 查找	沿父链遍历——O(N)，N = valueCtx 层数

诊断命令：

# goroutine 泄漏定位
go tool pprof http://localhost:6060/debug/pprof/goroutine
# (pprof) top → 看 context.(*cancelCtx).Done 是否出现
# (pprof) list funcName → 看具体哪个 goroutine 在等 Done

# 查看具体 goroutine 栈
curl http://localhost:6060/debug/pprof/goroutine?debug=2 | grep -B5 "context"

# heap profile — context 对象堆积
go tool pprof http://localhost:6060/debug/pprof/heap
# (pprof) top → context.(*cancelCtx) / context.(*timerCtx) 占比

# 快速检查 — runtime.NumGoroutine()
curl http://localhost:6060/debug/pprof/goroutine?debug=1 | head -1
# goroutine profile: total 32487

# 代码检查 — 静态分析未调用 cancel
# go vet 目前不检查 context 泄漏——需要依赖人工review或第三方linter
# 推荐: github.com/sashamelentyev/usestdlibvars (检查 context key 类型)

---

下一篇：我们已经掌握了 context 的取消传播机制——这是 Go 并发控制的"信号层"。下一步进入 24.channel 内部实现与调度——把 make(chan int) 背后的环形缓冲区、sudog 等待队列、以及 select 的随机选择算法拆到源码级别。