Go Context 深度解析：取消信号与请求作用域

Go 的 context 包是控制并发和传递请求作用域数据的核心机制。无论是 HTTP 服务、gRPC 调用还是数据库操作，正确使用 Context 都是编写健壮 Go 代码的关键。

一、为什么需要 Context？#

1.1 问题场景#

1
// 场景：用户请求需要取消
2
func handleRequest(req Request) {
3
    result := doSlowWork()  // 耗时操作
4

5
    // 问题：如果客户端断开连接，doSlowWork 还在继续执行
6
}
7

8
// 场景：请求需要超时控制
9
func fetchUserData(userID string) {
10
    data := database.Query(userID)  // 可能很慢
11

12
    // 问题：没有超时控制，可能无限等待
13
}

1.2 Context 的作用#

1
// 解决方案：使用 Context
2
func handleRequest(ctx context.Context, req Request) error {
3
    // ctx 可以被取消
4
    result, err := doSlowWork(ctx)  // 传递 ctx
5
    if err != nil {
6
        return err
7
    }
8
    return processResult(result)
9
}

二、Context 接口#

2.1 接口定义#

1
type Context interface {
2
    // Deadline 返回 ctx 的截止时间
3
    Deadline() (deadline time.Time, ok bool)
4

5
    // Done 返回一个关闭的通道，当 ctx 被取消或超时时关闭
6
    Done() <-chan struct{}
7

8
    // Err 返回 ctx 被关闭的原因
9
    Err() error
10

11
    // Value 返回 ctx 中存储的值
12
    Value(key any) any
13
}

2.2 内置 Context#

1
var (
2
    // 不可取消，没有截止时间，没有值
3
    // 通常用于 main 函数或顶级请求
4
    background = contextImpl{}
5

6
    // TODO: 语义未明确，用于临时占位
7
    todo = contextImpl{}
8
)
9

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

三、创建子 Context#

3.1 WithCancel#

1
func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
2
    // 返回新的 ctx 和取消函数
3
    // 调用 cancel() 会关闭 Done() 通道
4
}
5

6
func main() {
7
    ctx, cancel := context.WithCancel(context.Background())
8
    defer cancel()
9

10
    go func() {
11
        time.Sleep(2 * time.Second)
12
        cancel()  // 取消操作
13
    }()
14

15
    select {
16
    case <-ctx.Done():
17
        fmt.Println("Cancelled:", ctx.Err())
18
    }
19
}

3.2 WithTimeout#

1
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
2
    // 返回带超时的 ctx
3
    // 相当于 WithDeadline(parent, time.Now().Add(timeout))
4
}
5

6
func main() {
7
    ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
8
    defer cancel()
9

10
    result, err := fetchData(ctx)
11
    if err != nil {
12
        fmt.Println("Error:", err)  // 3 秒后会超时
13
    }
14
}

3.3 WithDeadline#

1
func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc) {
2
    // 返回在指定时间点过期的 ctx
3
}
4

5
func main() {
6
    // 设置截止时间：明天 12:00
7
    deadline := time.Date(2024, 1, 1, 12, 0, 0, 0, time.UTC)
8
    ctx, cancel := context.WithDeadline(context.Background(), deadline)
9
    defer cancel()
10
}

3.4 WithTimeout vs WithDeadline 时间线#

WithTimeout 和 WithDeadline 其实是同一个机制，区别仅在于时间参数的表达方式。WithTimeout(parent, timeout) 等价于 WithDeadline(parent, time.Now().Add(timeout))。

下面的时间线展示了二者的关系：

gantt title WithTimeout vs WithDeadline 时间线对比 dateFormat HH:mm:ss axisFormat %H:%M:%S section WithTimeout 请求开始 :a1, 00:00:00, 0s 超时 3 秒 :a2, 00:00:00, 3s section WithDeadline 请求开始 :b1, 00:00:00, 0s 截止时间 12:00:03 :milestone, 00:00:03, 0s section 效果二者等效：到期自动取消 ctx :c1, 00:00:00, 3s

选择建议：

使用 WithTimeout 当你关注”操作最长允许多久”
使用 WithDeadline 当你有一个明确的绝对时间点（如配置中的截止时间）

3.5 WithValue#

1
func WithValue(parent Context, key, val any) Context {
2
    // 返回携带值的 ctx
3
    // key 应该是不可比较的类型或自定义的 key 类型
4
}
5

6
// 推荐：定义自定义 key 类型避免冲突
7
type key string
8

9
const userIDKey key = "userID"
10
const traceIDKey key = "traceID"
11

12
func WithUserID(ctx context.Context, userID string) Context {
13
    return context.WithValue(ctx, userIDKey, userID)
14
}
15

16
func GetUserID(ctx context.Context) string {
17
    if userID, ok := ctx.Value(userIDKey).(string); ok {
18
        return userID
19
    }
20
    return ""
21
}

四、取消机制原理#

4.1 树状取消#

Context 构成树状结构，取消父节点会自动取消所有子节点。下图展示了一个典型的 Context 树形层级关系：

graph TD BG["Background() 根 Context"] --> WC1["WithCancel HTTP 请求"] BG --> WT1["WithTimeout(3s) gRPC 调用"] WC1 --> WV1["WithValue(traceID) 追踪信息"] WC1 --> WT2["WithTimeout(5s) 数据库查询"] WT1 --> WC2["WithCancel 流式处理"] WV1 --> WT3["WithTimeout(2s) 缓存读取"] WT2 --> WC3["WithCancel 结果处理"] style BG fill:#4CAF50,color:#fff style WC1 fill:#2196F3,color:#fff style WT1 fill:#FF9800,color:#fff style WV1 fill:#9C27B0,color:#fff style WT2 fill:#FF9800,color:#fff style WC2 fill:#2196F3,color:#fff style WT3 fill:#FF9800,color:#fff style WC3 fill:#2196F3,color:#fff

图解说明：

绿色节点：根 Context（Background()），永不被取消
蓝色节点：WithCancel 创建的可取消 Context
橙色节点：WithTimeout 创建的带超时 Context
紫色节点：WithValue 创建的携带值的 Context

取消传播方向为自上而下：当 HTTP 请求 Context 被取消时，其下的追踪信息、数据库查询、缓存读取等子 Context 都会被级联取消。

1
// Context 构成树状结构
2
// 取消父节点会自动取消所有子节点
3

4
func main() {
5
    parent, cancel := context.WithCancel(context.Background())
6
    defer cancel()
7

8
    child1, cancel1 := context.WithCancel(parent)
9
    child2, cancel2 := context.WithCancel(parent)
10
    defer cancel1()
11
    defer cancel2()
12

13
    // 取消 parent 会同时取消 child1 和 child2
14
    cancel()
15
}

4.2 取消传播#

下面的流程图展示了 HTTP 请求中 Context 取消信号的完整传播路径：

sequenceDiagram participant Client as 客户端 participant HTTP as HTTP Server participant Handler as Handler participant DB as 数据库 participant Cache as 缓存 Client->>HTTP: 发起请求 HTTP->>Handler: r.Context() Note over Handler: 创建子 ctx WithTimeout(ctx, 5s) Handler->>DB: QueryContext(ctx, SQL) Handler->>Cache: GetContext(ctx, key) Client-xHTTP: 断开连接 Note over HTTP: 检测到连接断开 自动 cancel ctx HTTP-->>Handler: ctx.Done() 关闭 Handler-->>DB: ctx 取消，查询终止 Handler-->>Cache: ctx 取消，读取终止 Note over Handler: 所有子操作收到取消信号 返回 context.Canceled

1
// HTTP 服务中的取消传播
2
func handleRequest(w http.ResponseWriter, r *http.Request) {
3
    ctx := r.Context()  // 获取请求的 ctx
4

5
    // 如果客户端断开连接，ctx 会自动取消
6
    result, err := doWork(ctx)
7
    if err != nil {
8
        // 处理错误
9
    }
10
}

4.3 避免泄露#

1
// 错误：忘记调用 cancel
2
func wrong() {
3
    ctx, cancel := context.WithTimeout(context.Background(), time.Hour)
4
    // 没有 defer cancel()，造成资源泄露
5
}
6

7
// 正确：确保 cancel 被调用
8
func correct() {
9
    ctx, cancel := context.WithTimeout(context.Background(), time.Hour)
10
    defer cancel()  // 函数结束时取消
11
}

五、HTTP 服务中的应用#

5.1 标准用法#

1
func main() {
2
    http.HandleFunc("/api/data", func(w http.ResponseWriter, r *http.Request) {
3
        ctx := r.Context()
4

5
        // 处理请求，传递 ctx
6
        data, err := fetchData(ctx)
7
        if err != nil {
8
            // 检查是否是 ctx 取消导致的错误
9
            if ctx.Err() == context.Canceled {
10
                http.Error(w, "Client cancelled", http.StatusClientClosedRequest)
11
                return
12
            }
13
            http.Error(w, "Internal error", http.StatusInternalServerError)
14
            return
15
        }
16

17
        json.NewEncoder(w).Encode(data)
18
    })
19

20
    log.Fatal(http.ListenAndServe(":8080", nil))
21
}

5.2 中间件模式#

1
// 追踪中间件
2
func tracingMiddleware(next http.Handler) http.Handler {
3
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
4
        ctx := r.Context()
5

6
        // 添加追踪信息
7
        traceID := generateTraceID()
8
        ctx = context.WithValue(ctx, traceIDKey, traceID)
9

10
        // 记录开始时间
11
        start := time.Now()
12

13
        // 包装 ResponseWriter 记录状态码
14
        wrapped := &statusWriter{ResponseWriter: w, statusCode: 200}
15

16
        next.ServeHTTP(wrapped, r.WithContext(ctx))
17

18
        // 记录日志
19
        log.Printf("traceID=%s status=%d duration=%v",
20
            traceID, wrapped.statusCode, time.Since(start))
21
    })
22
}
23

24
type statusWriter struct {
25
    http.ResponseWriter
26
    statusCode int
27
}
28

29
func (w *statusWriter) WriteHeader(code int) {
30
    w.statusCode = code
31
    w.ResponseWriter.WriteHeader(code)
32
}

5.3 数据库查询#

1
import "context"
2

3
// 使用 context 超时控制数据库查询
4
func queryWithTimeout(ctx context.Context, db *sql.DB) ([]Row, error) {
5
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
6
    defer cancel()
7

8
    rows, err := db.QueryContext(ctx, "SELECT * FROM users")
9
    if err != nil {
10
        return nil, err
11
    }
12
    defer rows.Close()
13

14
    return scanRows(rows)
15
}

六、gRPC 中的 Context#

6.1 传递元数据#

1
import (
2
    "google.golang.org/grpc"
3
    "google.golang.org/grpc/metadata"
4
)
5

6
func clientUnaryCall(ctx context.Context, client pb.UserServiceClient) {
7
    // 添加 metadata
8
    md := metadata.Pairs(
9
        "authorization", "Bearer token",
10
        "trace-id", traceID,
11
    )
12
    ctx = metadata.NewOutgoingContext(ctx, md)
13

14
    // 调用
15
    resp, err := client.GetUser(ctx, &pb.GetUserRequest{ID: userID})
16
}
17

18
func serverInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
19
    // 从 context 提取 metadata
20
    md, ok := metadata.FromIncomingContext(ctx)
21
    if !ok {
22
        return nil, status.Error(codes.Unauthenticated, "missing metadata")
23
    }
24

25
    token := md.Get("authorization")
26
    if len(token) == 0 {
27
        return nil, status.Error(codes.Unauthenticated, "missing token")
28
    }
29

30
    // 继续处理
31
    return handler(ctx, req)
32
}

6.2 取消传播#

1
// 客户端取消传播到服务端
2
ctx, cancel := context.WithCancel(parentCtx)
3
defer cancel()
4

5
stream, err := client.StreamData(ctx, &pb.StreamRequest{})
6
// 如果 cancel() 被调用，服务端会收到 ctx.Canceled

七、值传递最佳实践#

7.1 Key 类型设计#

1
// 错误：使用字符串 key，容易冲突
2
ctx.Value("userID")  // 可能返回其他包的同名值
3

4
// 正确：定义专属类型
5
type userIDKey struct{}
6
type traceIDKey struct{}
7

8
func GetUserID(ctx context.Context) string {
9
    if v := ctx.Value(userIDKey{}); v != nil {
10
        return v.(string)
11
    }
12
    return ""
13
}
14

15
// 使用包级别的私有 key
16
var keyUserID = struct{}{}
17
var keyTraceID = struct{}{}

7.2 Context 的值不应该用于#

Context Value 不是万能容器，滥用会导致隐式依赖，让代码难以理解和测试。

错误用法（应该用其他机制）：

传递可选参数 → 用函数选项模式（func Option）
传递依赖注入 → 用 DI 容器或构造函数注入
传递日志记录器 → 用结构化日志库的全局 logger 或结构体字段

正确用法（请求作用域的元数据）：

请求作用域的追踪 ID（trace ID）
请求作用域的用户信息（从认证中间件提取）
取消信号（Context 的本职工作）

八、常见陷阱#

8.1 Context 值是并发安全的#

Context.Value() 是并发安全的，多个 goroutine 可以同时读取同一个 Context 的值。这是因为 WithValue 创建的是新的链表节点，而不是修改已有 Context，每次 WithValue 都返回一个新 Context，原 Context 不变。

8.2 不要把 Context 放在结构体里#

1
// 错误：将 Context 存储在结构体中
2
type Request struct {
3
    ctx  context.Context  // 不应该放在这里
4
    Data string
5
}
6

7
func (r *Request) Process() error {
8
    // ctx 的生命周期与 Request 绑定，难以追踪取消来源
9
    return doWork(r.ctx)
10
}

1
// 正确：Context 作为函数的第一个参数传递
2
type Request struct {
3
    Data string
4
}
5

6
func Process(ctx context.Context, req *Request) error {
7
    // ctx 的生命周期由调用方控制，清晰且可追踪
8
    return doWork(ctx)
9
}

8.3 超时设置要合理#

超时时间过长等于没有超时，过短则会导致正常操作被误杀。设置超时的原则是：根据下游操作的 P99 延迟加上合理缓冲，而非拍脑袋决定。

1
// 过长：失去控制作用：24 小时超时对 HTTP 请求毫无意义
2
ctx, _ := context.WithTimeout(ctx, 24*time.Hour)
3

4
// 过短：还没完成就超时：1ms 对数据库查询来说太苛刻
5
ctx, _ := context.WithTimeout(ctx, 1*time.Millisecond)
6

7
// 合理：根据操作预估时间设置，留一定余量
8
ctx, _ := context.WithTimeout(ctx, 30*time.Second)

九、Go 1.20 Context 新特性#

Go 1.20 为 context 包引入了两个新 API：WithCancelCause 和 Cause，用于在取消 Context 时携带原因信息，解决了传统 WithCancel 只能返回 context.Canceled 通用错误的局限。

9.1 WithCancelCause ，携带原因的取消#

传统的 WithCancel 调用 cancel() 时，ctx.Err() 只能返回 context.Canceled，无法区分取消的具体原因。WithCancelCause 允许在取消时传入一个 error 作为原因。

1
// WithCancelCause 返回一个可携带取消原因的 Context
2
// 源码参考：https://github.com/golang/go/blob/go1.25.0/src/context/context.go
3
func WithCancelCause(parent Context) (ctx Context, cancel CancelCauseFunc)
4

5
// CancelCauseFunc 是带原因的取消函数
6
type CancelCauseFunc func(cause error)

1
package main
2

3
import (
4
    "context"
5
    "errors"
6
    "fmt"
7
    "time"
8
)
9

10
// 定义具体的取消原因
11
var (
12
    ErrUserCancelled    = errors.New("user cancelled the request")
13
    ErrTimeoutExceeded  = errors.New("operation exceeded timeout")
14
    ErrShuttingDown     = errors.New("server is shutting down")
15
)
16

17
func main() {
18
    ctx, cancel := context.WithCancelCause(context.Background())
19

20
    go func() {
21
        time.Sleep(2 * time.Second)
22
        // 传入具体的取消原因
23
        cancel(ErrUserCancelled)
24
    }()
25

26
    select {
27
    case <-ctx.Done():
28
        // ctx.Err() 仍然返回 context.Canceled
29
        fmt.Println("Err:", ctx.Err())
30

31
        // context.Cause(ctx) 返回具体的原因
32
        fmt.Println("Cause:", context.Cause(ctx))
33
        // 输出: Cause: user cancelled the request
34
    }
35
}

9.2 Cause ，获取取消原因#

context.Cause(ctx) 函数用于获取 Context 被取消的具体原因。

1
// Cause 返回导致 ctx 被取消的原始错误
2
// 如果 ctx 没有被取消，返回 nil
3
// 如果是通过 WithCancelCause 取消的，返回传入的 cause
4
// 如果是其他方式取消的，返回 ctx.Err()
5
func Cause(ctx Context) error

1
func handleRequest(ctx context.Context) {
2
    <-ctx.Done()
3

4
    // 区分不同的取消原因
5
    switch cause := context.Cause(ctx); {
6
    case errors.Is(cause, ErrUserCancelled):
7
        fmt.Println("用户主动取消，清理部分结果")
8
        cleanupPartialResults()
9
    case errors.Is(cause, ErrTimeoutExceeded):
10
        fmt.Println("操作超时，记录慢查询日志")
11
        logSlowOperation()
12
    case errors.Is(cause, ErrShuttingDown):
13
        fmt.Println("服务关闭，持久化当前状态")
14
        persistState()
15
    default:
16
        fmt.Println("未知取消原因:", cause)
17
    }
18
}

9.3 WithCancelCause 与 WithCancel 的对比#

特性	`WithCancel`	`WithCancelCause`
取消函数签名	`func()`	`func(error)`
`ctx.Err()` 返回	`context.Canceled`	`context.Canceled`
获取具体原因	不支持	`context.Cause(ctx)`
向后兼容	—	完全兼容，`cancel(nil)` 等价于旧版

迁移建议： 在新代码中优先使用 WithCancelCause 替代 WithCancel，即使暂时不需要原因信息，传入 nil 即可保持相同行为，为将来扩展预留空间。

十、Go 1.21 Context 新特性#

Go 1.21 为 context 包引入了两个重要 API：WithoutCancel 和 AfterFunc，分别用于脱离父 Context 的取消信号和注册取消后的回调函数。

10.1 WithoutCancel ，脱离父级取消#

在处理 HTTP 请求时，经常需要在请求结束后继续执行一些后台任务（如日志记录、指标上报、缓存预热等）。但请求的 Context 被取消后，这些后台任务也会被终止。WithoutCancel 可以创建一个不受父级取消影响的 Context。

1
// WithoutCancel 返回一个新 Context，它不受 parent 取消的影响
2
// 新 Context 没有截止时间，也不会被父级取消
3
// 但保留了 parent 中的值（Value）
4
// 源码参考：https://github.com/golang/go/blob/go1.25.0/src/context/context.go
5
func WithoutCancel(parent Context) Context

1
func handleRequest(w http.ResponseWriter, r *http.Request) {
2
    ctx := r.Context()
3

4
    // 处理请求
5
    data, err := fetchData(ctx)
6
    if err != nil {
7
        http.Error(w, err.Error(), http.StatusInternalServerError)
8
        return
9
    }
10
    json.NewEncoder(w).Encode(data)
11

12
    // 请求已响应，但需要在后台继续处理
13
    // 使用 WithoutCancel 创建脱离请求生命周期的 Context
14
    bgCtx := context.WithoutCancel(ctx)
15

16
    // bgCtx 中的 Value 仍然可以访问
17
    traceID := ctx.Value(traceIDKey)  // 可以读取
18

19
    go func() {
20
        // 即使原始请求 ctx 被取消，bgCtx 也不会被取消
21
        logAccess(bgCtx, traceID, data)
22
        updateCache(bgCtx, data)
23
        emitMetrics(bgCtx, data)
24
    }()
25
}

使用场景：

1
// 场景 1：请求完成后的异步日志记录
2
func logAfterResponse(ctx context.Context, req *http.Request) {
3
    bgCtx := context.WithoutCancel(ctx)
4
    go func() {
5
        // 不受请求取消影响
6
        log.Printf("method=%s path=%s traceID=%s",
7
            req.Method, req.URL.Path, bgCtx.Value(traceIDKey))
8
    }()
9
}
10

11
// 场景 2：请求触发的后台任务需要独立的超时控制
12
func spawnBackgroundTask(ctx context.Context) {
13
    bgCtx := context.WithoutCancel(ctx)
14
    // 给后台任务单独设置超时
15
    taskCtx, cancel := context.WithTimeout(bgCtx, 10*time.Minute)
16
    defer cancel()
17

18
    go processInBackground(taskCtx)
19
}

注意事项：

WithoutCancel 返回的 Context 没有截止时间（Deadline() 返回 false）
Done() 通道为 nil（永远不会关闭）
Err() 永远返回 nil
但 Value() 方法仍然可以读取父 Context 中的值

10.2 AfterFunc ，注册取消后的回调#

AfterFunc 允许在 Context 被取消或超时后自动执行一个函数。这为资源清理、通知下游服务等场景提供了更优雅的方式。

1
// AfterFunc 注册一个在 ctx 被取消后异步调用 f 的回调
2
// 返回一个 stop 函数，调用它可以取消注册（如果 f 尚未执行）
3
// 如果 ctx 已经被取消，f 会在新的 goroutine 中立即执行
4
// 源码参考：https://github.com/golang/go/blob/go1.25.0/src/context/context.go
5
func AfterFunc(ctx Context, f func()) (stop func() bool)

1
func main() {
2
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
3
    defer cancel()
4

5
    // 注册取消后的清理回调
6
    stop := context.AfterFunc(ctx, func() {
7
        fmt.Println("Context 被取消，执行清理操作...")
8
        cleanupResources()
9
        notifyDependentServices()
10
    })
11

12
    // 如果需要在 ctx 取消前停止回调
13
    defer stop()
14

15
    // 模拟工作
16
    doWork(ctx)
17
}

实际应用：连接池释放

1
func handleConnection(ctx context.Context, pool *ConnectionPool) error {
2
    conn, err := pool.Get(ctx)
3
    if err != nil {
4
        return err
5
    }
6

7
    // 当 ctx 被取消时，自动将连接归还到池中
8
    stop := context.AfterFunc(ctx, func() {
9
        fmt.Println("请求取消，释放连接回连接池")
10
        pool.Put(conn)
11
    })
12
    defer stop()
13

14
    // 使用连接处理业务
15
    return processWithConn(ctx, conn)
16
}

实际应用：超时降级通知

1
func fetchWithFallback(ctx context.Context) ([]byte, error) {
2
    ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
3
    defer cancel()
4

5
    var fallbackTriggered atomic.Bool
6

7
    // 注册超时后的降级回调
8
    context.AfterFunc(ctx, func() {
9
        if fallbackTriggered.CompareAndSwap(false, true) {
10
            // 超时后触发降级：使用缓存数据
11
            log.Println("请求超时，触发降级逻辑")
12
            triggerFallbackCache()
13
        }
14
    })
15

16
    data, err := fetchFromPrimary(ctx)
17
    if err != nil {
18
        return nil, err
19
    }
20
    return data, nil
21
}

10.3 AfterFunc 的 stop 函数详解#

AfterFunc 返回的 stop 函数有几个重要行为：

1
ctx, cancel := context.WithCancel(context.Background())
2

3
// 注册回调
4
stop := context.AfterFunc(ctx, func() {
5
    fmt.Println("回调已执行")
6
})
7

8
// stop() 的行为：
9
// 1. 如果 f 尚未启动，取消注册并返回 true
10
// 2. 如果 f 已经启动，返回 false（无法停止正在运行的 f）
11
// 3. 如果 f 已经执行完毕，返回 false
12
result := stop()
13
fmt.Println("是否成功阻止回调:", result)
14

15
cancel() // 取消 ctx

最佳实践： 总是 defer stop()，确保在函数退出时清理注册，避免回调在不需要时执行。

十一、源码解析#

Note

以下源码分析基于 Go 官方仓库： context/context.go

11.1 cancelCtx 实现#

1
// cancelCtx 是 WithCancel 和 WithCancelCause 的底层实现
2
// 源码：https://github.com/golang/go/blob/go1.25.0/src/context/context.go
3
type cancelCtx struct {
4
    Context
5
    mu       sync.Mutex
6
    done     atomic.Value  // 惰性初始化的 chan struct{}
7
    children map[canceler]struct{}
8
    err      error         // 取消原因
9
}

propagateCancel：父子关联的建立

WithCancel 创建子 context 时，调用 propagateCancel 将子 context 注册到父 context 的 children 中：

1
func propagateCancel(parent Context, child canceler) {
2
    done := parent.Done()
3
    if done == nil {
4
        return  // 父 context 永远不会被取消，不需要注册
5
    }
6
    select {
7
    case <-done:
8
        // 父 context 已经取消了，直接取消子 context
9
        child.cancel(false, parent.Err())
10
        return
11
    default:
12
    }
13

14
    if p, ok := parentCancelCtx(parent); ok {
15
        // 父 context 是 *cancelCtx 类型，直接加入 children
16
        p.mu.Lock()
17
        if p.err != nil {
18
            // 父 context 在我们加锁之前就被取消了
19
            p.mu.Unlock()
20
            child.cancel(false, p.err)
21
        } else {
22
            if p.children == nil {
23
                p.children = make(map[canceler]struct{})
24
            }
25
            p.children[child] = struct{}{}
26
            p.mu.Unlock()
27
        }
28
        return
29
    }
30

31
    // 父 context 不是 *cancelCtx（如 valueCtx），启动 goroutine 监听
32
    goroutines.Add(1)
33
    go func() {
34
        select {
35
        case <-parent.Done():
36
            child.cancel(false, parent.Err())
37
        case <-child.Done():
38
        }
39
    }()
40
}

第三种情况值得注意：如果父 context 不是 *cancelCtx（比如是 valueCtx 包装的 cancelCtx），无法直接访问 children map，只能启动一个 goroutine 来监听父 context 的 Done 通道。这意味着 WithValue 的滥用会增加 goroutine 数量。

cancel：递归取消

1
func (c *cancelCtx) cancel(removeFromParent bool, err error) {
2
    c.mu.Lock()
3
    if c.err != nil {
4
        c.mu.Unlock()
5
        return  // 已经取消过
6
    }
7
    c.err = err
8
    d, _ := c.done.Load().(chan struct{})
9
    if d == nil {
10
        c.done.Store(closedchan)  // 使用预创建的已关闭 channel
11
    } else {
12
        close(d)  // 关闭 Done 通道
13
    }
14

15
    // 递归取消子节点
16
    for child := range c.children {
17
        child.cancel(false, err)
18
    }
19
    c.children = nil
20
    c.mu.Unlock()
21

22
    if removeFromParent {
23
        removeChild(c.Context, c)
24
    }
25
}

cancel 关闭 Done 通道后，遍历 children 递归调用每个子节点的 cancel。removeFromParent 参数只在最外层调用时为 true（用户手动调用 cancel() 时），递归调用时为 false，避免重复从父节点中移除。

十二、常见问题 FAQ#

Q1：context.Background 和 context.TODO 有什么区别？#

Background 返回非 nil 空 context，作为整棵 context 树的根。TODO 语义上表示”暂时不确定用什么 context，后续补充”。功能上相同，区别仅在语义。

Q2：context.Value 应该用来传什么？#

只传请求级别的元数据（trace_id、user_id 等），不传业务参数或可选配置。Value 机制是附加的，不应成为参数传递的主要方式。滥用 Value 会导致隐式依赖。

Q3：WithCancel 和 WithTimeout 怎么选？#

WithTimeout 适合有明确超时时间的场景（如 RPC 调用）。WithCancel 适合需要手动取消的场景（如用户中断）。WithTimeout 本质是 WithDeadline 的语法糖。

Q4：context 取消后，goroutine 会自动退出吗？#

不会。context 取消只是发出信号（ctx.Done() 返回 closed channel），goroutine 需要自己检查 ctx.Done() 并主动退出。不会强制中断 goroutine 的执行。

小结#

Context 的设计本质是一个请求作用域的信号树<取消信号从根到叶级联传播>,超时信号在时钟到期时自动触发,Value 沿着树向上查找。这个模型解决了一个核心问题,当一个请求被取消(客户端断连、超时到期),所有为这个请求服务的子操作都应该立刻停止,而不是继续浪费 CPU 和 I/O。使用 Context 的最大陷阱是把 Context 当成参数传递的万能容器，Value 只应该承载请求级别的元数据(trace ID、用户身份),业务参数和可选配置应该走函数签名或依赖注入。Go 1.20 的 WithCancelCause 和 Go 1.21 的 WithoutCancel/AfterFunc 填补了原始设计的两个缺口<前者让你区分>”为什么取消”,后者让你在请求结束后继续执行清理逻辑而不被父 Context 的取消信号中断。什么时候不该用 Context?当你发现它在结构体字段里而不是函数参数里时,Context 的生命周期应该由调用方控制,而不是被某个长生命周期对象持有。

参考资料#

Go 官方 context 包文档 - Context 接口 API 参考与使用说明
Go 1.20 Release Notes — context 包 - WithCancelCause 和 Cause 新增 API
Go 1.21 Release Notes — context 包 - WithoutCancel 和 AfterFunc 新增 API
Go Context 源码 - 官方 context 包完整实现
Go Concurrency Patterns: Context - Go 官方博客关于 Context 的设计理念