Go Context 完全指南

01Context 到底是什么

一句话：Context 是「一次请求的生命周期 + 取消信号 + 请求域数据」的载体，沿着调用链一路往下传

type Context interface {
    Deadline() (deadline time.Time, ok bool)
    Done() <-chan struct{}
    Err() error
    Value(key interface{}) interface{}
}

02Context 到底解决什么问题

在 Context 出现之前（Go 1.7 之前），这些问题每一个都很棘手

// ❌ 泄漏版：调用方超时返回后，这个 goroutine 还在跑，结果永远没人接收
func fetch() Result {
    ch := make(chan Result)
    go func() {
        r := slowOperation()  // 耗时 10s
        ch <- r                        // 没人接收 → 永久阻塞 → goroutine 泄漏
    }()
    select {
    case r := <-ch:
        return r
    case <-time.After(2 * time.Second):
        return Result{}   // 超时返回了，但 goroutine 还在跑
    }
}

// ✅ 正确版：ctx 被取消时，子 goroutine 能感知并退出
func fetch(ctx context.Context) Result {
    ch := make(chan Result, 1)  // ← 关键：缓冲区 1，即使没人收也不会阻塞
    go func() {
        ch <- slowOperation()
    }()
    select {
    case r := <-ch:
        return r
    case <-ctx.Done():          // ← 监听取消信号
        return Result{Err: ctx.Err()}
    }
}

03Context 接口四个方法详解

搞懂这四个方法，就搞懂了 Context 的全部对外能力

逐个拆解

// 标准用法：select 监听 Done
select {
case result := <-resultCh:
    // 正常拿到结果
    handle(result)
case <-ctx.Done():
    // 被取消或超时，立即退出
    return ctx.Err()
}

// 如果没设取消，Done() 返回 nil，此时这个 case 永远阻塞（相当于禁用该分支）
var bg = context.Background()
bg.Done()  // → nil（nil channel 上的接收操作永远阻塞）

// 区分取消原因，做不同处理
if err := ctx.Err(); err != nil {
    switch err {
    case context.Canceled:
        log.Println("用户主动取消，无需告警")       // 客户端断开，正常现象
    case context.DeadlineExceeded:
        log.Println("处理超时，需要告警")             // 系统慢了，要关注
    }
}

if dl, ok := ctx.Deadline(); ok {
    // 有截止时间：把它设到底层连接上
    conn.SetDeadline(dl)
    log.Printf("剩余时间: %v", time.Until(dl))
} else {
    // 无截止时间：Background/TODO 就是这种情况
    conn.SetDeadline(time.Time{})
}

traceID := ctx.Value("traceID")   // ⚠️ 不建议用字符串做 key，会冲突
traceID := ctx.Value(traceKey{})      // ✅ 用自定义类型做 key，类型安全

04四种构造方式与 Context 树

Background/TODO 是根，WithCancel/WithTimeout/WithValue 是派生——它们构成一棵树

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()   // ← 必须！即使超时已到，调用 cancel 也是无害且推荐的

Background vs TODO

// 已经确定要用根 ctx，却写 TODO
ctx := context.TODO()
// 静态检查工具会告警，且语义不清

// 明确的起点用 Background
ctx := context.Background()
// 不确定/待重构处用 TODO 做标记
ctx := context.TODO()  // TODO: 接入请求 ctx

两者功能完全相同（都是空的 root ctx），区别只在语义和意图：TODO 是给人和工具看的「这里还没想好」，便于后续检索补齐。

05取消传播机制

父取消 → 子全部取消；子取消 → 父不受影响。理解这一点就理解了 Context 的一半

package main

import (
    "context"
    "fmt"
    "time"
)

func main() {
    parent, parentCancel := context.WithCancel(context.Background())
    defer parentCancel()

    child, childCancel := context.WithCancel(parent)

    childCancel()  // 只取消子 Context

    fmt.Println("child  err:", child.Err())    // context.Canceled
    fmt.Println("parent err:", parent.Err())   // nil ← 父不受影响！

    // 反过来：取消父，子会跟着取消
    parent2, parent2Cancel := context.WithCancel(context.Background())
    child2, _ := context.WithCancel(parent2)
    parent2Cancel()

    fmt.Println("child2 err:", child2.Err())   // context.Canceled ← 被父级联取消
}
// 输出：
// child  err: context.Canceled
// parent err: <nil>
// child2 err: context.Canceled

// 整体请求 5s，但查缓存最多只允许 200ms
cacheCtx, cancel := context.WithTimeout(ctx, 200*time.Millisecond)
defer cancel()
if v, err := cache.Get(cacheCtx, key); err == nil {
    return v  // 命中缓存
}
// 缓存超时/未命中 → 继续走 DB，此时 ctx（父）依旧有效，没有被取消
return db.Query(ctx, sql)

06WithTimeout 与 WithDeadline

两者本质相同，只是一个给「多久之后」，一个给「什么时候」

ctx, cancel := context.WithTimeout(parent, 3*time.Second)
defer cancel()

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

parent, _ := context.WithTimeout(context.Background(), 3*time.Second)
child, _  := context.WithTimeout(parent, 10*time.Second)  // 设了 10s

dl, _ := child.Deadline()
fmt.Println(time.Until(dl))  // 约 3s，不是 10s！被父截断了

实战：带超时的 HTTP 请求

func fetchWithTimeout(url string) ([]byte, error) {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, err
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        // 超时时 err 会包装 context.DeadlineExceeded
        if errors.Is(err, context.DeadlineExceeded) {
            return nil, fmt.Errorf("请求 %s 超时: %w", url, err)
        }
        return nil, err
    }
    defer resp.Body.Close()

    return io.ReadAll(resp.Body)
}

超时不应层层叠加：这是 WithTimeout 的核心价值

// 每个函数自己 sleep/after
func A() { B(); C() }
func B() { wait(3*time.Second) }
func C() { wait(3*time.Second) }
// 实际最坏 6s，且无法整体控制

func A(ctx context.Context) {
    ctx, cancel := context.WithTimeout(ctx, 4*time.Second)
    defer cancel()
    B(ctx); C(ctx)
}
// B、C 共享同一个 deadline，总耗时 ≤ 4s
// B 用完 3s，C 就只剩 1s

07WithValue：请求域数据的正确用法

这是最容易被滥用的 API —— 用对了很优雅，用错了是灾难

// 把业务参数塞进 ctx
ctx = context.WithValue(ctx, "userID", 123)
ctx = context.WithValue(ctx, "pageSize", 20)
ctx = context.WithValue(ctx, "sortBy", "time")

func ListOrders(ctx context.Context) {
    // 必须靠猜才知道要传什么，编译期无检查
    size := ctx.Value("pageSize").(int)  // 可能 panic
}

// 只放贯穿链路的元数据
ctx = context.WithValue(ctx, traceKey{}, "abc-123")
ctx = context.WithValue(ctx, userKey{}, "u-88")

// 业务参数显式声明
func ListOrders(ctx context.Context, pageSize int, sortBy string) {
    // 签名即文档，编译期检查
}

// ✅ 推荐：定义不可导出的 key 类型 + 配套读写函数
package mypkg

type traceIDKey struct{}   // 空结构体，零内存分配，且类型唯一
type userKey struct{}

// 写入
func WithTraceID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, traceIDKey{}, id)
}

// 读取（类型安全，带 ok 判断）
func TraceIDFrom(ctx context.Context) (string, bool) {
    id, ok := ctx.Value(traceIDKey{}).(string)
    return id, ok
}

// 使用方
ctx := WithTraceID(parent, "req-abc-123")
if id, ok := TraceIDFrom(ctx); ok {
    log.Println("trace:", id)
}

root  := context.WithValue(context.Background(), k1, "v1")
child := context.WithValue(root, k2, "v2")

child.Value(k2)  // "v2"  自己就有
child.Value(k1)  // "v1"  向上找到父
root.Value(k2)   // nil   不会向下找！

traceID, _ := TraceIDFrom(ctx)   // ✅ 循环外取一次
for _, item := range items {
    log(traceID, item)
}

08源码实现原理

理解四种 Context 的具体实现，很多"为什么"就自然明白了

cancelCtx：取消机制的核心

// 简化版源码（Go 1.21+ 改用了 canceler 链表，但原理一致）
type cancelCtx struct {
    Context                              // 内嵌父 Context

    mu       sync.Mutex
    done     chan struct{}         // 懒创建，第一次 Done() 时才 make
    children map[canceler]struct{}   // ← 所有可取消的子节点
    err      error                 // 取消原因
}

func (c *cancelCtx) Done() <-chan struct{} {
    c.mu.Lock()
    if c.done == nil {
        c.done = make(chan struct{})
    }
    d := c.done
    c.mu.Unlock()
    return d
}

func (c *cancelCtx) cancel(removeFromParent bool, err error) {
    c.mu.Lock()
    if c.err != nil {                  // 幂等：已取消过就直接返回
        c.mu.Unlock()
        return
    }
    c.err = err                       // ③ 设置错误
    if c.done == nil {
        c.done = closedchan           // 复用一个已关闭的 channel
    } else {
        close(c.done)                 // ② 关闭 channel → 广播给所有监听者
    }
    for child := range c.children {   // ④ 递归取消所有子节点
        child.cancel(false, err)
    }
    c.children = nil

    if removeFromParent {             // ⑤ 从父节点摘除自己
        removeChild(c.Context, c)
    }
    c.mu.Unlock()
}

propagateCancel：把自己挂到父节点上

创建子 Context 时，Go 会调用 propagateCancel 决定「如何让自己能被父级取消」。这是理解 Context 树的关键函数：

func propagateCancel(parent Context, child canceler) {
    done := parent.Done()
    if done == nil {
        return   // ① 父不可取消（Background/TODO），无需挂靠
    }

    select {
    case <-done:
        // ② 父已经被取消了，立即取消自己
        child.cancel(false, parent.Err())
        return
    default:
    }

    // ③ 找到父链上最近的 *cancelCtx，把自己加入它的 children
    if p, ok := parentCancelCtx(parent); ok {
        p.mu.Lock()
        if p.err != nil {
            child.cancel(false, p.err)   // 检查竞态：父可能刚好被取消
        } else {
            if p.children == nil {
                p.children = make(map[canceler]struct{})
            }
            p.children[child] = struct{}
        }
        p.mu.Unlock()
        return
    }

    // ④ 父是自定义 Context 实现：起一个 goroutine 转发取消信号
    go func() {
        select {
        case <-parent.Done():
            child.cancel(false, parent.Err())
        case <-child.Done():
        }
    }()
}

timerCtx：超时就是「定时器 + 取消」

type timerCtx struct {
    *cancelCtx              // 内嵌，复用取消能力
    timer    *time.Timer    // 到点触发的定时器
    deadline time.Time      // 绝对截止时间
}

func (c *timerCtx) cancel(removeFromParent bool, err error) {
    c.cancelCtx.cancel(false, err)   // 复用 cancelCtx 的取消逻辑
    if removeFromParent {
        removeChild(c.cancelCtx.Context, c)
    }
    c.mu.Lock()
    if c.timer != nil {
        c.timer.Stop()                // ← 停掉定时器，防止泄漏
        c.timer = nil
    }
    c.mu.Unlock()
}

09常用实战代码模式

生产代码里最常见的六种 Context 用法

① HTTP Server：请求自带 Context

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()   // ← 每个请求都有，客户端断开时自动取消

    // 客户端断开连接时，ctx 会被取消
    select {
    case <-time.After(5 * time.Second):
        fmt.Fprintln(w, "处理完成")
    case <-ctx.Done():
        log.Println("客户端断开，停止处理:", ctx.Err())
        return
    }
}

// 服务端也可以统一设置超时（用中间件）
func timeoutMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
        defer cancel()
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

② 数据库查询：超时自动取消

// database/sql 的 *Context 系列方法都会接收 ctx
ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
defer cancel()

var user User
err := db.QueryRowContext(ctx,
    "SELECT id, name FROM users WHERE id = ?", userID).Scan(&user.ID, &user.Name)

if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        // 查询超时：连接会被自动归还，已执行的语句在服务端被 KILL
        return fmt.Errorf("查询用户超时")
    }
    return err
}

③ 超时重试：每次重试独立的超时预算

func callWithRetry(ctx context.Context, url string, maxRetry int) ([]byte, error) {
    var lastErr error
    for i := 0; i < maxRetry; i++ {
        // 每次重试单独 2s 超时，但都受外层 ctx 总预算约束
        attemptCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
        data, err := doRequest(attemptCtx, url)
        cancel()   // ← 循环内不能用 defer！立即调用

        if err == nil {
            return data, nil
        }
        lastErr = err

        // 外层已取消（总预算耗尽或用户放弃），不再重试
        if ctx.Err() != nil {
            return nil, ctx.Err()
        }

        // 退避等待，且等待过程也可被取消
        select {
        case <-time.After(time.Duration(i+1) * 500 * time.Millisecond):
        case <-ctx.Done():
            return nil, ctx.Err()
        }
    }
    return nil, lastErr
}

④ 控制后台 goroutine 的生命周期

// 启一个可被停止的后台任务
func startWorker(ctx context.Context) {
    go func() {
        ticker := time.NewTicker(1 * time.Second)
        defer ticker.Stop()

        for {
            select {
            case <-ticker.C:
                doWork()
            case <-ctx.Done():
                log.Println("worker 收到停止信号，退出")
                return   // ← 干净退出，goroutine 结束
            }
        }
    }()
}

// 使用：想停的时候调用 cancel
ctx, cancel := context.WithCancel(context.Background())
startWorker(ctx)
// ... 运行一段时间 ...
cancel()   // worker 优雅退出

⑤ 等待一组 goroutine（配合 errgroup）

import "golang.org/x/sync/errgroup"

func fetchAll(ctx context.Context, ids []string) ([]Item, error) {
    g, ctx := errgroup.WithContext(ctx)   // ← 任一子任务失败，ctx 自动取消
    items := make([]Item, len(ids))

    for i, id := range ids {
        i, id := i, id   // Go 1.22+ 不需要这行
        g.Go(func() error {
            item, err := fetchOne(ctx, id)   // 传入同一个 ctx
            if err != nil {
                return err
            }
            items[i] = item
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return nil, err   // 其他 goroutine 已因 ctx 取消而退出
    }
    return items, nil
}

errgroup.WithContext 返回的 ctx 在第一个子任务返回 error 时自动取消，其他并行任务会立即收到信号退出——这就是「快速失败」（fail-fast），避免一个失败还傻等其他的。

⑥ 链路追踪：traceID 贯穿全链路

// 中间件：入口处生成 traceID 注入 ctx
func traceMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        traceID := r.Header.Get("X-Trace-ID")
        if traceID == "" {
            traceID = generateID()
        }
        ctx := WithTraceID(r.Context(), traceID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// 任意深度的调用处都能取到，无需层层传参
func repository.Find(ctx context.Context, id int) {
    traceID, _ := TraceIDFrom(ctx)
    log.Printf("[trace=%s] 查询 id=%d", traceID, id)
    // 调用下游 RPC 时也把 ctx 传过去，traceID 就实现了跨服务串联
    rpc.Call(ctx, ...)
}

10最佳实践清单

这 8 条是 Go 官方和社区的共识，背下来能避开 90% 的坑

// ✅ 官方约定：ctx 是第一个参数，命名统一为 ctx
func DoSomething(ctx context.Context, arg Arg) error

// ❌ 不要放后面，不要改名
func DoSomething(arg Arg, ctx context.Context) error   // 不推荐

// ❌ 危险
doWork(nil, arg)      // panic: nil pointer dereference

// ✅ 不确定时用 TODO
doWork(context.TODO(), arg)

type Service struct {
    ctx context.Context  // 危险！
}
// 这个 Service 常驻内存，但 ctx 早就该结束了

type Service struct {
    db *sql.DB   // 只存真正的依赖
}
func (s *Service) Get(ctx context.Context, id int) {
    s.db.QueryContext(ctx, ...)
}

ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()     // ✅ 函数内：defer

// 循环内：显式立即调用（不能用 defer）
for i := 0; i < n; i++ {
    c, cancel := context.WithTimeout(ctx, time.Second)
    use(c)
    cancel()      // ✅ 立即
}

// ❌ 信号断裂
func handler(w, r) {
    ctx := context.Background()   // 丢弃了 r.Context()
    db.QueryContext(ctx, ...)
}

// ✅ 原样传递
func handler(w, r) {
    db.QueryContext(r.Context(), ...)
}

11常见陷阱与错误

这些错误在生产环境都真实发生过，每一个的代价都不小

// ❌ 错误：用了请求 ctx，请求结束任务就被取消
go sendNotification(r.Context(), msg)

// ✅ 正确：异步任务用新 ctx，自带超时，脱离请求生命周期
go func() {
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    sendNotification(ctx, msg)
}()

12常见问题

点击展开