超时 on 吾爱主机

Python asyncio 事件循环与 Task 取消：原理、API 与工程实践

Mon, 20 Jul 2026 00:00:00 +0800

高并发 HTTP 客户端、WebSocket 网关、爬虫调度、微服务侧车——Python 侧大量 IO 密集型场景会落到 asyncio。写得不好时，常见症状是：协程“创建了却从不调度”、后台 Task 被 GC 悄悄干掉、超时后资源不释放、CancelledError 被误吞导致 TaskGroup / timeout 行为异常。

本文基于官方文档 asyncio — Asynchronous I/O、Coroutines and Tasks、Runners、Developing with asyncio，以及 PEP 492，把 事件循环协作调度、Task 生命周期、结构化并发、取消与超时 讲清楚，并给出可复现的写法与排障清单。

一、问题背景：并发不等于多线程

asyncio 的定位很明确：

asyncio is a library to write concurrent code using the async/await syntax.
asyncio is often a perfect fit for IO-bound and high-level structured network code.

它解决的是“大量等待网络/磁盘时如何让 CPU 去干别的活”，而不是用多核并行跑 CPU 密集计算。事件循环通常跑在 一个线程 内：某个 Task 在执行同步代码时，同线程的其他 Task 无法推进；只有执行到 await，当前 Task 挂起，循环才调度下一个。

若把 time.sleep、同步 requests、重型 JSON/CPU 计算直接塞进协程，等价于堵死整条事件循环。官方开发指南的原则是：阻塞工作放到线程池（asyncio.to_thread / loop.run_in_executor），循环线程只做非阻塞 IO 与调度。

概念	含义	工程后果
协程函数 `async def`	调用后得到协程对象，不会自动运行	只写 `foo()` 而不 `await`/`create_task` 会 RuntimeWarning
Awaitable	可被 `await` 的对象	三类主路径：协程、Task、Future
Event loop	调度 Task/回调、做网络 IO、跑子进程	应用层优先用 `asyncio.run`，少直接操作 loop
Task	被调度执行的协程包装	可取消、可聚合、可命名/追踪

二、核心模型：协作式调度 + 弱引用 Task

1. 必须“跑起来”，而不能只“创建”

import asyncio

async def main():
 print("hello")
 await asyncio.sleep(1)
 print("world")

asyncio.run(main())

官方示例同时强调反例：

>>> main()
<coroutine object main at 0x...>

单纯调用协程不会把它排进事件循环。入口应使用 asyncio.run(coro)：它负责创建/关闭循环、收尾异步生成器、关闭默认 executor。同一线程已有运行中的 loop 时不能再调用 asyncio.run（嵌套场景用 asyncio.Runner 或上层框架提供的生命周期）。

2. 并发来自 Task，不是“多写几个 await”

串行：

await say_after(1, "hello")
await say_after(2, "world") # 总耗时约 3s

并发：

task1 = asyncio.create_task(say_after(1, "hello"))
task2 = asyncio.create_task(say_after(2, "world"))
await task1
await task2 # 总耗时约 2s

create_task 把协程包成 Task 并立即调度。一个极易踩坑的细节（官方明确写出）：

The event loop only keeps weak references to tasks. A task that isn’t referenced elsewhere may get garbage collected at any time, even before it’s done.

“发后不管”的后台任务必须放进集合，并在 done 回调里移除：

background_tasks: set[asyncio.Task] = set()

def spawn(coro):
 task = asyncio.create_task(coro)
 background_tasks.add(task)
 task.add_done_callback(background_tasks.discard)
 return task

3. 结构化并发：优先 `TaskGroup`（3.11+）

asyncio.TaskGroup 把“创建 + 等待全部结束”绑在异步上下文管理器里：

async def main():
 async with asyncio.TaskGroup() as tg:
 tg.create_task(say_after(1, "hello"))
 tg.create_task(say_after(2, "world"))
 # 退出 with 时，组内任务均已结束

组内若有任务抛出非 CancelledError 的异常，会汇总为 ExceptionGroup / BaseExceptionGroup 再抛出。相对“手写 create_task + 忘记 await”，TaskGroup 更不容易留下孤儿任务。

API	典型用途	注意点
`create_task`	灵活并发、需要 Task 句柄	保持强引用；自行处理汇合
`TaskGroup`	结构化并发、统一收口	异常变为 ExceptionGroup；依赖取消语义正确
`gather(*aws, return_exceptions=False)`	固定一批 awaitable 一起等	默认某任务异常会影响整体策略；结果顺序与入参一致
`wait(aws, return_when=...)`	需要 `done/pending` 集合或 FIRST_COMPLETED	入参必须是 Future/Task 集合，不能是裸协程习惯用法

gather 适合“固定 N 路、要按入参顺序拿结果”：

results = await asyncio.gather(
 fetch(u1),
 fetch(u2),
 fetch(u3),
 return_exceptions=True, # 单个失败不中断其余；结果里可能是 Exception 实例
)

return_exceptions=False（默认）时，任一 awaitable 以异常结束，gather 会把该异常传播给调用方（其余任务的收尾策略仍需按版本与场景理解，工程上更稳妥的是用 TaskGroup 明确“有错就结构化失败”）。wait 则返回 (done, pending)，并可用 FIRST_COMPLETED / FIRST_EXCEPTION / ALL_COMPLETED 控制返回时机，适合“谁先完成谁处理、其余取消”的竞态选路。

三、取消与超时：CancelledError 是协作信号

1. 取消发生在“下一次机会”

task.cancel() 请求取消后，目标 Task 会在 下一次可取消点（通常是 await）注入 asyncio.CancelledError。官方建议：

用 try/finally 做资源清理（关连接、放回连接池、落盘状态）；
若显式 except CancelledError，清理完成后 一般应继续抛出；
CancelledError 直接继承 BaseException，因此普通 except Exception 抓不到它——这是刻意设计。

吞掉取消会破坏结构化并发组件：

asyncio.TaskGroup and asyncio.timeout() are implemented using cancellation internally and might misbehave if a coroutine swallows asyncio.CancelledError.

2. 超时：`wait_for` 与 `timeout` 上下文

# 超时后取消 awaitable，并抛 TimeoutError
try:
 await asyncio.wait_for(long_job(), timeout=5)
except TimeoutError:
 ...

wait_for 在超时路径会取消目标任务；为避免取消可包 shield（见下）。函数会等到取消真正完成，因此总等待可能略大于 timeout。

3.11+ 更推荐上下文管理器写法：

async def main():
 try:
 async with asyncio.timeout(10):
 await long_running_task()
 except TimeoutError:
 # TimeoutError 只能在 with 之外捕获
 ...

timeout 会取消 当前 Task，内部把 CancelledError 转成 TimeoutError。timeout_at(when) 用绝对 deadline，适合与外部截止时间对齐。

3. `shield`：挡外层取消，不挡内层自杀

res = await asyncio.shield(critical_section())

外层 Task 被取消时，critical_section 对应 Task 不一定 被取消；但从调用方看，await 仍会抛 CancelledError。若 critical_section 自己取消自己，shield 挡不住。完全“无视取消”通常不推荐——多数场景应清理后退出。

4. 可复现小实验：串行 vs 并发 vs 超时取消

把下面脚本存为 asyncio_lab.py，用本机 Python 3.11+ 直接跑，对照耗时与异常类型：

import asyncio
import time

async def work(name: str, delay: float, fail: bool = False):
 print(f"{name}: start")
 try:
 await asyncio.sleep(delay)
 if fail:
 raise RuntimeError(f"{name} failed")
 print(f"{name}: done")
 return name
 finally:
 print(f"{name}: cleanup")

async def demo_serial():
 t0 = time.perf_counter()
 await work("A", 1)
 await work("B", 1)
 print("serial_sec=", round(time.perf_counter() - t0, 2))

async def demo_concurrent():
 t0 = time.perf_counter()
 async with asyncio.TaskGroup() as tg:
 tg.create_task(work("A", 1))
 tg.create_task(work("B", 1))
 print("concurrent_sec=", round(time.perf_counter() - t0, 2))

async def demo_timeout_cancel():
 try:
 async with asyncio.timeout(0.3):
 await work("slow", 2)
 except TimeoutError:
 print("got TimeoutError as expected")

async def demo_swallow_cancel_bad():
 async def bad():
 try:
 await asyncio.sleep(10)
 except asyncio.CancelledError:
 print("swallowed cancel — TaskGroup/timeout 可能异常")
 # 反例：清理后应 re-raise
 return "oops"

 task = asyncio.create_task(bad())
 await asyncio.sleep(0.05)
 task.cancel()
 print("bad_result=", await asyncio.gather(task, return_exceptions=True))

async def main():
 await demo_serial()
 await demo_concurrent()
 await demo_timeout_cancel()
 await demo_swallow_cancel_bad()

if __name__ == "__main__":
 asyncio.run(main())

预期现象：

串行约 2s，并发约 1s，说明 await 串接 ≠ 并发；
超时路径打印 cleanup 后得到 TimeoutError（timeout 上下文在内部完成 CancelledError 转换）；
吞掉 CancelledError 会让任务“以普通返回值结束”，外层若误以为已取消，容易泄漏后续逻辑。

四、工程实践：从入口到排障

1. 入口与生命周期

async def app():
 # 创建共享资源：连接池、httpx.AsyncClient 等
 async with lifespan():
 await serve()

if __name__ == "__main__":
 asyncio.run(app(), debug=False) # 开发可 debug=True

需要在同一 loop 多次跑顶层协程时，用 asyncio.Runner 上下文，而不是嵌套 asyncio.run。

2. 阻塞调用迁出事件循环

def blocking_io():
 # 同步 SDK / 磁盘 / 旧库
 return open("/etc/hosts").read()

async def handler():
 data = await asyncio.to_thread(blocking_io)
 return data

to_thread 会传播 contextvars，适合 IO 型阻塞；CPU 密集可考虑进程池 executor。

3. 取消友好的业务骨架

async def fetch_with_cleanup(session, url):
 resp = None
 try:
 resp = await session.get(url)
 return await resp.text()
 finally:
 if resp is not None:
 await resp.aclose()

原则：

所有可能长时间 await 的路径都假定可被取消；
持有的锁、文件、连接在 finally 释放；
不要用裸 except Exception: pass 包住整段协程。

4. 并发扇出模板

async def fan_out(urls: list[str], limit: int = 20):
 sem = asyncio.Semaphore(limit)

 async def one(url: str):
 async with sem:
 return await fetch(url)

 async with asyncio.TaskGroup() as tg:
 tasks = [tg.create_task(one(u)) for u in urls]
 return [t.result() for t in tasks]

限流用 Semaphore，汇合用 TaskGroup，超时可在外层 async with asyncio.timeout(...) 包住整组或单个 one。

5. 调试开关

开发期打开 debug mode（任选其一）：

环境变量 PYTHONASYNCIODEBUG=1
asyncio.run(..., debug=True)
loop.set_debug(True)

debug 能更清楚地指出 never-awaited coroutine 的创建栈，并帮助发现慢回调。配合：

import logging
logging.basicConfig(level=logging.DEBUG)

6. 与多线程协作时的边界

官方 Developing with asyncio 写得很清楚：事件循环在一个线程里跑所有回调与 Task；几乎所有 asyncio 对象都不是线程安全的。从其他 OS 线程调度回调必须用 loop.call_soon_threadsafe(...)；从其他线程提交协程用 asyncio.run_coroutine_threadsafe(coro, loop)，它返回 concurrent.futures.Future。反向地，若只是要把阻塞函数丢出循环线程，优先 asyncio.to_thread，而不是自己裸开线程再回调 loop。

工程约束可以记成：

一个 loop 绑定一个线程（通常是主线程）；
跨线程只走 threadsafe API；
业务协程里不要 threading.Lock 长时间占着不 await——锁竞争会放大“假死”表象。

7. HTTP 扇出 + 首个成功取消其余

async def first_success(coros):
 tasks = [asyncio.create_task(c) for c in coros]
 try:
 while tasks:
 done, pending = await asyncio.wait(
 tasks, return_when=asyncio.FIRST_COMPLETED
 )
 for d in done:
 if d.exception() is None:
 for p in pending:
 p.cancel()
 # 收尾 pending，避免警告
 await asyncio.gather(*pending, return_exceptions=True)
 return d.result()
 tasks = list(pending)
 raise RuntimeError("all failed")
 finally:
 for t in tasks:
 if not t.done():
 t.cancel()

这是“多副本查询取最快”的常见模式：与 Go 里 fan-out + context cancel 同构，只是取消载体从 context.Context 换成了 Task.cancel / CancelledError。

五、常见坑与排查清单

症状	可能根因	排查/修复
`RuntimeWarning: coroutine 'x' was never awaited`	写了 `x()` 却未 `await`/`create_task`	打开 debug；全文搜未 await 的调用
后台任务“跑一半消失”	只 `create_task` 未保存强引用	`set` + `add_done_callback(discard)`
整体 QPS 骤降、延迟抖动	协程内同步阻塞	火焰图/`asyncio` 慢回调日志；改 `to_thread`
超时后连接仍占满	取消路径无 `finally` 清理	统一 async context manager
`TaskGroup` / `timeout` 行为怪异	`except CancelledError: pass` 吞取消	清理后 re-raise；勿滥用 `uncancel`
Jupyter/已有 loop 报错	嵌套 `asyncio.run`	用框架提供的 loop / `Runner` / `await` 直接写
取消不及时	长段纯计算无 `await`	拆分、主动 `await asyncio.sleep(0)` 让出（治标）或迁线程/进程（治本）

快速自检脚本思路：

# 1) 开发模式跑入口
PYTHONASYNCIODEBUG=1 python app.py

# 2) 确认没有 never-awaited
# 3) 压测时观察是否仅单核打满且无网络等待（疑似阻塞循环）

六、总结

asyncio 是单线程协作式并发：await 是让出点；阻塞代码会冻住所有 Task。
协程对象 ≠ 已调度任务：入口用 asyncio.run，并发用 create_task / TaskGroup。
Task 只有弱引用：fire-and-forget 必须自管强引用集合。
取消是协作语义：CancelledError 属 BaseException；清理后应继续传播，否则破坏 TaskGroup/timeout。
超时优先结构化 API：asyncio.timeout / wait_for；关键段可 shield，但不要“永远不退出”。
阻塞 IO 迁出循环：to_thread / executor；开发期打开 debug 抓 never-awaited 与慢回调。

掌握“调度模型 + 取消契约 + 结构化汇合”，比背一长串 API 更能写出可维护的异步服务。

参考资料

Go context 取消传播与超时控制：原理、API 与工程实践

Sat, 18 Jul 2026 00:00:00 +0800

HTTP 请求被客户端断开、下游 RPC 超时、批量任务需要“先完成的取消其余副本”——这些场景的共同点是：一组协作的 goroutine 必须能收到“该停了”的信号，并在约定时间内释放资源。Go 标准库的 context 包，就是为跨 API 边界传递 截止时间（deadline）、取消信号 与 请求级值 而设计的。

本文基于 context 包源码注释、pkg.go.dev/context 文档，以及 Go 官方博客 Go Concurrency Patterns: Context、Contexts and structs，把取消树、超时、CancelFunc 泄漏、WithValue 边界与常见工程坑讲清楚，并给出可落地的写法与排查清单。

一、问题背景：为什么需要 Context

没有统一取消通道时，常见反模式是：

每个函数自建 done chan struct{}，调用链一长就无法串联；
超时只写在 HTTP Client 上，业务层仍继续跑昂贵计算；
子 goroutine 不知道请求已结束，继续访问已关闭的连接，造成泄漏或写日志噪音。

官方文档的定位非常明确：

Package context defines the Context type, which carries deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes.

工程上可以记三句话：

能力	含义	典型触发
Deadline	工作最晚何时必须结束	`WithTimeout` / `WithDeadline`
Cancellation	调用方主动要求放弃	客户端断开、`cancel()`、父 context 取消
Request-scoped values	跨边界透传的请求元数据	trace id、鉴权主体（慎用）

服务入口应为入站请求创建 Context；出站调用应接收并传播同一个（或派生的）Context。中间调用链 必须向下传递，必要时用 WithCancel / WithTimeout / WithValue 派生子 Context。

二、核心模型：取消树 + Done 通道

Context 是接口，核心方法包括 Done、Err、Deadline、Value。理解取消的关键是：

Done() <-chan struct{}：通道关闭即“应停止工作”的信号；
Err()：在 Done 关闭后说明原因——context.Canceled 或 context.DeadlineExceeded；
派生形成树：父 Context 取消时，所有子 Context 一并取消；
接收方不能取消父方：Context 没有 Cancel 方法，Done 只读，避免子操作反过来取消父操作。

官方博客强调：父操作启动子操作时，子操作不应有能力取消父操作；取消权通过 WithCancel 返回的 CancelFunc 交给“拥有者”。

Background / request root
 │
 ├─ WithTimeout(2s) ──► handler 工作树
 │ │
 │ ├─ WithCancel ──► 并行查询 A
 │ └─ WithCancel ──► 并行查询 B
 │
 └─ 根取消 / 超时 / cancel()
 ⇒ 整棵子树 Done 关闭

Background() 返回永不取消、无值、无 deadline 的空 Context，适合 main、初始化、测试，以及入站请求的顶层根。TODO() 同样是空 Context，用于“暂时不清楚该用哪个 Context”的占位；不要传 nil——文档明确要求：即使函数允许 nil，也请传 context.TODO()。

三、API 速查：从根到超时

1. 取消：`WithCancel` / `WithCancelCause`

ctx, cancel := context.WithCancel(parent)
defer cancel() // 工作结束后尽快调用，释放子树与定时器资源

语义要点（源码注释）：

子 Context 的 Done 在 cancel() 被调用 或 父 Done 关闭 时关闭，谁先发生谁生效；
调用 cancel 会取消子及其后代，并断开父对子的引用、停止相关 timer；
不调用 CancelFunc 会泄漏：子 Context 及其后代会一直挂到父被取消；go vet 会检查所有控制流路径是否使用了 CancelFunc；
CancelFunc 不等待工作真正停下；可被多 goroutine 并发调用，首次之后为 no-op。

Go 1.20+ 的 cause 系列更利于排障：

ctx, cancel := context.WithCancelCause(parent)
cancel(fmt.Errorf("client disconnected: %w", err))
// ctx.Err() 仍为 context.Canceled
// context.Cause(ctx) 可取到你记录的 cause

Cause(ctx)：若通过 CancelCauseFunc(err) 取消则返回该 err；否则与 ctx.Err() 相同；未取消时返回 nil。

2. 超时与截止时间：`WithTimeout` / `WithDeadline`

// WithTimeout ≡ WithDeadline(parent, time.Now().Add(timeout))
ctx, cancel := context.WithTimeout(parent, 100*time.Millisecond)
defer cancel()
return slowOperation(ctx)

语义要点：

子 deadline 取 parent deadline 与新 deadline 中更早者；
Done 在 超时 / cancel / 父取消 三者中最先发生时关闭；
超时后 ctx.Err() 为 context.DeadlineExceeded；主动 cancel 一般为 context.Canceled；
同样必须 defer cancel()，即使操作在超时前完成，也要释放 timer 等资源。

3. 值：`WithValue`（窄场景）

type traceIDKey struct{}
ctx = context.WithValue(ctx, traceIDKey{}, "req-42")

官方硬规则：

只用于跨进程/API 传递的请求级数据，不要把可选函数参数塞进 Context；
key 必须 comparable，且 不要用内置 string 等类型当 key，避免包间碰撞；推荐自定义未导出类型，如 struct{}。

4. 进阶：`WithoutCancel` 与 `AfterFunc`（Go 1.21+）

API	用途	注意
`WithoutCancel(parent)`	派生一个不随父取消的 Context；无 Deadline/Err，Done 为 nil	父 nil 会 panic；适合“请求已结束但仍要落盘审计”的短尾工作，且必须自建超时
`AfterFunc(ctx, f)`	ctx 取消后在独立 goroutine 跑 `f`；已取消则立即调度	返回 `stop`；`stop` 不等待 `f` 结束；多次 `AfterFunc` 彼此独立

四、实践：HTTP 处理中的超时与协作取消

func handleSearch(w http.ResponseWriter, r *http.Request) {
 // 入站请求：以 r.Context() 为根（客户端断开时通常会取消）
 parent := r.Context()

 // 业务总预算：2s（与网关/客户端超时对齐，略留余量）
 ctx, cancel := context.WithTimeout(parent, 2*time.Second)
 defer cancel()

 q := r.URL.Query().Get("q")
 result, err := searchBackends(ctx, q)
 if err != nil {
 if errors.Is(err, context.DeadlineExceeded) {
 http.Error(w, "search timeout", http.StatusGatewayTimeout)
 return
 }
 if errors.Is(err, context.Canceled) {
 // 客户端已走，通常无需再写完整响应
 return
 }
 http.Error(w, err.Error(), http.StatusBadGateway)
 return
 }
 // ... 写响应
}

func searchBackends(ctx context.Context, q string) (string, error) {
 // 扇出：任一成功可取消其余；或全部失败返回
 ctx, cancel := context.WithCancel(ctx)
 defer cancel()

 type res struct {
 v string
 err error
 }
 ch := make(chan res, 2)

 for _, ep := range []string{"a.example", "b.example"} {
 ep := ep
 go func() {
 v, err := callOne(ctx, ep, q) // 内部必须监听 ctx.Done()
 ch <- res{v, err}
 }()
 }

 var last error
 for i := 0; i < 2; i++ {
 select {
 case <-ctx.Done():
 return "", context.Cause(ctx) // 或 ctx.Err()
 case r := <-ch:
 if r.err == nil {
 cancel() // 提前结束兄弟 goroutine
 return r.v, nil
 }
 last = r.err
 }
 }
 return "", last
}

func callOne(ctx context.Context, ep, q string) (string, error) {
 req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://"+ep+"/s?q="+url.QueryEscape(q), nil)
 if err != nil {
 return "", err
 }
 resp, err := http.DefaultClient.Do(req)
 if err != nil {
 return "", err
 }
 defer resp.Body.Close()
 // ... 读 body，同样尊重 ctx
 return "ok", nil
}

协作取消的正确姿势：

叶子操作用支持 Context 的 API（NewRequestWithContext、QueryContext、gRPC ctx 等）；
纯计算循环用 select 或周期性检查 ctx.Err()；
取消是 建议性（advisory） 的：库必须真正监听 Done，否则 cancel() 只是“通知了空气”。

五、不要把 Context 塞进结构体

官方文档与 Contexts and structs 博客一致：

Do not store Contexts inside a struct type; instead, pass a Context explicitly to each function that needs it. The Context should be the first parameter, typically named ctx.

六、常见坑与排查

症状	可能原因	处理
goroutine / timer 泄漏	创建了 `WithCancel`/`WithTimeout` 却没 `cancel`	立刻 `defer cancel()`；跑 `go vet`
超时不生效	底层调用未绑定 ctx（旧 `http.Get`、忽略 Done 的循环）	换 `*Context` API；手写 `select`
`Err` 总是 Canceled 难排查	未区分超时与主动取消	用 `errors.Is`；需要细节时用 Cause 系列
请求结束后仍用原 ctx 写库	父 ctx 已取消导致落库失败	短尾任务用新的 `WithTimeout(context.Background(), …)` 或审慎使用 `WithoutCancel` + 自有超时
值取不到 / 键冲突	string key 跨包碰撞或类型断言错误	私有 key 类型 + 统一 accessor
把可选参数塞进 Value	隐式依赖、难测	显式函数参数
传递 `nil` context	派生时 panic 或行为未定义	`TODO()` / `Background()`

最小实验建议：

A. WithTimeout(50ms) + time.Sleep(200ms) 并 select ctx.Done()
 期望：DeadlineExceeded

B. 父 WithCancel，子 WithTimeout(1s)，父先 cancel
 期望：子立刻 Done，Err 为 Canceled（父取消优先于子 timer）

C. WithTimeout 成功路径忘记 defer cancel
 观察：高频调用下 timer/子节点滞留（pprof / 泄漏检测）

D. Worker 存 ctx vs 每方法传 ctx
 对比：后者可为单次调用设更短 deadline

七、工程约定（可直接用于 Code Review）

ctx 永远是第一个参数，命名 ctx；不放结构体字段。
入站用框架/request 的 Context；出站必须向下传，禁止“半路换成 Background”除非有书面理由（如与请求脱钩的异步任务）。
每个 WithCancel / WithTimeout / WithDeadline 成对 defer cancel()。
超时预算 自上而下递减：网关 3s → 服务 2s → 下游 RPC 800ms，避免子超时大于父。
WithValue 仅 trace/auth 等横切元数据；业务输入走参数。
错误判断用 errors.Is(err, context.Canceled) / DeadlineExceeded，不要比字符串。
取消后仍需完成的短工作：新建带超时的独立 Context，并限队列，防止雪崩。
并发扇出时明确策略：全部完成 / 先胜出取消其余 / 错误阈值，并保证兄弟 goroutine 能收到取消。

八、总结

context 不是“多传一个参数”的仪式，而是 Go 并发里 跨边界的截止时间与取消协议：

取消沿 父子树 向下传播；子不能取消父；
WithTimeout / WithDeadline 用更紧的 deadline 保护尾延迟；
CancelFunc 必须调用，否则泄漏到父取消为止；
协作取消要求叶子真正监听 Done；
Context 作参数传递，不进结构体；Value 只承载请求级元数据。

把“谁拥有 cancel、超时预算如何切分、叶子是否尊重 Done”三件事写进设计与 Code Review，线上超时与 goroutine 泄漏类问题会少一个数量级。

参考资料

Go 标准库文档 — context package（Overview、WithCancel/WithTimeout/WithValue/WithoutCancel/AfterFunc/Cause、编程约定）
Go 源码 — src/context/context.go（包注释与 API 语义、Canceled/DeadlineExceeded、CancelFunc 行为）
Go Blog — Go Concurrency Patterns: Context（Context 接口、派生树、Background、服务端示例动机）
Go Blog — Contexts and structs（为何不要把 Context 存进结构体、按调用传参的生命周期清晰性）

超时 on 吾爱主机

Python asyncio 事件循环与 Task 取消：原理、API 与工程实践

一、问题背景：并发不等于多线程

二、核心模型：协作式调度 + 弱引用 Task

1. 必须“跑起来”，而不能只“创建”

2. 并发来自 Task，不是“多写几个 await”

3. 结构化并发：优先 TaskGroup（3.11+）

三、取消与超时：CancelledError 是协作信号

1. 取消发生在“下一次机会”

2. 超时：wait_for 与 timeout 上下文

3. shield：挡外层取消，不挡内层自杀

4. 可复现小实验：串行 vs 并发 vs 超时取消

四、工程实践：从入口到排障

1. 入口与生命周期

2. 阻塞调用迁出事件循环

3. 取消友好的业务骨架

4. 并发扇出模板

5. 调试开关

6. 与多线程协作时的边界

7. HTTP 扇出 + 首个成功取消其余

五、常见坑与排查清单

六、总结

参考资料

Go context 取消传播与超时控制：原理、API 与工程实践

一、问题背景：为什么需要 Context

二、核心模型：取消树 + Done 通道

三、API 速查：从根到超时

1. 取消：WithCancel / WithCancelCause

2. 超时与截止时间：WithTimeout / WithDeadline

3. 值：WithValue（窄场景）

4. 进阶：WithoutCancel 与 AfterFunc（Go 1.21+）

四、实践：HTTP 处理中的超时与协作取消

五、不要把 Context 塞进结构体

六、常见坑与排查

七、工程约定（可直接用于 Code Review）

八、总结

参考资料

3. 结构化并发：优先 `TaskGroup`（3.11+）

2. 超时：`wait_for` 与 `timeout` 上下文

3. `shield`：挡外层取消，不挡内层自杀

1. 取消：`WithCancel` / `WithCancelCause`

2. 超时与截止时间：`WithTimeout` / `WithDeadline`

3. 值：`WithValue`（窄场景）

4. 进阶：`WithoutCancel` 与 `AfterFunc`（Go 1.21+）