用途:指导在 Go 中正确使用 context.Context,避免 goroutine 泄漏、孤立任务和隐蔽的生产缺陷。
主要能力:
- 核心规则:context 必须是函数第一个参数;禁止存入结构体;禁止传 nil,不确定时用 context.TODO(),顶层用 context.Background()。
- 取消:WithCancel 后立即 defer cancel(),否则泄漏定时器与 goroutine;循环中检查 ctx.Err();可配合 errgroup 在任一 worker 出错时取消其余任务。
- 超时与截止:WithTimeout 用于时长限制,WithDeadline 用于绝对时间;子超时只消耗父预算、不会延长,必要时用 ctx.Deadline() 读取剩余预算并快速失败。
- 值:只存请求级元数据(请求 ID、trace/span ID、已认证用户、请求级 logger),键必须是非导出类型而非字符串,并提供访问函数。
- HTTP 与测试:处理器使用 r.Context() 并向下传递,中间件用 r.WithContext(ctx) 附加值;测试用 context.WithTimeout 防止挂起,并用 errors.Is(err, context.Canceled) 验证取消被遵守。
使用方式:按需加载 references/timeout-budgets.md、references/values.md、references/http-and-testing.md 等参考文件,仅在正文不足时阅读。
适用场景:Go 服务端请求处理、并发任务编排、HTTP 处理器与中间件、超时预算设计及取消相关测试。
限制:资料未提供安装命令、版本要求、收费信息或平台支持说明;内容为规范与示例,不构成可直接运行的完整程序。