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
// 解决方案：使用 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
}

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
}

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 }

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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

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

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

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

8
func (ctx context.Context) GetUserID() 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{}{}

1
// 错误用法：
2
// 1. 传递可选参数（用函数选项模式）
3
// 2. 传递依赖注入（用 DI 容器）
4
// 3. 传递日志记录器（用结构化日志库）
5

6
// 正确用法：
7
// 1. 请求作用域的追踪 ID
8
// 2. 请求作用域的用户信息
9
// 3. 取消信号

1
// Context 的 Value 方法是并发安全的
2
// 多个 goroutine 可以同时读取

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
}

1
// 过长：失去控制作用
2
ctx, _ := context.WithTimeout(ctx, 24*time.Hour)
3

4
// 过短：还没完成就超时
5
ctx, _ := context.WithTimeout(ctx, 1*time.Millisecond)
6

7
// 合理：根据操作预估时间
8
ctx, _ := context.WithTimeout(ctx, 30*time.Second)

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
}

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
}

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
}

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
}

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

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
}
10

11
func (c *cancelCtx) cancel(removeFromParent bool, err error) {
12
    c.mu.Lock()
13
    if c.err != nil {
14
        c.mu.Unlock()
15
        return  // 已经取消过
16
    }
17
    c.err = err
18
    d, _ := c.done.Load().(chan struct{})
19
    if d == nil {
20
        c.done.Store(make(chan struct{}))
21
    } else {
22
        close(d)  // 关闭 Done 通道
23
    }
24

25
    // 递归取消子节点
26
    for child := range c.children {
27
        child.cancel(false, err)
28
    }
29
    c.children = nil
30
    c.mu.Unlock()
31
}