---
tags: [go, context, goroutine, cancellation]
create time: 2026-05-06 15:30
---

# Go Context

## 概述

梳理 Go 标准库 `context` 包的核心机制与最佳实践：涵盖上下文树的创建与传播、取消信号传递、超时控制、请求级值存储，以及常见陷阱的规避方案。

## 正文

### 一、为什么需要 Context

> [!question] 思考：如果没有 context，如何优雅地停止一组 goroutine？

Go 的 goroutine 像线程一样运行在后台。当某个请求的处理逻辑已经完成，但它在内部启动的多个 goroutine 仍在跑——这些 goroutine 就成了"孤儿"，白白消耗 CPU 和内存。

```go
func fetchData() {
    dataCh := make(chan string)
    go func() {
        // 模拟一个永远超时的网络请求
        resp, _ := http.Get("https://example.com")
        dataCh <- resp.Status
    }()

    time.Sleep(1 * time.Second)
    return // 函数返回了，但上面的 goroutine 永远不会结束
}
```

Context 提供了三个核心能力来解决这个问题：

| 能力 | 说明 |
|------|------|
| **取消信号** | 沿调用链向下广播取消通知，让所有子 goroutine 及时退出 |
| **截止时间** | 自动触发取消（超时 / 指定时刻） |
| **请求级值传递** | 跨 goroutine 安全地携带请求上下文信息（如 TraceID、用户认证信息） |

### 二、根 Context：Background vs TODO

Context 世界从"根节点"开始：

```go
// 大多数情况下使用这个
ctx := context.Background()

// 当你不确定该用哪个，或者代码还在雏形阶段
ctx := context.TODO()
```

- **`Background()`**：正式的根 context，通常用在 `main` 入口或测试中，作为整棵 context 树的起点。
- **`TODO()`**：占位符。当函数暂时无法获取一个有意义的 context 时用它。**它只是一个临时方案**——如果你发现自己在产品代码中长期使用 `TODO()`，应该重构为接收上游传入的 `ctx`。

> [!tip] 关键认知
>
> Context 不是全局变量！它是沿着调用链**自上而下**单向传递的。每个函数只知道自己上方的 context，不直接感知下游。

### 三、衍生 Context：WithCancel / WithTimeout / WithDeadline

通过三个 `WithXxx` 函数，可以从父 context 派生出子 context，形成一棵树：

```go
// 手动取消
ctx, cancel := context.WithCancel(parentCtx)
cancel() // 立即向所有后代发送取消信号

// 自动超时取消
ctx, cancel := context.WithTimeout(parentCtx, 5*time.Second)
defer cancel() // 即使提前返回也要显式取消

// 指定绝对时间取消
ctx, cancel := context.WithDeadline(parentCtx, time.Now().Add(10*time.Minute))
defer cancel()
```

三者本质上是一个东西：`WithTimeout` = `WithDeadline(now + duration)`，`WithCancel` = 无截止时间的纯手动取消。

#### 3.1 Context 树的结构

```mermaid
flowchart TD
    BG["Background()"] --> R1["Request Handler\nWithCancel"]
    R1 --> DB["Database Query\nWithTimeout 3s"]
    R1 --> API["External API Call\nWithTimeout 5s"]
    API --> Cache["Cache Lookup\nWithValue"]

    style BG fill:#eee,stroke:#333
    style R1 fill:#bbf,stroke:#333
    style DB fill:#bfb,stroke:#333
    style API fill:#bbf,stroke:#333
    style Cache fill:#fee,stroke:#333
```

当 `R1` 被取消时，`DB`、`API` 以及 `API` 的子 context `Cache` 都会**自动收到取消信号**。这是一种递归传播机制——父被取消，所有子孙都会被取消。

> [!warning] 资源泄漏警告
>
> `WithTimeout` 和 `WithDeadline` 返回的 `cancel` 函数即使设置了超时也会注册 timer。**如果子 context 提前完成但没有调用 `cancel()`，timer 会一直持有引用直到超时**。虽然影响不大，养成 `defer cancel()` 的习惯是好事情。

#### 3.2 实际效果演示

```go
func worker(ctx context.Context, name string) {
    for {
        select {
        case <-ctx.Done():
            fmt.Printf("[%s] canceled: %v\n", name, ctx.Err())
            return
        default:
            fmt.Printf("[%s] working...\n", name)
            time.Sleep(200 * time.Millisecond)
        }
    }
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 600*time.Millisecond)
    defer cancel()

    go worker(ctx, "A")
    go worker(ctx, "B")

    time.Sleep(1 * time.Second)
}
// 输出：每个 worker 打印约 3 次后都收到 canceled: context deadline exceeded
```

`select` 中对 `<-ctx.Done()` 的检查是**让 goroutine 感知取消的标准写法**。

#### 3.3 ctx.Err() 的含义

```go
ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()
time.Sleep(200 * time.Millisecond)

switch ctx.Err() {
case context.DeadlineExceeded:
    fmt.Println("超时了")
case context.Canceled:
    fmt.Println("被主动取消了")
}
```

| `ctx.Err()` 返回值 | 含义 |
|---------------------|------|
| `nil` | context 仍然有效 |
| `context.Canceled` | 被 `cancel()` 主动取消 |
| `context.DeadlineExceeded` | 到达截止时间自动取消 |

> [!note] 错误语义
>
> 在 HTTP handler 或服务框架中，`ctx.Err() == context.Canceled` 通常表示客户端断开了连接。你可以借此跳过不必要的后端处理来节省资源。

### 四、WithValue：携带请求级数据

Context 不仅可以传递取消信号，还能携带只在当前请求生命周期内有效的键值对。

#### 4.1 基本用法

```go
ctx := context.Background()
ctx = context.WithValue(ctx, "userID", 42)
userID := ctx.Value("userID") // 返回 any
```

#### 4.2 Key 类型的重要性 ⚠️

这是 `WithValue` 最容易被忽略的关键点：

```go
type ctxKey string

const userIDKey ctxKey = "userID"
// ctxKey 是自定义零实例类型，确保 key 的唯一性
```

**不要用 `string` 或 `int` 做 key！** 理由如下：

```go
// ❌ 危险：任何包都用 "userID" 这个字符串，可能产生碰撞
ctx := context.WithValue(context.Background(), "userID", 42)
val := ctx.Value("userID")

// ✅ 安全：零实例类型的地址在整个进程中唯一
type userIDKey struct{}
ctx := context.WithValue(context.Background(), userIDKey{}, 42)
```

> [!summary] Key 类型的正确姿势
>
> 定义一个没有任何方法的零结构体：
>
> ```go
> type traceIDKey struct{} // 空结构体零开销
> ctx := context.WithValue(ctx, traceIDKey{}, traceID)
> ```
>
> 这样即便其他包也定义了同名的 key，它们在运行时也不会碰撞，因为它们是不同类型。

#### 4.3 哪些值不该放进 Context？

| 不该做的事 | 原因 |
|-----------|------|
| 存放敏感数据（密码、token） | Context 会被日志、debug 工具随意读取，难以追踪生命周期 |
| 存放大数据量（大对象、切片） | 持有 Context 的所有地方都间接持有了这些数据，导致 GC 延迟回收 |
| 存放本可以用参数传递的数据 | Context 是可选的参数，不是万能传参通道 |
| 将 Context 存入 struct 作为字段 | Context 的生命周期属于**单次请求/操作**，不应成为对象的属性 |

> [!tip] Context 的使用场景总结
>
> 适合放入 Context 的值：TraceID、用户身份标识（不含凭证）、超时配置、区域设置偏好等**仅在当前请求上下文中有意义且生命周期与请求绑定的元信息**。

#### 4.4 Value 传递的方向

Context 的 value 是**单向传递**的，只能由父到子，不能向上回传：

```go
parent := context.WithValue(context.Background(), "key", "parent-value")
child := context.WithValue(parent, "key", "child-value")

parent.Value("key") // "parent-value" —— 父不知道子覆盖了自己的值
child.Value("key")  // "child-value"
```

这种设计保证了各层级不会被意外篡改上游数据。

### 五、实战：HTTP 请求中的组合拳

实际开发中最常见的组合模式：**超时控制 + 取消 + Value 传递**。

```go
func handleRequest(w http.ResponseWriter, r *http.Request) {
    // 生成本次请求的 TraceID
    traceID := generateTraceID()

    // 构建带 traceId 的请求 context
    ctx := context.WithValue(r.Context(), traceIDKey{}, traceID)

    // 添加 3 秒超时保护
    ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()

    // 同时启动两个独立任务
    resultCh := make(chan string, 2)

    go fetchFromServiceA(ctx, resultCh)
    go fetchFromServiceB(ctx, resultCh)

    // 等待两个结果（任一失败则取消整个请求）
    for i := 0; i < 2; i++ {
        if result := <-resultCh; result != "" {
            w.Write([]byte(result))
            cancel() // 拿到结果后主动取消，释放资源
            return
        }
    }
}
```

> [!important] 为什么不用全局变量存 traceId？
>
> 因为有高并发：同一个进程同时处理成百上千个请求，goroutine 随时切换。如果把 traceId 存入包级变量，不同请求会互相覆盖。**Context 天然保证了值的隔离性**——每个请求有自己独立的 context 树，互不干扰。

### 六、高级用法：自定义 Context

标准库提供的方法覆盖了绝大多数场景。但在某些特定需求下，可能需要自建 context。

```go
type myContext struct {
    context.Context       // 嵌入标准接口
    timeout time.Duration
}

func (c myContext) Timeout() time.Duration {
    return c.timeout
}

// 包装标准 context，增加额外功能
func wrapWithTimeout(parent context.Context, d time.Duration) myContext {
    return myContext{Context: parent, timeout: d}
}

// 使用方式
ctx := wrapWithTimeout(context.Background(), 5*time.Second)
fmt.Println(ctx.Timeout()) // 5s —— 额外的方法，不影响原有的 Done()/Err()
```

> [!note] 什么时候需要自定义？
>
> 99% 的场景不需要。标准库的三个 `WithXxx` 加上 `WithValue` 已足够。**只有在你的框架需要暴露额外的 context 相关行为时**（比如上面示例中的额外 `.Timeout()` 方法），才考虑自定义。记住：自定义 Context 也必须实现 `context.Context` 接口，并且最好嵌入一个已有的 context 来继承其行为。

### 七、常见陷阱清单

#### 7.1 遗漏 nil Check

```go
// ❌ 错误：Context 是接口类型，零值为 nil
var ctx context.Context  // nil
ctx.Value("key")         // panic: nil map read

// ✅ 正确：始终从 Background() 或函数参数获取
ctx := context.Background()
```

#### 7.2 在循环中使用同一个 Context

```go
// ❌ 问题：每次循环复用同一个 ctx，第一次 cancel 后后续全部失效
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
for _, item := range items {
    doWork(ctx, item)  // 第二次调用时 ctx 已经被 cancel 了
}

// ✅ 修正：每次循环创建新的带超时 context
for _, item := range items {
    childCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
    doWork(childCtx, item)
    cancel()
}
```

#### 7.3 忘记在 goroutine 中检查 ctx.Done()

```go
// ❌ goroutine 永远不会响应取消信号
go func() {
    longOperation() // 没有 select ctx.Done()，cancel 后仍然继续执行
}()

// ✅ 正确的做法：每次长时间操作的入口处都要检查
go func() {
    select {
    case <-ctx.Done():
        return
    default:
        longOperation()
    }
}()
```

#### 7.4 嵌套 Context 过多导致性能问题

```go
// ❌ 三层嵌套，每层都注册 cancel callback，链路过长
ctx := context.Background()
ctx = context.WithValue(ctx, k1, v1)      // layer 1
ctx = context.WithValue(ctx, k2, v2)      // layer 2
ctx = context.WithCancel(ctx)              // layer 3
ctx = context.WithTimeout(ctx, 5*time.S)  // layer 4

// ✅ 合并相近操作
ctx, cancel := context.WithTimeout(context.Background(), 5*time.S)
ctx = context.WithValue(ctx, someKey{}, val)
```

## 关联笔记

- [[Go 多态]]
- [[Go 工程模块化]]