1. 从一个真实场景说起：为什么你的 goroutine 关不掉
刚写 Go 那会儿，我做过一个定时同步数据的小服务。主流程很简单：起一个 goroutine 每隔几秒拉一次接口，把结果写进数据库。上线跑了一周，某天运维告诉我内存一直在涨，重启之后才恢复。我盯着代码看了半天，逻辑上没有任何泄漏点，最后发现问题出在那个 goroutine 上——服务收到退出信号时，主函数直接return了，可那个后台 goroutine 还在傻乎乎地循环，它持有的数据库连接、HTTP 客户端、缓冲区全都没被释放。
这就是 Go 新手最容易踩的坑：goroutine 一旦启动，就没有任何外部手段能把它“掐死”。Go 运行时没有提供 kill 某个 goroutine 的 API，这是刻意设计的结果，因为强制终止会让共享状态处于不可预期的中间态。那怎么办？答案就是让 goroutine 自己决定退出，而传递“该退出了”这个信号的载体，就是context.Context，日常代码里一般简写成ctx。
ctx在 Go 里几乎无处不在。你写 Gin 的 handler，第一个参数就是c.Request.Context()；你用database/sql做查询，有QueryContext；你调 gRPC，每个方法第一个参数都是ctx；你写go-redis，命令方法也带ctx。可以说，不理解 ctx，就不算真正入门 Go 的并发编程。这篇文章我打算把 ctx 从“是什么”到“怎么用”再到“怎么用对”完整讲一遍，结合 Gin、goroutine、超时控制这些高频场景，把我在实际项目里踩过的坑和总结的经验都摊开说。不管你是刚学 Go 语法的新手，还是已经能写业务但总感觉并发控制不踏实的同学，应该都能从里面拿到能直接抄的东西。
2. Context 到底是什么：拆开看它的四个能力
2.1 一句话定义与它的设计初衷
context.Context是 Go 标准库context包里的一个接口，它的官方定位是“在 API 边界之间传递截止时间、取消信号和请求范围的值”。这句话有点绕，我拆成大白话：它是一棵可以向下传播信号的树，父节点一喊停，所有子节点全部收到通知。
为什么需要这么个东西？回到刚才的场景。一个 HTTP 请求进来，Gin 会为它创建一个根 ctx。这个请求可能触发：一次数据库查询、一次 Redis 读取、一次下游 HTTP 调用，每个操作又可能各自再起 goroutine。如果客户端中途断开连接，或者我们给整个请求设了 3 秒超时，那么这棵树上挂着的所有操作都应该立刻停下来，把资源还回去。没有 ctx 的话，你得自己维护一堆 channel 和标志位，代码会烂成一团。ctx 把这套“取消传播”的机制标准化了，所有库都认它，于是它成了 Go 并发控制的事实标准。
2.2 接口里的四个方法，各管什么
Context接口本身非常小，只有四个方法：
type Context interface { Deadline() (deadline time.Time, ok bool) Done() <-chan struct{} Err() error Value(key any) any }Deadline()返回这个 ctx 的截止时间，如果没有设置就返回ok=false。它主要给那些需要提前知道自己还剩多少时间的库用，比如数据库驱动会据此决定是否还要发起连接。
Done()是最核心的一个，返回一个只读 channel。当这个 ctx 被取消或超时，这个 channel 会被关闭。注意是“关闭”而不是“发送一个值”，所以你可以用<-ctx.Done()阻塞等待，也可以用select配合其他 case 一起监听。关闭 channel 的好处是所有监听者会同时被唤醒，天然支持一对多广播。
Err()告诉你为什么 Done 被关闭了。如果是因为主动取消，返回context.Canceled；如果是因为超时，返回context.DeadlineExceeded。这两个是哨兵错误，可以用errors.Is判断。
Value(key)用来取请求范围的数据。这个方法是争议最大的，后面我会专门讲它的正确用法和滥用后果。
2.3 四种创建方式与它们的适用场景
标准库提供了四个创建 ctx 的函数，我按使用频率排一下：
| 函数 | 作用 | 典型场景 |
|---|---|---|
context.Background() | 返回一个空的根 ctx，永不取消 | main 函数、初始化、测试 |
context.TODO() | 和 Background 一样，语义上表示“还没想好” | 占位，重构时提醒自己补上 |
context.WithCancel(parent) | 返回可手动取消的 ctx | 需要主动停止的场景 |
context.WithTimeout(parent, d) | 带超时自动取消 | 网络请求、数据库查询 |
context.WithDeadline(parent, t) | 指定绝对时间点取消 | 有明确截止时刻的任务 |
context.WithValue(parent, k, v) | 携带键值对 | 传递请求 ID、认证信息 |
Background和TODO在实现上完全一样，区别只在语义。我个人的习惯是：main 里用Background，写业务代码时如果暂时不知道该传什么 ctx，先用TODO，这样 code review 时一眼就能看到哪里还没处理。
WithCancel、WithTimeout、WithDeadline都会返回两个值：新的 ctx 和一个CancelFunc。这个 CancelFunc 必须被调用，哪怕超时自动取消了也要调，因为它负责释放父节点里挂着的子节点引用。不调用就是内存泄漏，这一点后面会展开。
3. 取消传播机制：ctx 树是怎么工作的
3.1 父子关系与信号向下传递
每次调用WithCancel、WithTimeout这类函数，都会创建一个新的 ctx，它内部持有对父 ctx 的引用，同时父 ctx 也会把这个子节点登记到自己的 children 列表里。这样就形成了一棵树。
信号传播是单向的，只能从父到子。父 ctx 被取消时，它会遍历自己的 children，逐个取消，子节点再取消它们的子节点，层层递归下去。反过来，子 ctx 被取消不会影响父 ctx，也不会影响兄弟节点。这个设计很合理：一个请求里某个子操作失败了，不应该把整个请求干掉，除非你主动决定这么做。
我用一个生活化的类比：ctx 树就像公司的组织架构。CEO（根 ctx）说“项目暂停”，所有部门（子 ctx）全部停工。但某个小组（叶子 ctx）自己提前完成了任务，不影响其他小组继续干活。
3.2 Done channel 的关闭语义
理解Done()的关键是理解 channel 关闭的行为。一个被关闭的 channel，读取操作会立即返回零值，不会阻塞。所以<-ctx.Done()在 ctx 未取消时阻塞，取消后立即返回。这个特性让它可以和select完美配合：
select { case <-ctx.Done(): return ctx.Err() case result := <-resultCh: return result }这里有个细节很多人不知道：Done()每次调用返回的是同一个 channel，不是新建的。所以你可以放心地在多个 goroutine 里各自调用ctx.Done()，它们监听的是同一个信号源。这也是为什么 ctx 天然支持一对多广播，不需要你自己维护订阅者列表。
3.3 为什么必须调用 CancelFunc
这是 ctx 使用中最容易被忽视、后果最严重的一点。WithCancel系列函数在父 ctx 里注册了子节点，如果不调用 CancelFunc，这个子节点会一直挂在父节点的 children 列表里，直到父节点自己被取消。如果父节点是Background()，那它永远不会取消，子节点就永远不释放。
想象一个 HTTP 服务，每个请求都从Background派生一个带超时的 ctx。如果每个请求处理完都不调 CancelFunc，那么随着请求量累积，Background的 children 列表会无限增长，内存持续上涨。这就是我开头那个内存泄漏案例的另一种形态。
所以规则很简单：只要调用了 WithCancel/WithTimeout/WithDeadline，就立刻写defer cancel()。哪怕你觉得超时会自动触发，也要写。go vet工具会检查这一点，建议把它加进 CI。
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) defer cancel() // 这一行不能省4. 在 Gin 项目里把 ctx 用对：从请求入口到下游调用
4.1 Gin 的 Context 和标准库 Context 不是一回事
新手最容易混淆的地方来了。Gin 有个自己的*gin.Context，标准库有个context.Context，两者名字像但完全不是一个东西。
*gin.Context是 Gin 框架封装的对象，负责处理 HTTP 请求和响应，提供c.JSON()、c.Param()、c.Bind()这些方法。它内部持有一个标准库的context.Context，通过c.Request.Context()取出来。
标准库的context.Context才是我们说的 ctx，负责取消传播和超时控制。
所以正确的做法是：在 handler 里，用c.Request.Context()拿到标准库 ctx，然后把它传给下游的数据库、Redis、HTTP 调用。不要把*gin.Context直接传给 service 层或 repository 层，那样会让业务代码和 Web 框架耦合，测试起来也麻烦。
func GetUser(c *gin.Context) { ctx := c.Request.Context() user, err := userService.FindByID(ctx, c.Param("id")) if err != nil { c.JSON(500, gin.H{"error": err.Error()}) return } c.JSON(200, user) }4.2 给请求加超时：中间件的正确写法
Gin 默认不会给请求设超时，一个慢查询可能把连接一直占着。生产环境里我一般会加一个超时中间件：
func TimeoutMiddleware(d time.Duration) gin.HandlerFunc { return func(c *gin.Context) { ctx, cancel := context.WithTimeout(c.Request.Context(), d) defer cancel() c.Request = c.Request.WithContext(ctx) c.Next() } }这里有个关键点：必须用c.Request.WithContext(ctx)把新 ctx 塞回去，否则下游通过c.Request.Context()拿到的还是原来的 ctx，超时设置就白做了。这个坑我见过不止一个同事踩。
超时时长的选择也有讲究。我一般按 P99 响应时间来定，比如接口 P99 是 800ms，那超时设 2 秒左右比较合适，留出余量但不至于让慢请求拖太久。设太短会误杀正常请求，设太长等于没设。
4.3 下游调用如何响应取消
光设了超时还不够，下游操作必须真的“听得懂”取消信号。这就是为什么我们要用带 ctx 的方法：
- 数据库：
db.QueryContext(ctx, ...)而不是db.Query(...) - Redis：
rdb.Get(ctx, key)而不是rdb.Get(key) - HTTP 调用：
http.NewRequestWithContext(ctx, ...) - gRPC：方法第一个参数就是 ctx
这些方法内部会监听ctx.Done()，一旦取消就中断操作并返回错误。如果你用了不带 ctx 的版本，超时到了 ctx 取消了，但数据库查询还在跑，连接还占着，超时就形同虚设。
我见过一个项目，中间件加了超时，但 repository 层全用的是db.Query，结果压测时连接池被打满，排查半天才发现是这里的问题。ctx 的取消要贯穿整条调用链才有意义，任何一环断了，前面的努力都白费。
5. WithValue 的正确姿势与滥用警告
5.1 它该用来传什么
context.WithValue的官方建议是：只用来传递“请求范围的数据”，也就是那些贯穿整个请求生命周期、但不影响业务逻辑的数据。典型的有：
- 请求 ID（trace ID），用于日志串联
- 认证信息，比如解析后的用户 ID
- 租户 ID，多租户系统里区分数据归属
这些数据的共同点是：它们不是函数的业务参数，但下游很多地方都需要，一层层往下传太啰嗦，用 ctx 携带比较自然。
5.2 它不该用来传什么
反过来，以下这些千万别往 ctx 里塞：
- 数据库连接、Redis 客户端这类依赖，应该用依赖注入
- 业务参数，比如分页大小、查询条件，这些应该是函数参数
- 可选参数，用来规避函数签名设计问题
我见过最离谱的用法是把整个*gin.Context塞进context.WithValue，然后在 service 层取出来用。这等于把框架耦合带到了业务层，测试时根本没法 mock。
还有一个隐蔽的坑：key 的类型。如果你用字符串当 key，不同包可能用同样的字符串，导致冲突。正确做法是定义一个不导出的自定义类型：
type ctxKey string const userIDKey ctxKey = "userID" // 存 ctx = context.WithValue(ctx, userIDKey, 123) // 取 id, ok := ctx.Value(userIDKey).(int)这样即使别的包也用"userID"字符串，类型不同就不会冲突。
5.3 取值时的类型断言陷阱
ctx.Value返回的是any，取值时必须做类型断言。如果 key 不存在，返回nil，断言会 panic。所以一定要用带 ok 的形式：
id, ok := ctx.Value(userIDKey).(int) if !ok { // 处理缺失情况 }我在 code review 里见过直接ctx.Value(key).(int)的写法，线上某次因为中间件顺序调整导致 key 没塞进去，直接 panic 了。这种错误完全可以用带 ok 的断言避免。
6. 常见问题与排查实录
6.1 goroutine 泄漏怎么发现和定位
goroutine 泄漏是 ctx 用错最常见的后果。发现手段有两个：一是监控runtime.NumGoroutine()，如果持续上涨不回落，基本就是泄漏了；二是用 pprof 的 goroutine profile，能看到每个 goroutine 的调用栈。
定位时重点看那些阻塞在 channel 接收、网络 IO、锁等待上的 goroutine。如果它们的调用栈里有select监听ctx.Done()，但 ctx 一直没被取消，那就是取消信号没传到位。
6.2 超时没生效的几种原因
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 超时到了请求还在跑 | 下游用了不带 ctx 的方法 | 检查 db/redis/http 调用 |
| 超时时间不对 | 中间件没把 ctx 塞回 Request | 检查WithContext |
| 子 ctx 超时不影响父 | 这是正常行为 | 确认是否需要父也取消 |
| 取消后仍占资源 | 没调 CancelFunc | 检查 defer cancel |
6.3 几个我踩过的坑
第一个坑：在循环里创建 ctx 但忘了 cancel。比如批量处理任务，每个任务WithTimeout一次，如果不在循环体内 defer cancel，而是攒到最后，中间那些 ctx 一直挂着。正确做法是把每次处理包成一个函数，在函数内 defer。
第二个坑：把 ctx 存进结构体字段。ctx 应该作为函数第一个参数显式传递，不应该作为结构体成员。存进结构体后，生命周期就乱了，很容易出现用一个已经取消的 ctx 去发请求。
第三个坑：用context.Background()作为下游调用的 ctx。这样等于放弃了取消传播，上游取消了它也不知道。除非是真正独立的后台任务，否则都应该从请求 ctx 派生。
7. 一套可以直接抄的实践模板
把上面的经验浓缩成几条规则，我在项目里基本就是这么执行的：
- 函数第一个参数是
ctx context.Context，命名统一用ctx - 只要调用了 WithCancel/WithTimeout/WithDeadline，下一行立刻
defer cancel() - 下游调用一律用带 ctx 的版本，不用裸方法
- WithValue 只传请求范围数据，key 用自定义不导出类型
- 不在结构体里存 ctx，不把 ctx 当可选参数
- 中间件里改 ctx 后必须
c.Request.WithContext(ctx)塞回去 - CI 里跑
go vet，它会帮你抓出没调 cancel 的地方
这套规则不复杂，但坚持下来能避免绝大多数 ctx 相关的线上问题。我自己从“能跑就行”到“每个 ctx 都管好生命周期”，中间交了不少学费，希望这些经验能让你少走点弯路。真要说的话，ctx 这东西，用对了是并发控制的利器，用错了就是内存泄漏和诡异 bug 的温床，区别就在这些细节里。
