普通函数从第一行开始执行,直到返回结果或抛出异常。调用方会停在函数调用的位置,等函数结束后再继续:
01def greet(name): 02 print("函数开始") 03 result = f"你好,{name}" 04 print("函数结束") 05 return result 06 07print("调用之前") 08message = greet("小明") 09print("调用之后") 10print(message)
输出顺序是:
1调用之前 2函数开始 3函数结束 4调用之后 5你好,小明
greet("小明") 会立即进入函数体。调用方拿到的是函数执行完成后的字符串,而不是函数本身。
greet("小明")
协程与普通函数最大的区别,是协程可以在执行过程中暂停,并在等待的结果准备好后恢复。这个能力让同一个线程可以在等待期间处理其他任务。
使用 async def 定义协程函数:
async def
1async def greet(name): 2 print("协程开始") 3 return f"你好,{name}" 4 5coroutine = greet("小明") 6print(type(coroutine).__name__) # coroutine
这里需要区分两个概念:
greet
调用普通函数会立即执行函数体,调用协程函数则只会创建协程对象。所以下面的代码不会输出「协程开始」:
1async def greet(): 2 print("协程开始") 3 4print("创建之前") 5coroutine = greet() 6print("创建之后") 7 8coroutine.close() # 示例没有运行协程,主动关闭以释放它
协程对象可以理解为「这段异步工作的一次执行计划」。创建它之后,还需要使用 await 等待,或者把它包装成 Task 交给事件循环调度,函数体才会真正开始执行。
await
如果只创建协程对象却没有等待、调度或关闭它,程序结束时通常会看到:
1RuntimeWarning: coroutine 'greet' was never awaited
这个警告表示异步函数虽然被调用了,但对应的工作从未真正执行。
协程不是只能执行一次的普通代码块,它具有暂停和恢复的能力。一次协程调用通常经历以下过程:
下面通过日志观察暂停和恢复:
01import asyncio 02 03async def fetch(): 04 print("2. fetch 开始") 05 await asyncio.sleep(1) 06 print("4. fetch 恢复") 07 return "请求结果" 08 09async def main(): 10 print("1. 准备等待 fetch") 11 result = await fetch() 12 print("5. main 恢复") 13 print(result) 14 15asyncio.run(main())
fetch() 运行到 await asyncio.sleep(1) 时暂停。一秒后,事件循环让它继续执行。代码的实际输出是:
fetch()
await asyncio.sleep(1)
11. 准备等待 fetch 22. fetch 开始 34. fetch 恢复 45. main 恢复 5请求结果
在第二行和第四行之间,fetch() 处于暂停状态,事件循环可以处理其他任务。协程暂停时会保留当前执行位置和局部变量,恢复后不需要从函数第一行重新开始。
await 只能写在 async def 中,用于等待一个可等待对象(awaitable)。常见的可等待对象包括:
执行 await read_cache() 时,并不是一看到 await 就立即切换到另一个任务。控制权会先进入 read_cache():
await read_cache()
read_cache()
01import asyncio 02 03async def read_cache(): 04 print("2. 进入 read_cache") 05 await asyncio.sleep(1) 06 print("3. read_cache 恢复") 07 return "缓存数据" 08 09async def main(): 10 print("1. main 开始") 11 result = await read_cache() 12 print("4. main 恢复") 13 print(result) 14 15asyncio.run(main())
调用过程是:
main()
因此,真正让控制权回到事件循环的,是协程调用链遇到一个尚未完成、需要等待的操作。如果被等待的协程可以立即计算并返回,整个调用链可能会连续执行,中间没有机会切换其他任务。
await 不会创建线程,也不会自动让代码在后台运行。它表达的是「当前协程依赖这个结果,可以暂停等待」。
异步代码不一定并发。连续直接等待两个协程时,第二个协程必须等第一个协程结束后才会创建并运行:
01import asyncio 02import time 03 04async def fetch(name): 05 print(f"{name} 开始") 06 await asyncio.sleep(1) 07 print(f"{name} 完成") 08 return name 09 10async def main(): 11 started_at = time.perf_counter() 12 13 first = await fetch("任务一") 14 second = await fetch("任务二") 15 16 elapsed = time.perf_counter() - started_at 17 print(first, second) 18 print(f"耗时约 {elapsed:.1f} 秒") 19 20asyncio.run(main())
两个任务各等待 1 秒,总耗时接近 2 秒。这里使用了协程和 await,但执行关系仍然是串行的。
如果两个任务相互独立,可以把它们同时交给事件循环:
01import asyncio 02import time 03 04async def fetch(name): 05 print(f"{name} 开始") 06 await asyncio.sleep(1) 07 print(f"{name} 完成") 08 return name 09 10async def main(): 11 started_at = time.perf_counter() 12 13 first, second = await asyncio.gather( 14 fetch("任务一"), 15 fetch("任务二"), 16 ) 17 18 elapsed = time.perf_counter() - started_at 19 print(first, second) 20 print(f"耗时约 {elapsed:.1f} 秒") 21 22asyncio.run(main())
两个任务的等待时间可以重叠,总耗时接近 1 秒。这里先建立「直接 await 通常保持调用顺序,显式调度多个协程才能形成并发」的认识;Task、gather() 和任务取消会在后续文章中详细讲解。
gather()
协程使用 return 返回结果。等待它的调用方会得到这个值:
return
01import asyncio 02 03async def add(left, right): 04 return left + right 05 06async def main(): 07 result = await add(2, 3) 08 print(result) # 5 09 10asyncio.run(main())
如果协程抛出异常,异常会沿着 await 调用关系传递给等待者,可以使用普通的 try...except 处理:
try...except
01import asyncio 02 03async def divide(left, right): 04 if right == 0: 05 raise ValueError("除数不能为 0") 06 07 return left / right 08 09async def main(): 10 try: 11 result = await divide(1, 0) 12 print(result) 13 except ValueError as error: 14 print(error) 15 16asyncio.run(main())
这里不需要为了“让函数变异步”而添加无意义的 await asyncio.sleep(0)。async def 已经定义了协程函数;是否需要 await,取决于函数内部是否真的要等待异步操作。
await asyncio.sleep(0)
一个协程对象表示一次执行,完成后不能再次等待:
01import asyncio 02 03async def get_message(): 04 return "你好" 05 06async def main(): 07 coroutine = get_message() 08 print(await coroutine) 09 # print(await coroutine) # RuntimeError:不能重复使用已等待的协程 10 11asyncio.run(main())
如果需要多次执行,应多次调用协程函数,分别创建新的协程对象。
观察协程对象创建时、被等待后和再次等待时的真实状态。
入口和主题代码与工作区直接共用同一份来源:
01from fastapi import FastAPI, Query 02 03from coroutines import run_experiment 04 05app = FastAPI(title="Python 协程") 06 07@app.get("/coroutines") 08async def experiment( 09 name: str = Query(default="小微", min_length=1, max_length=40), 10) -> dict[str, object]: 11 report = await run_experiment(name) 12 print(report) 13 return report 14
01import asyncio 02import inspect 03 04async def run_experiment(name: str) -> dict[str, object]: 05 events = [] 06 07 async def greet() -> str: 08 events.append("协程开始") 09 await asyncio.sleep(0.01) 10 events.append("协程恢复") 11 return f"你好,{name}" 12 13 coroutine = greet() 14 before = {"state": inspect.getcoroutinestate(coroutine), "events": events.copy()} 15 result = await coroutine 16 after = inspect.getcoroutinestate(coroutine) 17 try: 18 await coroutine 19 except RuntimeError as error: 20 reuse_error = type(error).__name__ 21 return {"before_await": before, "result": result, "after_await": after, 22 "events": events, "reuse_error": reuse_error} 23
打开在线案例,点击运行,等待环境就绪,再发送默认 GET /coroutines?name=小微。本篇无需密钥或外部服务。
GET /coroutines?name=小微
before_await.state 为 CORO_CREATED,此时 events 是空列表;结果为 "你好,小微",结束状态为 CORO_CLOSED。第二次等待同一个协程的 RuntimeError 已捕获并作为观察结果返回。
before_await.state
CORO_CREATED
events
"你好,小微"
CORO_CLOSED
RuntimeError
修改名字会改变回复;空名字和超过 40 字符的名字返回 422。错误实验不会使整个请求失败,也不会留下未等待的协程。
实验事件和状态每次请求独立创建。实际定时与耗时会受到运行环境影响,不能据此承诺固定调度顺序或实时精度。日志输出本次报告,可以在修改参数后对照查看。
下载项目后,在本机终端执行:
1uv run fastapi dev main.py
然后通过 http://127.0.0.1:8000/docs 发送同一请求。文章中的 asyncio.run(...) 是独立终端脚本入口;浏览器和 FastAPI 接口已经有事件循环,这里的案例直接 await 实验函数。
http://127.0.0.1:8000/docs
asyncio.run(...)
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 函数
普通函数从第一行开始执行,直到返回结果或抛出异常。调用方会停在函数调用的位置,等函数结束后再继续:
输出顺序是:
greet("小明")会立即进入函数体。调用方拿到的是函数执行完成后的字符串,而不是函数本身。协程与普通函数最大的区别,是协程可以在执行过程中暂停,并在等待的结果准备好后恢复。这个能力让同一个线程可以在等待期间处理其他任务。
使用
async def定义协程函数:这里需要区分两个概念:
greetasync def定义的函数greet("小明")调用普通函数会立即执行函数体,调用协程函数则只会创建协程对象。所以下面的代码不会输出「协程开始」:
协程对象可以理解为「这段异步工作的一次执行计划」。创建它之后,还需要使用
await等待,或者把它包装成 Task 交给事件循环调度,函数体才会真正开始执行。如果只创建协程对象却没有等待、调度或关闭它,程序结束时通常会看到:
这个警告表示异步函数虽然被调用了,但对应的工作从未真正执行。
2. 生命周期
协程不是只能执行一次的普通代码块,它具有暂停和恢复的能力。一次协程调用通常经历以下过程:
await或包装成 Task,开始运行;await后面继续;下面通过日志观察暂停和恢复:
fetch()运行到await asyncio.sleep(1)时暂停。一秒后,事件循环让它继续执行。代码的实际输出是:在第二行和第四行之间,
fetch()处于暂停状态,事件循环可以处理其他任务。协程暂停时会保留当前执行位置和局部变量,恢复后不需要从函数第一行重新开始。3. await
await只能写在async def中,用于等待一个可等待对象(awaitable)。常见的可等待对象包括:执行
await read_cache()时,并不是一看到await就立即切换到另一个任务。控制权会先进入read_cache():调用过程是:
main()执行到await read_cache();read_cache()开始运行;read_cache()执行到尚未完成的await asyncio.sleep(1);read_cache()和等待它的main()都暂时不能继续;read_cache()先恢复并返回结果;main()得到结果,再从自己的await后面恢复。因此,真正让控制权回到事件循环的,是协程调用链遇到一个尚未完成、需要等待的操作。如果被等待的协程可以立即计算并返回,整个调用链可能会连续执行,中间没有机会切换其他任务。
await不会创建线程,也不会自动让代码在后台运行。它表达的是「当前协程依赖这个结果,可以暂停等待」。4. 串行
异步代码不一定并发。连续直接等待两个协程时,第二个协程必须等第一个协程结束后才会创建并运行:
两个任务各等待 1 秒,总耗时接近 2 秒。这里使用了协程和
await,但执行关系仍然是串行的。如果两个任务相互独立,可以把它们同时交给事件循环:
两个任务的等待时间可以重叠,总耗时接近 1 秒。这里先建立「直接
await通常保持调用顺序,显式调度多个协程才能形成并发」的认识;Task、gather()和任务取消会在后续文章中详细讲解。5. 结果
协程使用
return返回结果。等待它的调用方会得到这个值:如果协程抛出异常,异常会沿着
await调用关系传递给等待者,可以使用普通的try...except处理:这里不需要为了“让函数变异步”而添加无意义的
await asyncio.sleep(0)。async def已经定义了协程函数;是否需要await,取决于函数内部是否真的要等待异步操作。一个协程对象表示一次执行,完成后不能再次等待:
如果需要多次执行,应多次调用协程函数,分别创建新的协程对象。
6. 在线实验
观察协程对象创建时、被等待后和再次等待时的真实状态。
入口和主题代码与工作区直接共用同一份来源:
打开在线案例,点击运行,等待环境就绪,再发送默认
GET /coroutines?name=小微。本篇无需密钥或外部服务。before_await.state为CORO_CREATED,此时events是空列表;结果为"你好,小微",结束状态为CORO_CLOSED。第二次等待同一个协程的RuntimeError已捕获并作为观察结果返回。修改名字会改变回复;空名字和超过 40 字符的名字返回 422。错误实验不会使整个请求失败,也不会留下未等待的协程。
实验事件和状态每次请求独立创建。实际定时与耗时会受到运行环境影响,不能据此承诺固定调度顺序或实时精度。日志输出本次报告,可以在修改参数后对照查看。
下载项目后,在本机终端执行:
然后通过
http://127.0.0.1:8000/docs发送同一请求。文章中的asyncio.run(...)是独立终端脚本入口;浏览器和 FastAPI 接口已经有事件循环,这里的案例直接await实验函数。