Go 1.20 context 取消原因入门：让并发任务知道为什么停下

取消任务时，只知道 canceled 有时不够

context.Context 是 Go 并发和服务端代码里非常核心的工具。它可以传递超时、取消信号和请求范围数据。以前我们通常通过 ctx.Err() 判断 context 为什么结束，常见结果是 context.Canceled 或 context.DeadlineExceeded。这对很多场景已经够用，但在复杂任务里，有时你还想知道更具体的原因。

比如一个批处理任务启动了多个 worker，其中一个 worker 发现配置错误，于是取消整个任务。下游只看到 context canceled，排查时还要翻日志找第一个失败点。Go 1.20 提供了取消原因：取消时附带一个错误，之后可以用 context.Cause(ctx) 读取。

这篇文章讲普通取消、带原因取消，以及在 worker 场景中的用法。

普通取消复习

ctx, cancel := context.WithCancel(context.Background())

go func() {
	<-ctx.Done()
	fmt.Println(ctx.Err())
}()

cancel()

输出：

context canceled

超时：

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

select {
case <-time.After(3 * time.Second):
	fmt.Println("done")
case <-ctx.Done():
	fmt.Println(ctx.Err())
}

输出通常是：

context deadline exceeded

在 HTTP handler 里，你应该把 r.Context() 传给下游：

user, err := service.GetUser(r.Context(), id)

这样客户端断开或请求超时时，下游数据库查询、HTTP 调用和业务任务都有机会停止。

WithCancelCause

带原因取消：

ctx, cancel := context.WithCancelCause(context.Background())

cancel(fmt.Errorf("config file is invalid"))

<-ctx.Done()
fmt.Println(ctx.Err())
fmt.Println(context.Cause(ctx))

ctx.Err() 仍然是通用的 context canceled，context.Cause(ctx) 会返回你传入的具体错误。这样既兼容原有 context 使用方式，也能给需要更多信息的地方提供原因。

一个任务函数：

func runTask(ctx context.Context) error {
	select {
	case <-time.After(5 * time.Second):
		return nil
	case <-ctx.Done():
		return fmt.Errorf("task stopped: %w", context.Cause(ctx))
	}
}

如果取消原因是 config file is invalid，返回错误就会带上这个上下文。

在 worker 组里使用

type Job struct {
	ID int64
}

func processJob(ctx context.Context, job Job) error {
	select {
	case <-time.After(100 * time.Millisecond):
		if job.ID == 3 {
			return fmt.Errorf("job data is broken")
		}
		return nil
	case <-ctx.Done():
		return context.Cause(ctx)
	}
}

运行多个任务：

func RunJobs(parent context.Context, jobs []Job) error {
	ctx, cancel := context.WithCancelCause(parent)
	defer cancel(nil)

	errCh := make(chan error, len(jobs))
	var wg sync.WaitGroup

	for _, job := range jobs {
		job := job
		wg.Add(1)
		go func() {
			defer wg.Done()
			if err := processJob(ctx, job); err != nil {
				cancel(fmt.Errorf("job %d failed: %w", job.ID, err))
				errCh <- err
			}
		}()
	}

	wg.Wait()
	close(errCh)

	if cause := context.Cause(ctx); cause != nil {
		return cause
	}
	return nil
}

第一个失败的 job 会取消整个 context，并记录失败原因。其他 worker 感知到取消后可以尽快退出。

这个示例为了入门保持简单。真实项目里你可能还要收集多个错误、限制并发数量、区分可重试错误和不可重试错误。

不要把 cause 当业务数据通道

取消原因应该是“为什么停止”的错误，不应该塞入大量业务数据。比如不要把完整用户对象、请求体或配置内容放进 cause。context 的职责仍然是取消和超时传播，不是替代函数参数。

好的原因：

cancel(fmt.Errorf("job %d failed: %w", job.ID, err))

不好的原因：

cancel(fmt.Errorf("full request body: %s", body))

后者可能泄露敏感信息，也让日志变得混乱。

测试取消原因

取消逻辑也可以写测试。不要只在真实服务里按 Ctrl+C 观察日志。

func TestRunTaskCanceledWithCause(t *testing.T) {
	ctx, cancel := context.WithCancelCause(context.Background())
	cancel(fmt.Errorf("manual stop"))

	err := runTask(ctx)
	if err == nil {
		t.Fatal("expected error")
	}
	if !strings.Contains(err.Error(), "manual stop") {
		t.Fatalf("error = %v, want manual stop", err)
	}
}

如果你希望程序能用 errors.Is 判断原因，可以定义哨兵错误：

var ErrManualStop = errors.New("manual stop")

func TestCauseIsPreserved(t *testing.T) {
	ctx, cancel := context.WithCancelCause(context.Background())
	cancel(ErrManualStop)

	if !errors.Is(context.Cause(ctx), ErrManualStop) {
		t.Fatalf("cause = %v", context.Cause(ctx))
	}
}

测试的重点是确认取消原因没有在封装过程中丢失。并发代码一旦变复杂，只有日志很难证明行为稳定，单元测试能把关键语义固定下来。

context.Cause vs ctx.Err()

ctx.Err() 兼容旧代码，不会变。新增代码可以用 Cause 获取更丰富信息，但不要破坏已有接口契约。

与 context.WithTimeoutCause

Go 1.20 还新增了 WithTimeoutCause 和 WithDeadlineCause：

ctx, cancel := context.WithTimeoutCause(
	context.Background(),
	5*time.Second,
	fmt.Errorf("database query exceeded 5s"),
)
defer cancel()

超时后 context.Cause(ctx) 返回你指定的错误，而不是泛化的 context.DeadlineExceeded。

常见问题 FAQ

Q: 旧版本 Go 能用 Cause 吗？
A: context.Cause 是 Go 1.20 新增。旧版本需要升级。如果暂时不能升级，可以用自定义 channel + error 实现类似机制。

Q: Cause 的错误需要稳定吗？
A: 不建议用 Cause 做业务判断依据。它更适合日志和排查。如需要业务层面的错误识别，定义 sentinel error 并用 errors.Is 判断。

Q: Cause 错误会传递到所有子 context 吗？
A: Cause 顺着取消链向上找。但如果中间新 context 覆盖了原因，上层的 Cause 可能是中间层的原因。

常见陷阱

1. Cause 里塞太多信息：错误太长会增加日志负担、传播延迟，也可能泄露内部细节。
2. 把 Cause 当业务参数：context 不是函数参数替代品，不要把复杂数据塞进 cause。
3. 忽略兼容性：调用库代码时，对方可能不认识 cause。公共 API 的设计要考虑旧版本兼容。

小结

Go 1.20 的取消原因让 context 更容易排查。context.WithCancelCause 可以在取消时附带错误，context.Cause 可以读取具体原因。WithTimeoutCause 让超时场景也能携带自定义原因。它适合 worker 组、批处理、服务关闭和复杂请求链路。

使用时保持克制：context 仍然负责取消，不负责传业务数据。把原因写得短小、明确、可排查，就能让并发代码停止得更有解释力。普及 Cause 的最佳实践是从关键 worker 链路开始，逐步养成用明确原因替代模糊 Canceled 的习惯。

网络请求链中的传递

在微服务调用链中，context cause 可以帮助下游服务理解取消原因：

func CallService(ctx context.Context, url string) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return err
    }
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return fmt.Errorf("call %s: %w", url, err)
    }
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("status %d", resp.StatusCode)
    }
    return nil
}

上游 context 超时时，Cause 会告诉你是哪个环节触发的取消。

对比表：带 Cause vs 不带 Cause

WithCancelCause 只是多传了一个参数，排查价值却大得多。新项目推荐使用。

调试技巧

打印 context 链路中的 cause：

func logCause(ctx context.Context, msg string) {
    if cause := context.Cause(ctx); cause != nil {
        log.Printf("%s: cause=%v", msg, cause)
    }
}

在关键节点加入这类日志，能显著缩短线上排查时间。

超时链路的具体排查

在超时链路上，Cause 能帮你定位是第一层超还是第二层超时：

func Level1(ctx context.Context) {
    ctx2, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    if err := Level2(ctx2); err != nil {
        log.Printf("level1 failed: %v, cause=%v", err, context.Cause(ctx2))
    }
}

func Level2(ctx context.Context) {
    ctx3, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()
    if err := Level3(ctx3); err != nil {
        log.Printf("level2 failed: %v, cause=%v", err, context.Cause(ctx3))
    }
}

日志输出：

level2 failed: timeout, cause=timeout after 3s
level1 failed: timeout, cause=timeout after 3s

可以看出是 Level3 导致了 Level2 超时，而非外部传入的 5 秒超时触发的。

Context 链路的命名约定

cacheCtx, cancel := context.WithTimeoutCause(ctx, 100*time.Millisecond,
    fmt.Errorf("cache timeout"))
defer cancel()

dbCtx, cancel := context.WithTimeoutCause(ctx, 500*time.Millisecond,
    fmt.Errorf("db timeout"))
defer cancel()

每层都赋予有意义的名字，排查时一目了然：是缓存慢还是数据库慢。

避免 Root Cause 丢失

如果用 fmt.Errorf("wrapped: %w", cause) 包装后再取消，root cause 仍然在错误链中保留。context.Cause 返回的是你传给 cancel 的错误本身，不会自动展开 error chain 到最底层。需要时在日志中同时输出 cause 和 cause error chain。

总结

Context Cause 的核心价值是从模糊的"context canceled"进化到具体的"database query exceeded 500ms"。这不仅方便排查，还能支撑更精细的告警和自动化处理。例如可以将 cause 中的超时错误统一归类为一种告警，将用户取消归类为另一种，避免它们混在一起难以区分。这种可观测性的提升，不需要引入复杂的中间件，只需要在使用 context 时多传一个参数。对于线上系统，这是性价比极高的改进。

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

• 函数是否处理了所有 error 返回值
• 并发代码是否有明确的退出路径和 WaitGroup
• 用户输入是否经过校验和清洗
• 敏感配置是否通过环境变量或加密存储注入
• 测试是否覆盖了正常路径和至少一个错误路径
• 日志是否包含足够的上下文信息但不泄露敏感数据
• 接口设计是否符合最小接口原则

CI/CD 集成建议

• 每次提交前运行 go fmt ./...
• CI 中运行 go vet ./... 和 golangci-lint run
• 单元测试使用 go test -race ./... 检测数据竞争
• 关键路径的 benchmark 加入回归测试
• 使用 go mod verify 确保依赖完整性

性能调优检查点

• 使用 pprof 分析 CPU 和内存使用
• 关注 benchmark 的 allocs/op，减少高频路径的堆分配
• 检查数据库查询是否使用索引
• 确认外部 HTTP 调用有合理的超时设置
• 缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

1. goroutine 和线程的区别
2. channel 的缓冲和非缓冲用法
3. defer 的执行顺序和与返回值的关系
4. map 的并发不安全性和解决方案
5. interface 的隐式实现和类型断言
6. slice 的底层数组和 append 机制
7. GC 的基本原理和调优参数
8. context 的使用场景和超时控制
9. error 的包装和 errors.Is/errors.As
10. sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

1. 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
2. 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
3. 不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
4. 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
5. 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
6. 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

1. 把文中所有示例代码在自己的机器上跑一遍
2. 给示例代码补充错误分支的测试用例
3. 尝试基于本文内容构建一个小型完整项目
4. 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
5. 订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

• Go 官方网站：https://go.dev/
• Go 标准库文档：https://pkg.go.dev/std
• Go by Example：https://gobyexample.com/
• Effective Go：https://go.dev/doc/effective_go
• Go 常见问题：https://go.dev/doc/faq
• Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

在 gRPC 和微服务中使用 Cause

在微服务调用链中，context cause 可以逐层传递，让最终调用方了解根因。比如上游服务设置了全局 timeout，下游服务在查询数据库时再次设置一个更短的 timeout。如果数据库查询超时，下游会生成一个"db timeout"的 cause，上游收到后是"context deadline exceeded"的包装错误。查看 cause 链就能知道问题出在数据库层，而不是网络层或其他中间环节。这种透明性对于分布式系统的排查是极大的帮助。建议在每个服务的入口和出口处都记录 cause 信息，构建完整的请求链路日志。这样在出现问题时，不需要手动串联多个服务的日志，就能快速定位延迟点或失败点。