Go语言context.Context的传递链与取消机制

context.Context 是 Go 语言中用于在 goroutine 之间传递请求域元数据、控制超时与取消信号的标准化接口。正确使用 context 能有效防止 goroutine 泄漏，并实现优雅的并发控制。下面通过循序渐进的步骤，掌握其传递链与取消机制。

1. 理解 context.Context 接口

context 包 的核心是 Context 接口，它包含四个方法：

关键概念：Done() 返回的 channel 是取消通知的唯一通道。当父 context 被取消或超时，所有派生子 context 的 Done() channel 都会同时被关闭。

2. 获取根 context

根 context 是应用中最顶层的 context，不会被自动取消。使用以下两种方式创建：

• context.Background() – 返回一个非 nil 的空 context，通常用于 main 函数、初始化以及测试中作为请求的顶层 context。
• context.TODO() – 在不确定应使用何种 context 时作为占位符，逻辑与 Background() 相同，但语义上表示后续需要替换。

操作：在你的程序入口处 调用 context.Background()，并将返回值保存为变量。

ctx := context.Background()

3. 派生 context：构建传递链

所有实际操作的 context 都是从根 context 派生的。派生函数接收父 context 作为参数，返回子 context 和一个取消函数（CancelFunc），或是一个新的 value context。

3.1 使用 WithCancel 创建可取消的 context

WithCancel(parent Context) (ctx Context, cancel CancelFunc)

• 返回的子 context 会在以下两种情况下取消：
  1. 父 context 被取消。
  2. 显式调用返回的 cancel() 函数。

操作：创建可取消 context，并在函数返回前 延迟调用 cancel() 以释放资源。

ctx, cancel := context.WithCancel(context.Background())
defer cancel() // 确保资源释放

3.2 使用 WithTimeout 创建带超时的 context

WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)

• 子 context 会在超时时间到达后自动取消，或者父 context 被取消时取消。
• 返回的 CancelFunc 也可手动提前取消。

操作：设置超时时间为 2 秒。

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

3.3 使用 WithDeadline 创建指定截止时间的 context

WithDeadline(parent Context, d time.Time) (Context, CancelFunc)

• 与 WithTimeout 类似，但指定的是绝对时间点。

操作：设置截止时间为当前时间后 5 秒。

deadline := time.Now().Add(5 * time.Second)
ctx, cancel := context.WithDeadline(context.Background(), deadline)
defer cancel()

3.4 使用 WithValue 传递请求域数据

WithValue(parent Context, key, val interface{}) Context

• 在 context 链上绑定一个键值对，后续所有从此派生的子 context 均可通过 Value() 读取。
• 注意：key 通常是自定义类型，避免与标准库 key 冲突。

操作：绑定用户 ID 到 context。

type contextKey string
const userIDKey contextKey = "userID"

ctx := context.WithValue(context.Background(), userIDKey, "12345")

传递链本质是 context 树的构建：

每个子 context 都保存了父 context 的引用，形成单向链表。当父 context 取消时，会递归关闭所有子 context 的 Done() channel。

4. 传递 context 的规范

核心规则：将 context 作为函数的第一个参数，参数名统一为 ctx，类型为 context.Context。

操作：在函数签名中 定义 ctx 参数。

func DoSomething(ctx context.Context, data string) error {
    // 使用 ctx 控制超时或取消
    select {
    case <-ctx.Done():
        return ctx.Err()
    default:
        // 执行具体逻辑
    }
    return nil
}

禁止：

• 将 context 存储在结构体字段中（应作为参数传递）。
• 传递 nil context（如果不确定，使用 context.TODO() 作为临时占位）。
• 使用 Value() 传递可选参数（应该通过普通参数传递）。

5. 取消机制的传播与监听

当父 context 被取消时，其所有派生子 context（包括递归派生）都会被取消。监听取消信号的方式是 select 中读取 ctx.Done()。

5.1 主动取消：调用 cancel()

操作：在发现错误或不再需要 goroutine 时 调用 cancel()。

ctx, cancel := context.WithCancel(context.Background())
go func() {
    // 模拟工作
    time.Sleep(1 * time.Second)
    cancel() // 主动取消
}()

<-ctx.Done() // 等待取消
fmt.Println(ctx.Err()) // 输出: context canceled

5.2 超时取消：自动触发

操作：使用 WithTimeout 后，超时时间到达时自动关闭 Done() channel。

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

select {
case <-time.After(200 * time.Millisecond):
    fmt.Println("completed")
case <-ctx.Done():
    fmt.Println("timeout:", ctx.Err()) // 输出: timeout: context deadline exceeded
}

5.3 在 goroutine 中正确监听

操作：在 goroutine 内使用 select 同时监听 Done() 和正常逻辑通道。

func worker(ctx context.Context, jobs <-chan int) {
    for {
        select {
        case <-ctx.Done():
            return // 清理退出
        case job, ok := <-jobs:
            if !ok {
                return // 通道关闭
            }
            // 处理 job
            _ = job
        }
    }
}

5.4 检查 context 是否已取消而不阻塞

操作：使用 ctx.Done() 的 非阻塞 select 或直接调用 ctx.Err()（如果 context 未取消，返回 nil）。

select {
case <-ctx.Done():
    // 已取消
default:
    // 未取消
}

// 或者
if ctx.Err() != nil {
    // 已取消
}

6. 完整示例：带超时的 HTTP 请求

场景：发起外部 API 请求，若 3 秒内未响应则取消。

操作：创建根 context，派生带超时的 context，传递给 HTTP 请求函数。

package main

import (
    "context"
    "fmt"
    "io"
    "net/http"
    "time"
)

func fetchData(ctx context.Context, url string) (string, error) {
    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return "", err
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return "", err
    }
    return string(body), nil
}

func main() {
    // 创建超时 context
    ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
    defer cancel()

    data, err := fetchData(ctx, "https://httpbin.org/delay/5")
    if err != nil {
        fmt.Println("Error:", err) // 超时后输出: context deadline exceeded
        return
    }
    fmt.Println("Data:", data)
}

解释：

• http.NewRequestWithContext 将 context 绑定到请求。
• 如果 3 秒内服务器未响应，context 超时取消，Do 方法会立即返回 context.DeadlineExceeded 错误。
• defer cancel() 确保在 main 函数返回时释放资源，即使请求提前完成。

7. 多层取消传播：并发 goroutine 的优雅关闭

场景：一个请求启动多个子任务，当任一任务失败或用户取消时，所有任务都应停止。

操作：共享同一个 ctx，每个子任务都监听 ctx.Done()。

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

    // 启动两个 goroutine
    go taskA(ctx)
    go taskB(ctx)

    // 模拟用户取消
    time.Sleep(500 * time.Millisecond)
    cancel() // 取消所有子任务

    time.Sleep(time.Second) // 等待 goroutine 退出
}

func taskA(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("taskA stopped:", ctx.Err())
            return
        default:
            // 模拟工作
            time.Sleep(100 * time.Millisecond)
        }
    }
}

func taskB(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("taskB stopped:", ctx.Err())
            return
        default:
            time.Sleep(50 * time.Millisecond)
        }
    }
}

输出（约 500ms 后）：

taskB stopped: context canceled
taskA stopped: context canceled

所有子 goroutine 同时收到取消信号，整齐退出。

8. 避免 context 泄漏的最佳实践

• 始终调用 cancel()：无论是 WithCancel、WithTimeout 还是 WithDeadline，返回的 CancelFunc 必须在不再需要 context 时被调用。通常使用 defer。
• 传递 context 时不要保存副本：尽量传递原始 ctx，而非复制后的新 context（WithValue 除外）。
• 不要在函数签名中省略 context：即使函数当前不需要取消，也应该接受 context 参数，以便将来扩展。
• 使用合适的 key 类型：WithValue 的 key 推荐定义为包级别的私有类型，避免与其他包冲突。
• 只在请求生命周期内使用 context：不要在后台长期运行的 goroutine 中传递旧的请求 context，应创建新的根 context。

总结：通过 context.WithCancel、WithTimeout、WithDeadline 和 WithValue 构建清晰的传递链，利用 Done() channel 和 CancelFunc 实现可传播的取消和超时机制，是 Go 并发编程中必不可少的基本功。