Go context 深入：取消传播、超时与截止时间、值传递与上下文树

type Context interface {
    // Deadline 返回该 context 的截止时间；若无截止时间则 ok 为 false
    Deadline() (deadline time.Time, ok bool)

    // Done 返回一个 channel，context 被取消或超时时会被关闭
    Done() <-chan struct{}

    // Err 说明 Done channel 为何被关闭：
    //   返回 Canceled（手动取消）或 DeadlineExceeded（超时）
    Err() error

    // Value 返回与该 key 关联的值；无关联时返回 nil
    Value(key any) any
}

// 根 context：不会被取消、没有截止时间、不携带任何值
ctx := context.Background()

// 适用于还不知道该用什么 context 的起点，或测试
ctx := context.TODO()

// 可取消：手动调用 cancel() 触发 Done 关闭
ctx, cancel := context.WithCancel(parent)

// 带超时：到达 deadline 后自动取消
ctx, cancel := context.WithTimeout(parent, 3*time.Second)

// 带截止时间：在绝对时间点自动取消
ctx, cancel := context.WithDeadline(parent, time.Now().Add(3*time.Second))

// 带值：携带一个 key-value
ctx := context.WithValue(parent, traceKey, traceID)

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel() // 兜底：确保所有派生 goroutine 最终都能退出

    // 派生的 goroutine 监听 ctx.Done()
    go worker(ctx, "worker-A")
    go worker(ctx, "worker-B")

    // 模拟 5 秒后主动取消
    time.Sleep(5 * time.Second)
    cancel()
    // 此时 worker-A、worker-B 以及它们再派生的 goroutine 全部收到信号
}

func worker(ctx context.Context, name string) {
    child, _ := context.WithCancel(ctx) // 再次派生：形成取消树
    go childWorker(child, name+"-sub")

    select {
    case <-ctx.Done():
        log.Printf("%s 被取消", name)
    case <-time.After(30 * time.Second):
        log.Printf("%s 完成任务", name)
    }
}

func childWorker(ctx context.Context, name string) {
    <-ctx.Done() // 父取消会自动传导到这里
    log.Printf("%s 收尾清理", name)
}

ctx, cancel := context.WithCancel(parent)

// 什么时候调用 cancel？三个铁律：
// 1. 尽早 defer cancel()，保证任何返回路径都会执行
// 2. 手动触发时只能调用一次（重复调用是安全的，幂等）
// 3. 每个 WithCancel 派生的 cancel 都要调用，否则父 context 的
//    children 列表会残留子节点，造成内存与计算泄漏

func fetchWithContext(ctx context.Context) error {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel() // 无论 fetch 成功还是失败，都会触发取消
    return fetch(ctx)
}

// WithTimeout：相对时长，从创建时刻开始计时
ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()

// WithDeadline：绝对时刻，适合"整个请求必须在 X 时刻前完成"
deadline := time.Now().Add(3 * time.Second)
ctx, cancel := context.WithDeadline(ctx, deadline)
defer cancel()

func queryUser(ctx context.Context, id int) (*User, error) {
    // 若父 context 已带超时，这里再叠加一个更短的超时
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()

    row := db.QueryRowContext(ctx, "SELECT name FROM users WHERE id = ?", id)

    var u User
    if err := row.Scan(&u); err != nil {
        if ctx.Err() == context.DeadlineExceeded {
            return nil, fmt.Errorf("query user %d timeout", id)
        }
        return nil, err
    }
    return &u, nil
}

func handle(ctx context.Context) error {
    select {
    case <-ctx.Done():
        switch ctx.Err() {
        case context.Canceled:
            // 手动取消：通常是更上层的请求被放弃
            return errors.New("request canceled")
        case context.DeadlineExceeded:
            // 超时：需要告诉调用方"我慢了"，触发重试或降级
            return errors.New("deadline exceeded")
        }
    default:
        // 正常执行
    }
    return nil
}

type traceIDKey struct{} // 使用私有类型作为 key，避免字符串 key 冲突

ctx := context.WithValue(ctx, traceIDKey{}, "trace-abc-123")

// 任意深度读取
func readTraceID(ctx context.Context) (string, bool) {
    v, ok := ctx.Value(traceIDKey{}).(string)
    return v, ok
}

1. 不要用内置类型（string、int）直接做 key —— 不同包容易冲突
2. key 必须使用包级私有类型（如 type traceIDKey struct{}），包外无法构造
3. 只传"请求级"数据：traceID、userID、租户 ID、语言偏好
4. 绝不传可变状态、绝不传用于业务逻辑控制的参数 —— 那会隐藏依赖

ctx := context.Background()
ctx = context.WithValue(ctx, keyA, "a")
ctx = context.WithValue(ctx, keyB, "b") // 新节点包住旧节点

// ctx.Value(keyA) 会从最外层向内层回溯，找到 keyA 就返回
// 因此"同 key 重复 WithValue"时，内层覆盖外层，且每次查找 O(深度)

func HandleRequest(w http.ResponseWriter, r *http.Request) {
    // 入口：从请求派生，全局贯穿
    ctx := r.Context()

    // 分支1：带值（traceID 等）供全链路日志使用
    ctx = context.WithValue(ctx, traceIDKey{}, r.Header.Get("X-Trace-ID"))

    // 分支2：整体超时，控制整个请求生命周期
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    // 分支3：调用下游，叠加更短的超时
    resp, err := callDownstream(ctx, r.URL.Path)
    if err != nil {
        http.Error(w, "upstream error", http.StatusBadGateway)
        return
    }
    _ = resp
}

func mergeDone(ctxA, ctxB context.Context) <-chan struct{} {
    merged := make(chan struct{})
    go func() {
        defer close(merged)
        select {
        case <-ctxA.Done():
        case <-ctxB.Done():
        }
    }()
    return merged
}

// 场景：一个 goroutine 同时受"请求取消"和"服务关停"两个信号控制
stop := mergeDone(ctx.Done(), appShutdownCh)
<-stop // 任意一个触发，都会继续

// 凡是做 IO 或启动 goroutine 的函数，第一个参数都应是 ctx
type Repository interface {
    GetUser(ctx context.Context, id int) (*User, error)
}

// 存储 goroutine 的调用，保证可取消
func StartPolling(ctx context.Context) {
    ticker := time.NewTicker(time.Second)
    defer ticker.Stop()
    for {
        select {
        case <-ctx.Done():
            return // 取消即退出，绝不泄漏
        case <-ticker.C:
            doPoll()
        }
    }
}