1
2
3
4
5
6
7
8
9

// 没有 context 的世界，每个函数都要加一堆参数
func QueryUser(userID string, cancel chan struct{}, deadline time.Time, requestID string) {
    // 参数列表长得让人窒息
}

// 有 context 的世界，一切都很优雅
func QueryUser(ctx context.Context, userID string) {
    // 简洁、清晰、可组合
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

type Context interface {
    // Deadline 返回这个 Context 的截止时间
    // 如果没有设置截止时间，ok 返回 false
    Deadline() (deadline time.Time, ok bool)

    // Done 返回一个关闭的频道，当 Context 被取消时会关闭
    // 如果这个 Context 永远不会被取消，返回 nil
    Done() <-chan struct{}

    // Err 返回 Context 被取消的原因
    // 如果 Done() 还没关闭，返回 nil
    Err() error

    // Value 返回这个 Context 中存储的值
    // 如果没有这个值，返回 nil
    Value(key any) any
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

func main() {
    // context.Background() 返回一个 nil 错误的 Context
    // 它是整个 Context 树的根，通常作为请求的入口点
    ctx := context.Background()

    fmt.Println("Context:", ctx)
    fmt.Println("Deadline:", ctx.Deadline())
    // 输出: Deadline: 0001-01-01 00:00:00 +0000 UTC, false
    fmt.Println("Done 通道:", ctx.Done())  // 输出: nil（永远不会被取消）
    fmt.Println("Err:", ctx.Err())  // 输出: nil
}

1
2
3
4
5
6
7
8

func main() {
    // TODO 和 Background 在功能上几乎一样
    // 但语义不同：TODO 表示"将来会替换成合适的 Context"
    ctx := context.TODO()

    fmt.Println("Context:", ctx)
    fmt.Println("Done 通道:", ctx.Done())
}

1
2
3
4
5
6
7
8

// 假设这个函数还没确定如何获取 Context
func processData(data string) error {
    // 这里还不知道该用 Background 还是从参数传入
    // 所以先用 TODO 占位，后续重构时会改成正确的 Context
    ctx := context.TODO()

    return fetchFromDB(ctx, data)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

func main() {
    // 从 Background 创建可取消 Context
    ctx, cancel := context.WithCancel(context.Background())

    // 在另一个 goroutine 中模拟工作
    go func() {
        for {
            select {
            case <-ctx.Done():
                fmt.Println("工作被取消，退出")
                return
            default:
                fmt.Println("工作中...")
                time.Sleep(500 * time.Millisecond)
            }
        }
    }()

    // 主函数等待 2 秒后取消
    time.Sleep(2 * time.Second)
    fmt.Println("调用取消函数")
    cancel()

    // 等待一下让 goroutine 收到信号
    time.Sleep(500 * time.Millisecond)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

func main() {
    // 创建一个 3 秒后截止的 Context
    deadline := time.Now().Add(3 * time.Second)
    ctx, cancel := context.WithDeadline(context.Background(), deadline)
    defer cancel()  // 别忘了清理资源

    fmt.Printf("当前时间: %v\n", time.Now().Format("15:04:05.000"))
    fmt.Printf("截止时间: %v\n", deadline.Format("15:04:05.000"))

    i := 0
    for {
        i++
        select {
        case <-ctx.Done():
            fmt.Printf("Context 已取消: %v（第 %d 次循环后）\n", ctx.Err(), i)
            return
        default:
            fmt.Printf("执行任务 %d...\n", i)
            time.Sleep(1 * time.Second)
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

func main() {
    // 创建一个 5 秒超时的 Context
    // WithTimeout(parent, duration) 等价于 WithDeadline(parent, time.Now().Add(duration))
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    fmt.Println("超时 Context 已创建，5 秒后将自动取消")

    for {
        select {
        case <-ctx.Done():
            fmt.Printf("超时触发: %v\n", ctx.Err())
            return
        default:
            fmt.Println("处理中...")
            time.Sleep(1 * time.Second)
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// HTTP 服务中设置请求超时
func handler(w http.ResponseWriter, r *http.Request) {
    // 创建 10 秒超时的 Context
    ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
    defer cancel()

    // 将 Context 传递给实际处理逻辑
    result, err := doHeavyWork(ctx)
    if err != nil {
        http.Error(w, err.Error(), 500)
        return
    }

    w.Write(result)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

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

    go func() {
        // 模拟一个操作失败
        time.Sleep(2 * time.Second)
        // 传递具体的取消原因
        cancel(errors.New("数据库连接失败：connection refused"))
    }()

    <-ctx.Done()

    // Cause() 返回传递给 cancel 的具体错误
    fmt.Printf("取消原因: %v\n", context.Cause(ctx))
}

1
2
3
4
5
6
7
8
9

// WithCancel：只能知道「被取消了」，不知道为什么
ctx1, cancel1 := context.WithCancel(context.Background())
// ...
cancel1()  // 只能取消，无法传递原因

// WithCancelCause：不仅能取消，还能传递一个错误作为原因
ctx2, cancel2 := context.WithCancelCause(context.Background())
// ...
cancel2(errors.New("操作失败的具体原因"))  // 取消并附带原因

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// 定义一个非导出的 key 类型（这是最佳实践，后面会详细讲）
type requestIDKey struct{}

func main() {
    ctx := context.Background()

    // 存储请求 ID
    ctx = context.WithValue(ctx, requestIDKey{}, "req-12345")

    // 在子 Context 中存储用户 ID
    childCtx := context.WithValue(ctx, "userID", 10086)

    // 读取值
    reqID := childCtx.Value(requestIDKey{})
    userID := childCtx.Value("userID")

    fmt.Printf("请求 ID: %v\n", reqID)
    fmt.Printf("用户 ID: %v\n", userID)

    // 从父 Context 也能读取到值
    fmt.Printf("从父 Context 读取请求 ID: %v\n", ctx.Value(requestIDKey{}))
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

func simulateTask(ctx context.Context, name string) {
    for {
        select {
        case <-ctx.Done():
            fmt.Printf("[%s] 收到取消信号，退出: %v\n", name, ctx.Err())
            return
        default:
            fmt.Printf("[%s] 工作中...\n", name)
            time.Sleep(500 * time.Millisecond)
        }
    }
}

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

    go simulateTask(ctx, "任务A")
    go simulateTask(ctx, "任务B")

    <-ctx.Done()
    fmt.Printf("主流程结束: %v\n", ctx.Err())
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

func main() {
    // 测试主动取消
    ctx1, cancel1 := context.WithCancel(context.Background())
    cancel1()
    fmt.Printf("主动取消: %v\n", ctx1.Err())
    // 输出: 主动取消: context canceled

    // 测试超时取消
    ctx2, cancel2 := context.WithTimeout(context.Background(), 1*time.Millisecond)
    defer cancel2()
    time.Sleep(10 * time.Millisecond)
    fmt.Printf("超时取消: %v\n", ctx2.Err())
    // 输出: 超时取消: context deadline exceeded

    // 未取消的 Context
    ctx3 := context.Background()
    fmt.Printf("未取消: %v\n", ctx3.Err())
    // 输出: 未取消: <nil>
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

func main() {
    // 无截止时间的 Context
    ctx1 := context.Background()
    deadline, ok := ctx1.Deadline()
    fmt.Printf("Background - 截止时间: %v, 已设置: %v\n", deadline, ok)
    // 输出: Background - 截止时间: 0001-01-01 00:00:00 +0000 UTC, 已设置: false

    // 有截止时间的 Context
    ctx2, _ := context.WithDeadline(context.Background(), time.Now().Add(5*time.Second))
    deadline, ok = ctx2.Deadline()
    fmt.Printf("WithDeadline - 截止时间: %v, 已设置: %v\n", deadline.Format(time.RFC3339), ok)
    // 输出: WithDeadline - 截止时间: 2024-01-15T10:30:00+08:00, 已设置: true
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

func main() {
    // 构建一个 Context 链
    level1 := context.WithValue(context.Background(), "level", 1)
    level2 := context.WithValue(level1, "level", 2)
    level3 := context.WithValue(level2, "level", 3)

    // 当前 Context 有值，直接返回
    fmt.Printf("level3.Value('level') = %v\n", level3.Value("level"))
    // 输出: 3

    // 当前 Context 没有，往上找
    fmt.Printf("level3.Value('name') = %v\n", level3.Value("name"))
    // 输出: <nil>

    // 从父节点查找
    fmt.Printf("level2.Value('level') = %v\n", level2.Value("level"))
    // 输出: 1
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

func worker(ctx context.Context, name string) {
    for {
        select {
        case <-ctx.Done():
            fmt.Printf("[%s] 被取消了: %v\n", name, ctx.Err())
            return
        default:
            fmt.Printf("[%s] 工作中...\n", name)
            time.Sleep(300 * time.Millisecond)
        }
    }
}

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

    // 创建两个子 Context
    ctx1, _ := context.WithCancel(ctx)
    ctx2, _ := context.WithCancel(ctx)

    // 启动多个 worker
    go worker(ctx1, "Worker-A")
    go worker(ctx2, "Worker-B")
    go worker(ctx, "Worker-Main")

    // 等待 Context 取消
    <-ctx.Done()
    fmt.Println("父 Context 已超时，所有子 Context 都会被取消")
    time.Sleep(1 * time.Second)
}

1
2
3
4
5
6
7

// package A
ctx := context.WithValue(ctx, "requestID", "123")

// package B（假设也用了 "requestID" 作为 key）
// 在 package A 的 Context 上调用 package B 的方法
// B 也想通过 "requestID" 存自己的值
ctx2 := context.WithValue(ctx, "requestID", "456") // 覆盖了 A 的值！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// 在你的包里定义一个非导出的 key 类型
type contextKey string

// 或者更推荐：使用 struct{} 作为 key，定义多个常量
type key int

const (
    requestIDKey key = iota
    userIDKey
    traceIDKey
)

// 使用时
ctx := context.WithValue(ctx, requestIDKey, "req-123")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

package mypkg

// 定义非导出的 key 类型
type contextKey string

// 定义包级别的 key 常量
const (
    requestIDKey contextKey = "request-id"
    userIDKey    contextKey = "user-id"
)

// GetRequestID 安全地获取请求 ID
func GetRequestID(ctx context.Context) string {
    if v := ctx.Value(requestIDKey); v != nil {
        return v.(string)
    }
    return ""
}

// WithRequestID 存储请求 ID
func WithRequestID(ctx context.Context, requestID string) context.Context {
    return context.WithValue(ctx, requestIDKey, requestID)
}

1
2
3
4
5
6
7
8

// 错误的做法
func fetchUser(ctx context.Context, id int) (*User, error) {
    // 错误：把 userID 当作可选参数存在 Context 里
    if userID := ctx.Value("currentUserID"); userID != nil {
        fmt.Printf("操作者: %v\n", userID)
    }
    return db.QueryUser(id)
}

1
2
3
4
5

// 正确的做法
func fetchUser(ctx context.Context, id int, operatorID string) (*User, error) {
    fmt.Printf("操作者: %s\n", operatorID)  // 明确传递，类型安全
    return db.QueryUser(ctx, id)
}

1
2
3
4
5
6

// 正确的使用场景
ctx := context.WithValue(ctx, requestIDKey, "req-123")
ctx = context.WithValue(ctx, traceIDKey, "trace-abc")

// 日志、监控、数据库等基础设施可以自动从 Context 读取
log.Info("处理请求", "requestID", ctx.Value(requestIDKey))

1
2
3
4
5
6
7
8
9

// ✅ 正确：Context 作为第一个参数
func FetchUser(ctx context.Context, userID int) (*User, error) {
    // ...
}

// ❌ 错误：Context 作为最后一个参数
func FetchUser(userID int, ctx context.Context) (*User, error) {
    // ...
}

1
2
3
4
5
6
7
8
9

func main() {
    ctx := context.Background()

    // ❌ 错误：每个函数都传 Context，即使它不需要
    result := process(ctx, data)

    // ✅ 正确：只在需要取消信号、截止时间或元数据时传递
    result = processWithTimeout(ctx, data)
}

1
2
3
4
5
6

// ❌ 错误
func Query(ctx context.Context, id int, trace bool) { ... }

// ✅ 正确
func Query(ctx context.Context, id int) { ... }
func QueryWithTrace(ctx context.Context, id int, traceID string) { ... }

1
2
3
4
5
6

func handler(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
    defer cancel()  // 防止资源泄漏

    // 使用 ctx 处理请求
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

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

    // 从 Context 中提取数据
    requestID := ctx.Value("requestID")
    fmt.Printf("处理请求: %v\n", requestID)

    select {
    case <-time.After(5 * time.Second):
        w.Write([]byte("OK"))
    case <-ctx.Done():
        fmt.Printf("请求被取消: %v\n", ctx.Err())
    }
}

func main() {
    http.HandleFunc("/", handleRequest)
    http.ListenAndServe(":8080", nil)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

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

    // QueryContext 支持 Context 参数
    rows, err := db.QueryContext(ctx, "SELECT * FROM users WHERE id = ?", 1)
    if err != nil {
        if err == context.DeadlineExceeded {
            fmt.Println("查询超时！")
        }
        return
    }
    defer rows.Close()

    // 处理结果
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

func runCommandWithTimeout() {
    ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
    defer cancel()

    // CommandContext 会在 Context 取消时杀死进程
    cmd := exec.CommandContext(ctx, "ping", "-n", "10", "localhost")
    output, err := cmd.CombinedOutput()

    if err != nil {
        if ctx.Err() == context.DeadlineExceeded {
            fmt.Println("命令执行超时！")
        }
        return
    }

    fmt.Printf("输出: %s\n", output)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

func longRunningTask(ctx context.Context) error {
    for i := 0; i < 100; i++ {
        // 每一步都检查 Context 是否被取消
        select {
        case <-ctx.Done():
            return ctx.Err()  // 快速退出，释放资源
        default:
            // 继续执行
        }

        // 执行一些工作
        fmt.Printf("执行第 %d 步...\n", i)
        time.Sleep(200 * time.Millisecond)
    }
    return nil
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

package main

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

type contextKey string

const requestIDKey contextKey = "request-id"

func middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 生成请求 ID 并存入 Context
        requestID := fmt.Sprintf("req-%d", time.Now().UnixNano())
        ctx := context.WithValue(r.Context(), requestIDKey, requestID)

        w.Header().Set("X-Request-ID", requestID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    // 模拟处理逻辑，定期检查取消
    for i := 0; i < 5; i++ {
        select {
        case <-ctx.Done():
            fmt.Printf("请求被取消: %v\n", ctx.Err())
            return
        case <-time.After(1 * time.Second):
            fmt.Printf("[%s] 处理中...\n", ctx.Value(requestIDKey))
        }
    }

    w.Write([]byte("处理完成"))
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", handler)

    server := &http.Server{
        Addr:    ":8080",
        Handler: middleware(mux),
    }

    fmt.Println("服务器启动在 :8080")
    server.ListenAndServe()
}