Go Context 底层实现

#golang · #context · #并发 · #超时 · #取消

Context 是 Go 并发编程中传递取消信号、超时控制和请求范围数据的核心机制。从 HTTP Server 到 gRPC，从数据库查询到微服务调用链，Context 贯穿整个请求生命周期。理解其底层实现，才能正确使用它。

---

1. Context 接口

// context/context.go
type Context interface {
    Deadline() (deadline time.Time, ok bool)  // 截止时间
    Done() <-chan struct{}                      // 取消信号 channel
    Err() error                                 // 取消原因
    Value(key interface{}) interface{}          // 请求范围数据
}

接口设计非常精简：取消信号通过 Done() 返回的只读 channel 传播，Err() 告诉你为什么被取消，Value() 实现请求范围的 K-V 存储，Deadline() 支持超时控制。

---

2. Context 树

graph TD
    BG["context.Background()"] --> C1["context.WithCancel()"]
    BG --> C2["context.WithTimeout(2s)"]
    C1 --> C3["context.WithValue()"]
    C1 --> C4["context.WithTimeout(1s)"]
    C2 --> C5["context.WithCancel()"]

Context 是一棵树，每个节点持有父节点的引用。关键规则：

• 取消传播：父 Context 取消 → 所有子 Context 也会被取消。
• 不反向传播：子 Context 取消不影响父 Context。
• Value 查找：从当前节点向上遍历到根节点（类似链表查找）。

---

3. 四种创建方式

函数	返回类型	用途
context.Background()	*emptyCtx	根 context，通常用于 main/func init/测试
context.TODO()	*emptyCtx	还不确定用哪种 context 时的占位符
context.WithCancel(parent)	*cancelCtx	手动取消
context.WithDeadline(parent, time)	*timerCtx	到达指定时间自动取消
context.WithTimeout(parent, duration)	*timerCtx	超时自动取消（内部调用 WithDeadline）
context.WithValue(parent, key, value)	*valueCtx	携带请求范围的数据

---

4. cancelCtx — 手动取消

4.1 结构定义

type cancelCtx struct {
    Context                     // 父 context

    mu       sync.Mutex         // 保护以下字段
    done     atomic.Value       // 懒创建：首次调用 Done() 时创建 chan struct{}
    children map[canceler]struct{} // 所有可取消的子 context
    err      error              // 取消原因（set under mu）
    cause    error              // 取消原因详情（Go 1.20+）
}

4.2 cancel 函数：取消是怎么传播的

// WithCancel 返回的 cancel 函数
func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {
    if err == nil {
        panic("context: internal error: missing cancel error")
    }
    if cause == nil {
        cause = err
    }

    c.mu.Lock()
    if c.err != nil {
        c.mu.Unlock()
        return // 已经取消过了
    }
    c.err = err
    c.cause = cause
    // 关闭 done channel：所有阻塞在 <-ctx.Done() 的 goroutine 被唤醒
    d, _ := c.done.Load().(chan struct{})
    if d == nil {
        c.done.Store(closedchan)  // 使用全局已关闭的 channel
    } else {
        close(d)
    }
    // 递归取消所有子 context
    for child := range c.children {
        child.cancel(false, err, cause)
    }
    c.children = nil
    c.mu.Unlock()

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

4.3 取消传播流程图

sequenceDiagram
    participant Caller as 调用者
    participant C1 as cancelCtx (父)
    participant C2 as cancelCtx (子1)
    participant C3 as cancelCtx (子2)
    participant G1 as goroutine 1
    participant G2 as goroutine 2

    Caller->>C1: cancel()
    C1->>C1: 设置 err = Canceled
    C1->>C1: close(done channel)
    C1->>C2: child.cancel()
    C2->>C2: 设置 err = Canceled
    C2->>C2: close(done channel)
    C1->>C3: child.cancel()
    C3->>C3: 设置 err = Canceled
    C3->>C3: close(done channel)

    Note over G1,G2: done channel 关闭 → 所有等待者被唤醒
    G1->>G1: <-ctx.Done() 解除阻塞
    G2->>G2: <-ctx.Done() 解除阻塞

4.4 完整使用示例

func main() {
    ctx, cancel := context.WithCancel(context.Background())

    go worker(ctx, "worker-1")
    go worker(ctx, "worker-2")

    time.Sleep(2 * time.Second)
    cancel() // 通知所有 worker 退出
    time.Sleep(1 * time.Second)
}

func worker(ctx context.Context, name string) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println(name, "退出, 原因:", ctx.Err())
            return
        default:
            fmt.Println(name, "工作中...")
            time.Sleep(500 * time.Millisecond)
        }
    }
}

---

5. timerCtx — 超时与截止时间

5.1 结构

type timerCtx struct {
    cancelCtx              // 嵌入 cancelCtx
    timer    *time.Timer   // 底层定时器
    deadline time.Time     // 截止时间
}

// WithTimeout 实际调用 WithDeadline
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
    return WithDeadline(parent, time.Now().Add(timeout))
}

5.2 工作原理

func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
    // 1. 如果父 context 的 deadline 更早，直接用父的 cancel
    if cur, ok := parent.Deadline(); ok && cur.Before(d) {
        return WithCancel(parent)
    }

    c := &timerCtx{
        cancelCtx: newCancelCtx(parent),
        deadline:  d,
    }
    propagateCancel(parent, c) // 将自己注册到父的 children

    // 2. 如果 deadline 已经过了，直接取消
    dur := time.Until(d)
    if dur <= 0 {
        c.cancel(true, DeadlineExceeded, nil)
        return c, func() { c.cancel(false, Canceled, nil) }
    }

    c.mu.Lock()
    defer c.mu.Unlock()
    if c.err == nil {
        // 3. 创建 timer，到期后自动调用 cancel
        c.timer = time.AfterFunc(dur, func() {
            c.cancel(true, DeadlineExceeded, nil)
        })
    }
    return c, func() { c.cancel(true, Canceled, nil) }
}

5.3 超时和手动取消的区别

ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel() // ← 重要！即使超时也会自动取消，但手动 cancel 可以提前释放资源

select {
case <-ctx.Done():
    switch ctx.Err() {
    case context.DeadlineExceeded:
        fmt.Println("超时了")
    case context.Canceled:
        fmt.Println("被手动取消了")
    }
}

重要：defer cancel() 不能省！timerCtx 在超时后虽然会自动取消，但 timer 还在等待中。手动 cancel 会让 timer 停止，释放资源。否则 timer 会一直等到超时才被 GC 回收。

---

6. valueCtx — 请求范围数据

6.1 结构

type valueCtx struct {
    Context
    key, val interface{}
}

非常简单的链表节点：每个 valueCtx 只存一对 key-value，更多数据通过链式嵌套。

6.2 Value 查找：向上遍历

func (c *valueCtx) Value(key interface{}) interface{} {
    if c.key == key {
        return c.val
    }
    return c.Context.Value(key) // 向上递归查找父节点
}

flowchart LR
    subgraph BG["Background"]
    end
    subgraph VT1["WithValue(key=a)"]
        A["key=a, val=1"]
    end
    subgraph VT2["WithValue(key=b)"]
        B["key=b, val=2"]
    end
    subgraph VT3["WithValue(key=c)"]
        C["key=c, val=3"]
    end

    BG --> VT1
    VT1 --> VT2
    VT2 --> VT3

    VT3 -..->|"ctx.Value(a)"| A

查找复杂度 O(n)，n 为 Value 嵌套层数。但因为请求范围的 K-V 通常很少，所以不是问题。

6.3 Key 的设计：类型安全

// ❌ 不好：字符串 key 容易冲突
ctx = context.WithValue(ctx, "user_id", 123)

// ✅ 好：使用自定义类型作为 key（不可导出）
type contextKey string

const (
    UserIDKey  contextKey = "user_id"
    TraceIDKey contextKey = "trace_id"
)

ctx = context.WithValue(ctx, UserIDKey, 123)
ctx = context.WithValue(ctx, TraceIDKey, "abc-123")

// 取值
userID := ctx.Value(UserIDKey).(int)

为什么用自定义类型：interface{} 作 key 时，只有类型和值都相同才算同一个 key。自定义类型 contextKey 和普通 string 是不同类型，避免不同包之间的 key 冲突。

---

7. 源码关键机制

7.1 懒创建 done channel

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{})
}

只在首次调用 Done() 时才创建 channel。如果 context 在 Done() 被调用前就取消了，直接返回全局的 closedchan（一个已关闭的 channel）。

7.2 propagateCancel：父子关联

func propagateCancel(parent Context, child canceler) {
    done := parent.Done()
    if done == nil {
        return // 父不会取消（如 Background/TODO）
    }

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

    // 父是 cancelCtx 类型 → 把自己加入父的 children
    if p, ok := parentCancelCtx(parent); ok {
        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{}{}
        }
        p.mu.Unlock()
    } else {
        // 父是其他类型的 Context → 启动 goroutine 监听父的取消
        go func() {
            select {
            case <-parent.Done():
                child.cancel(false, parent.Err(), Cause(parent))
            case <-child.Done():
            }
        }()
    }
}

关键：如果父是 cancelCtx/timerCtx，子直接注册到 children map；如果父是其他类型（如用户自定义 Context），则需要额外的 goroutine 来监听。

---

8. 工程最佳实践

8.1 规范

// 1. Context 必须是函数的第一个参数，通常命名为 ctx
func DoSomething(ctx context.Context, argArg string) error

// 2. 不要把 Context 存在 struct 中
// ❌ type S struct { ctx context.Context }
// ✅ func (s *S) Do(ctx context.Context)

// 3. Context 是线程安全的（可以传给多个 goroutine）
go worker(ctx)
go worker(ctx)

// 4. 不确定用哪个时用 TODO(), 不要传 nil
// ❌ func handler(ctx context.Context) { handler2(nil) }
// ✅ func handler(ctx context.Context) { handler2(context.TODO()) }

8.2 HTTP Server 中的 Context

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context() // 浏览器关闭连接 → ctx 被取消

    result, err := doSlowQuery(ctx)
    if err != nil {
        http.Error(w, "query failed", http.StatusInternalServerError)
        return
    }
    fmt.Fprintln(w, result)
}

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

    // 将 ctx 传给 database/sql，支持查询超时
    row := db.QueryRowContext(ctx, "SELECT data FROM big_table WHERE id = $1", 1)
    // ...
}

8.3 典型调用链

// gRPC 拦截器中设置超时
func UnaryTimeoutInterceptor(timeout time.Duration) grpc.UnaryServerInterceptor {
    return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo,
        handler grpc.UnaryHandler) (interface{}, error) {

        ctx, cancel := context.WithTimeout(ctx, timeout)
        defer cancel()

        return handler(ctx, req)
    }
}

// 业务代码中传递
func (s *Service) GetUser(ctx context.Context, id int64) (*User, error) {
    // 从 ctx 获取 traceID
    traceID := ctx.Value(TraceIDKey).(string)

    // 查询 DB，传递 ctx（支持超时）
    user, err := s.db.GetUserByID(ctx, id)

    // 调用下游服务
    resp, err := s.userClient.GetProfile(ctx, &pb.GetProfileReq{UserId: id})

    // 如果 ctx 被取消，这些操作都会提前返回
    return user, err
}

---

9. 滥用反模式与选型指南

Context 的六大反模式

Go 社区有一个说法：Context 是"Go 语言中最容易被滥用的特性"。以下是最常见的错误：

反模式	为什么错	正确做法
Context 存入 struct	生命周期混乱，多个请求共享一个 ctx	作为函数第一个参数传递，随请求生命周期走
ctx.Value 存业务数据	丢失类型安全，调用者无法知晓返回值	只存请求元数据（traceID/userID），业务数据用参数显式传递
循环中创建子 ctx 不 cancel	timerCtx 的 timer 泄漏，goroutine 泄漏	每次 WithTimeout/WithCancel 必须 defer cancel()
用 ctx.Background() 替代 ctx.TODO()	失去"待定"语义，后续维护者无法识别	不确定用哪种 context 时用 TODO()，确定后改为 Background() 或传参
select 中漏掉 ctx.Done()	goroutine 无法响应取消信号，可能永久泄漏	任何可能阻塞的地方都加上 case <-ctx.Done()
对已经 cancel 的 ctx 再调 cancel	不会 panic，但浪费（cancelCtx.cancel 内部有幂等检查）	最好只 defer cancel() 一次

// ❌ 典型反模式：Context 存入 struct
type Worker struct {
    ctx context.Context  // 错误！
}
func (w *Worker) Do() {
    // 谁负责 cancel？生命周期混乱
}

// ✅ 正确：作为参数传递
type Worker struct{}
func (w *Worker) Do(ctx context.Context) {
    // ctx 的生命周期由调用者控制，清晰明确
}

WithTimeout vs WithDeadline — 什么时候用哪个

// WithTimeout: "从这个时间点开始，给我 N 秒"
ctx, cancel := context.WithTimeout(parent, 3*time.Second)

// WithDeadline: "在某个绝对时间点之前完成"
ctx, cancel := context.WithDeadline(parent, time.Date(2026, 7, 12, 18, 30, 0, 0, time.UTC))

维度	WithTimeout	WithDeadline
参数	相对时长 time.Duration	绝对时间 time.Time
可读性	✅ 直观："3秒超时"	🟡 需计算："到18:30截止"
跨服务传播	❌ 序列化后丢失相对基准	✅ 绝对时间可序列化传播
适用场景	单服务内部调用链	跨服务 RPC 调用链、定时任务

推荐：99% 的场景用 WithTimeout——除非你需要跨服务传递截止时间（如 gRPC 的 deadline 传播），这时用 WithDeadline。

错误	原因	正确做法
忘记 defer cancel()	timer 资源泄漏	始终 defer cancel()
Context 存入 struct	生命周期混乱	作为函数参数传递
ctx.Value 存大量数据	遍历链过长	只存请求范围元数据
在 select 中漏掉 ctx.Done()	无法响应取消	总是加 case <-ctx.Done()
循环中创建 SubContext 没 cancel	内存/goroutine 泄漏	每次迭代都 cancel

内存泄漏示例

// ❌ 泄漏：每次循环创建一个 timerCtx，但没 cancel
func processItems(ctx context.Context, items []string) {
    for _, item := range items {
        ctx, _ := context.WithTimeout(ctx, 5*time.Second) // timer 没释放！
        go process(ctx, item)
    }
}

// ✅ 正确：及时 cancel
func processItems(ctx context.Context, items []string) {
    for _, item := range items {
        ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
        process(ctx, item)
        cancel()
    }
}

---

10. 工程实践：Context 真正解决的是“请求收口”问题

10.0 一眼看懂：Context 在服务里到底管什么

flowchart LR
    A["入口 deadline / cancel"] --> B["HTTP / gRPC handler"]
    B --> C["业务逻辑"]
    C --> D["DB / RPC / cache"]
    D --> E["连接、goroutine、timer 收尾"]

关注点	先看什么	常见误区
请求预算	deadline 是否从入口统一下发	每层都重新 WithTimeout 一次
取消传播	channel / DB / RPC 是否都消费 ctx.Done()	上游超时了，下游还继续跑
生命周期	子任务是否真的从属于当前请求	把后台任务直接挂在请求 ctx 上
元数据传递	trace_id / request_id 这类轻量值	用 Value() 偷运业务参数

10.1 Context 的核心不是传值，而是控制请求预算

很多人第一次接触 context，会把注意力放在 Value() 上，但在真实服务里，Context 最重要的职责其实是：

• 传递取消信号
• 传递超时/截止时间
• 让整条调用链共享同一个“预算”

flowchart LR
    A["客户端请求 2s 超时"] --> B["HTTP / gRPC 入口 ctx"]
    B --> C["业务逻辑"]
    C --> D["MySQL 查询"]
    C --> E["Redis 查询"]
    C --> F["下游 RPC"]

如果没有 Context，每一层都可能“各等各的”：

• 上游已经超时
• 下游还在继续跑
• goroutine 还在等 I/O
• 连接、buffer、定时器都还没释放

所以 Context 的价值，本质上是 统一整条链路的退出和预算边界。

10.2 超时不是越多越好，而是要避免预算层层叠加

一个常见误区是每一层都重新写一遍：

ctx1, cancel1 := context.WithTimeout(ctx, 3*time.Second)
ctx2, cancel2 := context.WithTimeout(ctx1, 3*time.Second)
ctx3, cancel3 := context.WithTimeout(ctx2, 3*time.Second)

看起来每层都“很安全”，实际上容易导致：

• 超时预算不透明
• 某层以为自己还有 3 秒，实际上父 ctx 只剩几百毫秒
• retry、fallback、下游调用互相抢预算

更合理的思路通常是：

• 入口统一给总预算
• 下层消费这个预算，而不是重复扩预算
• 必要时基于 Deadline() 计算剩余时间，再决定是否继续调用下游

10.3 取消协议不完整，比超时配置错误更常见

很多线上泄漏，不是因为没设置 timeout，而是因为某个阻塞点根本没理会 ctx.Done()：

• channel select 没监听 ctx.Done()
• worker 池任务已经没意义，但 goroutine 还在跑
• DB/RPC 接口没把 ctx 继续往下传
• 某层内部起了后台 goroutine，却没绑定请求 ctx

这类问题最后常表现为：

• goroutine 数上涨
• fd / 连接占用时间变长
• 请求虽然超时了，但系统负载没有立刻回落

10.4 Value() 的问题不在性能，而在边界失控

Value() 本身链式查找，通常不是性能瓶颈。真正的问题是它太容易被用成“隐式参数通道”。

适合放进 ctx.Value() 的东西：

• trace id
• request id
• user id（轻量、请求范围）
• 灰度标记、鉴权元数据

不适合放进去的东西：

• 大对象
• 业务核心参数
• 可选配置大包
• 跨请求长期共享的数据

否则会出现：

• 接口签名看不出依赖
• 调用方不知道要准备哪些值
• 调试时很难追踪数据来自哪一层

10.5 一个典型故障传播链

flowchart LR
    A["客户端已取消/超时"] --> B["上游 ctx 已关闭"]
    B --> C["某层没有继续传 ctx"]
    C --> D["下游查询仍继续执行"]
    D --> E["goroutine/连接释放延迟"]
    E --> F["系统负载持续高于预期"]

这类链路里，表面现象可能是：

• RT 抖动
• goroutine 数越来越高
• 数据库连接池偶发打满
• 取消率高，但 CPU/内存并没有同步回落

10.6 实战判断：什么时候该新建子 Context

场景	建议
请求入口	创建总预算 ctx
调用下游，需要更短局部超时	基于父 ctx 派生子 ctx
同请求内多个步骤共享预算	直接传父 ctx
后台长期任务	不要直接复用请求 ctx
fire-and-forget 任务	明确脱离请求 ctx，并设计独立生命周期

关键不是“能不能派生”，而是：这个子任务的生命周期是否真的从属于当前请求。

10.7 排障思路

现象	优先怀疑	看什么
goroutine 持续上涨	ctx.Done() 没有被消费	goroutine dump
超时很多但系统压力不降	取消没有继续传播到下游	调用链日志、下游接口签名
DB/RPC 连接占用偏长	ctx 没传到驱动或客户端	接口实现、trace
timer / alloc 上涨	循环创建 WithTimeout 且没及时 cancel	alloc/heap profile

10.8 一个实战原则

先把 Context 当作“请求生命周期控制器”，
再把它当作“少量请求元数据载体”；
不要反过来。

参考

• Go context 包源码
• Go Concurrency Patterns: Context
• Context 的演进与设计