Go context 传递实战超时、取消和元数据的最佳实践一、一个 Goroutine 泄漏引发的凌晨排查凌晨两点收到告警某服务 Goroutine 数量从平时的 200 飙升到 15000内存占用 8GBOOM 被 kill 了三次。排查发现源头是上游服务调用超时后断开了连接但下游的 300 个 Goroutine 全都没有收到取消信号继续执行数据库查询和模型推理——白白消耗 CPU 和连接池。这个问题指向一个 Go 开发中最常见的坑context 用错了或者根本没传。context.Context是 Go 并发模型的神经系统不传 context 就像神经系统坏死了——你不知道 Goroutine 什么时候该停、什么时候该退。二、Context 传递的三层语义Go 的 context 包提供了三种核心能力每种对应不同的场景取消传播当父 context 被取消时所有子 context 自动取消。这保证了请求退出时整个调用链上的 Goroutine 都能收到停止信号。超时控制为操作设置绝对截止时间或相对超时时间防止单个慢操作拖垮整个请求。元数据传递在调用链中传递请求级别的键值对如 TraceID、UserID避免在每个函数签名中显式传递。sequenceDiagram participant Client as HTTP 客户端 participant Handler as HTTP Handler participant Service as 业务服务层 participant DB as 数据库 participant LLM as 大模型 API Client-Handler: GET /api/chat?qxxx Handler-Handler: ctx context.WithTimeout(5s) Handler-Handler: ctx WithTraceID(ctx, abc123) Handler-Service: ProcessMessage(ctx, msg) Service-Service: ctx, cancel WithTimeout(3s) Service-DB: QueryHistory(ctx, userID) alt 数据库查询超时 DB--Service: context.DeadlineExceeded Service-Service: cancel() Service--Handler: Err: timeout Handler--Client: 504 Gateway Timeout else 查询成功 DB--Service: results Service-LLM: CallModel(ctx, prompt) alt 客户端断开连接 Handler-Handler: ctx.Done() Service-LLM: (cancel 传播) LLM--Service: context.Canceled end endContext 传递的核心原则永远不要把 context 存储在结构体字段中它应该在函数调用链上显式传递作为第一个参数。这样每个函数都能清楚地知道它的生命周期受谁控制。三、三个生产级的 Context 使用模式package service import ( context database/sql errors fmt net/http time ) // 模式 1多层超时控制 // ProcessChatMessage 处理聊天消息展示多层超时的正确用法 func ProcessChatMessage(ctx context.Context, userID, message string) (string, error) { // 第一层整体请求超时由 HTTP Handler 设置 // 这里继承上游的超时不再重复设置 // 第二层数据库查询子任务超时 dbCtx, dbCancel : context.WithTimeout(ctx, 2*time.Second) defer dbCancel() // 关键用完立即释放资源 history, err : queryChatHistory(dbCtx, userID) if err ! nil { if errors.Is(err, context.DeadlineExceeded) { return , fmt.Errorf(查询历史记录超时请稍后重试) } return , fmt.Errorf(查询历史失败: %w, err) } // 第三层模型推理子任务超时 llmCtx, llmCancel : context.WithTimeout(ctx, 5*time.Second) defer llmCancel() resp, err : callLLM(llmCtx, history, message) if err ! nil { return , fmt.Errorf(模型推理失败: %w, err) } return resp, nil } // 模式 2Fan-out 并发控制 // BatchInference 批量推理任意一个子任务失败则取消所有 func BatchInference(ctx context.Context, prompts []string) ([]string, error) { // 创建可取消的子 context任一子任务失败时取消其余 ctx, cancel : context.WithCancel(ctx) defer cancel() type result struct { idx int text string err error } resultCh : make(chan result, len(prompts)) for i, p : range prompts { go func(idx int, prompt string) { r : result{idx: idx} // 在 goroutine 内部再次包装超时 taskCtx, taskCancel : context.WithTimeout(ctx, 3*time.Second) defer taskCancel() resp, err : callLLM(taskCtx, nil, prompt) if err ! nil { r.err err cancel() // 任一失败通知其他 goroutine 停止 } else { r.text resp } resultCh - r }(i, p) } // 收集结果 results : make([]string, len(prompts)) var firstErr error for i : 0; i len(prompts); i { r : -resultCh if r.err ! nil firstErr nil { firstErr r.err } results[r.idx] r.text } if firstErr ! nil { return nil, firstErr } return results, nil } // 模式 3元数据传递 type contextKey string const ( KeyTraceID contextKey trace_id KeyUserID contextKey user_id KeyRequestID contextKey request_id ) // WithTraceID 往 context 中注入 TraceID func WithTraceID(ctx context.Context, traceID string) context.Context { return context.WithValue(ctx, KeyTraceID, traceID) } // TraceIDFromContext 从 context 中提取 TraceID func TraceIDFromContext(ctx context.Context) string { if v, ok : ctx.Value(KeyTraceID).(string); ok { return v } return unknown } // HTTP 中间件从请求头提取并注入元数据 func TraceMiddleware(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { ctx : r.Context() // 优先使用上游传入的 TraceID traceID : r.Header.Get(X-Trace-ID) if traceID { traceID generateTraceID() } ctx WithTraceID(ctx, traceID) // 设置整体请求超时 ctx, cancel : context.WithTimeout(ctx, 30*time.Second) defer cancel() next.ServeHTTP(w, r.WithContext(ctx)) }) } // 辅助函数 type Message struct { Role string Content string } func queryChatHistory(ctx context.Context, userID string) ([]Message, error) { // 检查 context 是否已取消避免无意义查询 select { case -ctx.Done(): return nil, ctx.Err() default: } // 实际数据库查询... _ userID return nil, nil } func callLLM(ctx context.Context, history []Message, prompt string) (string, error) { // 检查是否已取消 select { case -ctx.Done(): return , ctx.Err() default: } // 实际 LLM 调用... return response, nil } func generateTraceID() string { return fmt.Sprintf(%d, time.Now().UnixNano()) }四、Context 使用的常见陷阱与边界不要把 context 存到 struct 中。这是 Go 官方文档明确反对的做法。Context 的生命周期应该和请求一致存储到 struct 意味着它可能会在请求结束后继续存在导致逻辑混乱和资源泄漏。defer cancel() 必须紧跟 WithTimeout/WithCancel。忘记调用 cancel 会让相关的 timer goroutine 持续运行直到超时触发。在循环中使用时尤其危险——每次迭代创建新 context 但不 canceltimer 会堆积。context.Value 的值尽量简单。不要把大对象、可变对象放到 context 中。context.Value 应该用于请求范围的元数据如 TraceID、UserID而不是用来替代正经的依赖注入。超时时间要分层设置。总超时 数据库超时 模型推理超时 其他子任务超时。如果子任务超时大于总超时子任务永远不会正常完成。五、总结Context 是 Go 并发编程的安全绳。三条铁律第一总是作为函数第一个参数传递第二WithTimeout/WithCancel 必须紧跟 defer cancel()第三在启动 goroutine 前检查 ctx.Done()。记住 Context 的职责边界它负责生命周期管理取消、超时和元数据传递不负责业务流程控制。当你的 Goroutine 数量异常增长时第一个排查方向永远是——context 有没有传到链条的最末端。
Go context 传递实战超时、取消和元数据的最佳实践一、一个 Goroutine 泄漏引发的凌晨排查凌晨两点收到告警某服务 Goroutine 数量从平时的 200 飙升到 15000内存占用 8GBOOM 被 kill 了三次。排查发现源头是上游服务调用超时后断开了连接但下游的 300 个 Goroutine 全都没有收到取消信号继续执行数据库查询和模型推理——白白消耗 CPU 和连接池。这个问题指向一个 Go 开发中最常见的坑context 用错了或者根本没传。context.Context是 Go 并发模型的神经系统不传 context 就像神经系统坏死了——你不知道 Goroutine 什么时候该停、什么时候该退。二、Context 传递的三层语义Go 的 context 包提供了三种核心能力每种对应不同的场景取消传播当父 context 被取消时所有子 context 自动取消。这保证了请求退出时整个调用链上的 Goroutine 都能收到停止信号。超时控制为操作设置绝对截止时间或相对超时时间防止单个慢操作拖垮整个请求。元数据传递在调用链中传递请求级别的键值对如 TraceID、UserID避免在每个函数签名中显式传递。sequenceDiagram participant Client as HTTP 客户端 participant Handler as HTTP Handler participant Service as 业务服务层 participant DB as 数据库 participant LLM as 大模型 API Client-Handler: GET /api/chat?qxxx Handler-Handler: ctx context.WithTimeout(5s) Handler-Handler: ctx WithTraceID(ctx, abc123) Handler-Service: ProcessMessage(ctx, msg) Service-Service: ctx, cancel WithTimeout(3s) Service-DB: QueryHistory(ctx, userID) alt 数据库查询超时 DB--Service: context.DeadlineExceeded Service-Service: cancel() Service--Handler: Err: timeout Handler--Client: 504 Gateway Timeout else 查询成功 DB--Service: results Service-LLM: CallModel(ctx, prompt) alt 客户端断开连接 Handler-Handler: ctx.Done() Service-LLM: (cancel 传播) LLM--Service: context.Canceled end endContext 传递的核心原则永远不要把 context 存储在结构体字段中它应该在函数调用链上显式传递作为第一个参数。这样每个函数都能清楚地知道它的生命周期受谁控制。三、三个生产级的 Context 使用模式package service import ( context database/sql errors fmt net/http time ) // 模式 1多层超时控制 // ProcessChatMessage 处理聊天消息展示多层超时的正确用法 func ProcessChatMessage(ctx context.Context, userID, message string) (string, error) { // 第一层整体请求超时由 HTTP Handler 设置 // 这里继承上游的超时不再重复设置 // 第二层数据库查询子任务超时 dbCtx, dbCancel : context.WithTimeout(ctx, 2*time.Second) defer dbCancel() // 关键用完立即释放资源 history, err : queryChatHistory(dbCtx, userID) if err ! nil { if errors.Is(err, context.DeadlineExceeded) { return , fmt.Errorf(查询历史记录超时请稍后重试) } return , fmt.Errorf(查询历史失败: %w, err) } // 第三层模型推理子任务超时 llmCtx, llmCancel : context.WithTimeout(ctx, 5*time.Second) defer llmCancel() resp, err : callLLM(llmCtx, history, message) if err ! nil { return , fmt.Errorf(模型推理失败: %w, err) } return resp, nil } // 模式 2Fan-out 并发控制 // BatchInference 批量推理任意一个子任务失败则取消所有 func BatchInference(ctx context.Context, prompts []string) ([]string, error) { // 创建可取消的子 context任一子任务失败时取消其余 ctx, cancel : context.WithCancel(ctx) defer cancel() type result struct { idx int text string err error } resultCh : make(chan result, len(prompts)) for i, p : range prompts { go func(idx int, prompt string) { r : result{idx: idx} // 在 goroutine 内部再次包装超时 taskCtx, taskCancel : context.WithTimeout(ctx, 3*time.Second) defer taskCancel() resp, err : callLLM(taskCtx, nil, prompt) if err ! nil { r.err err cancel() // 任一失败通知其他 goroutine 停止 } else { r.text resp } resultCh - r }(i, p) } // 收集结果 results : make([]string, len(prompts)) var firstErr error for i : 0; i len(prompts); i { r : -resultCh if r.err ! nil firstErr nil { firstErr r.err } results[r.idx] r.text } if firstErr ! nil { return nil, firstErr } return results, nil } // 模式 3元数据传递 type contextKey string const ( KeyTraceID contextKey trace_id KeyUserID contextKey user_id KeyRequestID contextKey request_id ) // WithTraceID 往 context 中注入 TraceID func WithTraceID(ctx context.Context, traceID string) context.Context { return context.WithValue(ctx, KeyTraceID, traceID) } // TraceIDFromContext 从 context 中提取 TraceID func TraceIDFromContext(ctx context.Context) string { if v, ok : ctx.Value(KeyTraceID).(string); ok { return v } return unknown } // HTTP 中间件从请求头提取并注入元数据 func TraceMiddleware(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { ctx : r.Context() // 优先使用上游传入的 TraceID traceID : r.Header.Get(X-Trace-ID) if traceID { traceID generateTraceID() } ctx WithTraceID(ctx, traceID) // 设置整体请求超时 ctx, cancel : context.WithTimeout(ctx, 30*time.Second) defer cancel() next.ServeHTTP(w, r.WithContext(ctx)) }) } // 辅助函数 type Message struct { Role string Content string } func queryChatHistory(ctx context.Context, userID string) ([]Message, error) { // 检查 context 是否已取消避免无意义查询 select { case -ctx.Done(): return nil, ctx.Err() default: } // 实际数据库查询... _ userID return nil, nil } func callLLM(ctx context.Context, history []Message, prompt string) (string, error) { // 检查是否已取消 select { case -ctx.Done(): return , ctx.Err() default: } // 实际 LLM 调用... return response, nil } func generateTraceID() string { return fmt.Sprintf(%d, time.Now().UnixNano()) }四、Context 使用的常见陷阱与边界不要把 context 存到 struct 中。这是 Go 官方文档明确反对的做法。Context 的生命周期应该和请求一致存储到 struct 意味着它可能会在请求结束后继续存在导致逻辑混乱和资源泄漏。defer cancel() 必须紧跟 WithTimeout/WithCancel。忘记调用 cancel 会让相关的 timer goroutine 持续运行直到超时触发。在循环中使用时尤其危险——每次迭代创建新 context 但不 canceltimer 会堆积。context.Value 的值尽量简单。不要把大对象、可变对象放到 context 中。context.Value 应该用于请求范围的元数据如 TraceID、UserID而不是用来替代正经的依赖注入。超时时间要分层设置。总超时 数据库超时 模型推理超时 其他子任务超时。如果子任务超时大于总超时子任务永远不会正常完成。五、总结Context 是 Go 并发编程的安全绳。三条铁律第一总是作为函数第一个参数传递第二WithTimeout/WithCancel 必须紧跟 defer cancel()第三在启动 goroutine 前检查 ctx.Done()。记住 Context 的职责边界它负责生命周期管理取消、超时和元数据传递不负责业务流程控制。当你的 Goroutine 数量异常增长时第一个排查方向永远是——context 有没有传到链条的最末端。
