这套教程怎么学

这套教程假设你已经会写普通 Python 程序，知道函数调用、异常、列表、字典、文件 I/O、网络请求大概是什么；也假设你听过线程和进程，但不要求你写过线上并发服务。

读完以后，你要能做这几件事：

1. 用 asyncio.run()、async def、await、create_task()、gather()、TaskGroup 写出不乱的并发 I/O 代码。
2. 解释事件循环、协程对象、Future、Task、Handle、TimerHandle、selector 分别在什么时候出现。
3. 看懂 CPython Lib/asyncio 里的几个入口，知道一次 await asyncio.sleep() 或一次 create_task() 大概经过哪些文件。
4. 运行并理解本仓库的 mini_asyncio，它用少量标准库代码复现事件循环、Future、Task、定时器、socket I/O 和异步 Queue。

建议顺序

阶段	学习目标	对应章节
第 1 阶段	知道 asyncio 适合解决哪类等待问题，分清 coroutine、Future、Task	起步
第 2 阶段	跟着写 11 个小程序：先并发等待，再限流、超时、Queue、Streams、调试	练习代码
第 3 阶段	再看事件循环怎样等定时器和 socket，又怎样让 Task 继续往下跑	运行过程
第 4 阶段	手写一个教学版事件循环，把前面的例子换成自己的代码跑	Mini Asyncio

项目目录

.
├── docs/
│   ├── guide/                 # 基础概念、运行机制和源码阅读
│   ├── labs/                  # 标准库 asyncio 小实验
│   ├── mini-asyncio/          # 教学版运行时实现
│   └── references/            # 资料、术语和 FAQ
├── examples/
│   ├── asyncio_demos/         # 官方 asyncio API 风格 Demo
│   └── mini_asyncio_runtime/  # 教学版 mini_asyncio
├── package.json
└── README.md

为什么按这个顺序讲

Python 文档适合查 API。直接拿它当入门材料，容易卡在几处：

• async def、coroutine、Task、Future 这些词会同时出现，很难分清谁是谁。
• 示例通常很短，知道能跑，但不知道为什么这样写。
• 事件循环 API 很多，直接读源码容易把 selector、callback、Task 混在一起。

所以这里按写代码时会遇到的问题讲：

每章大致这样安排：

1. 先说这一节要解决的具体问题。
2. 跑一个本地 Demo。
3. 用图说明这段代码怎样停下、怎样继续。
4. 列出容易写错的地方。
5. 留一个小改动，让你验证自己的理解。

环境准备

教程站点使用 VitePress：

npm install
npm run docs:dev

标准库 asyncio Demo 不需要第三方 Python 依赖。本教程按 Python 3.12+ 来写；如果你用 uv，可以单独建一个 3.12 或更新版本的环境。TaskGroup 和 asyncio.timeout() 从 3.11 开始可用，教程示例统一按 3.12+ 讲。

python3 examples/asyncio_demos/01_hello_async.py
python3 examples/asyncio_demos/04_limited_gather_semaphore.py
python3 examples/asyncio_demos/07_taskgroup_failure.py

教学版 mini_asyncio 只依赖 Python 标准库：

python3 -m unittest discover -s examples/mini_asyncio_runtime/tests
python3 examples/mini_asyncio_runtime/demos/01_tasks.py

学习方法

不要只看输出。每次运行 Demo 后，打开源码把 await 出现的位置标出来。asyncio 程序好不好懂，很多时候取决于你是否看清了“程序在哪些 await 位置暂停，事件循环什么时候让它继续”。