本文摘要FastAPI 漏写 await 会静默返回 coroutine副作用丢失。从响应体字符串、日志空白、副作用消失三种症状逐层定位。修复需对齐路由与函数的同步异步声明行为随版本变化需实测确认。一、问题与结论某 FastAPI 项目中开发者写了同步路由函数def create_order内部调用async def process_payment处理支付。接口返回 HTTP 200响应体却是{status:ok,result:coroutine object process_payment at 0x7f8a2b3c4d00}数据库中没有这笔订单支付从未执行日志里没有任何报错。客户端收到成功实际什么都没做。结论Python 的async def函数被调用时返回 coroutine 对象不会执行内部代码。coroutine 未被await驱动时函数体内的数据库写入、外部请求、异常处理全部不执行。FastAPI 不对此抛异常或打警告——它把 coroutine 对象当作普通值交给 JSON 序列化器处理。定位时需要确认两件事路由声明是def还是async def以及被调用函数声明是否为async def、调用处是否正确await。二、排查与选择依据三种症状从不同角度暴露同一个问题看到任意一个即可启动排查症状观察到的现象根因响应体出现 coroutine 字符串JSON 中有coroutine object at 0x...def路由调async def函数未 await日志零异常接口 200无 error 也无 warningcoroutine 未驱动内部try/except不触发副作用不生效数据库未写入、外部调用未发生coroutine 内部代码从未执行排查顺序看响应体。如果 JSON 中出现coroutine object ...字符串基本可以确认是 coroutine 未被 await。看路由声明。def路由在线程池中运行调用async def函数后不会自动 awaitasync def路由在事件循环中运行顶层漏await的行为依赖 FastAPI 版本。看被调用函数。只有async def函数才会返回 coroutine 对象def函数不会。看调用处。确认是否漏写await或者是否在不恰当的上下文中调用了异步函数。如果症状不明显响应体被中间件处理过或被前端框架遮蔽可以在代码中加一个临时调试端点来检查返回值类型app.get(/_debug)asyncdef_debug():resultwrite_to_db(probe)return{type:type(result).__name__,repr:repr(result)}调用后观察type字段如果输出coroutine而非str说明调用方式有问题。在代码审查中这类错误通常出现在两种过渡场景一是项目从纯同步逐步引入异步库如asyncpg、httpx.AsyncClient部分旧路由还是def二是新成员不熟悉 FastAPI 的双模式路由机制在async def路由中沿用了同步写法。两种情况下只需检查一个规则async def函数在调用处必须有await或者被传给asyncio.run()显式驱动。替代方案与取舍方案选择条件代价边界路由改async def 补await调用链全异步同步阻塞操作会阻塞事件循环适合纯异步链路同步路由中用asyncio.run()只桥接一个异步函数每次请求新建事件循环开销高不适合高并发CI 中用ruff --select ASYNC拦截合并前预防无法覆盖所有运行时场景仅作辅助手段中间件用asyncio.iscoroutine()兜底生产环境防线增加每请求开销只能发现不能预防如果路由本身就是纯同步的内部只用同步 I/O不需要改成async def。同步路由在 FastAPI 线程池中运行是设计预期不会出现本节讨论的 coroutine 问题。不要为了消除 lint 告警而强行改路由声明——这可能引入事件循环阻塞的新问题。三、关键原理FastAPI 根据路由函数声明自动选择执行机制这是框架的核心设计之一def路由放入线程池执行。线程池中调用async def函数只返回 coroutine 对象——没有事件循环来驱动它函数体内的代码一行都不会执行。async def路由在事件循环中执行。如果漏写await顶层返回的 coroutine 在部分 FastAPI 版本中可能被框架自动 await但这是 Starlette 底层的版本相关行为不能作为可靠依赖来设计代码。这个机制要求调用链的声明方式和调用方式保持一致在同步上下文中调用异步函数或在异步上下文中漏掉await都会打破这个契约。从 Python 运行时的角度看coroutine 是一个有限状态机。调用async def函数只是创建了这个状态机对象并没有开始执行。只有当事件循环或await、asyncio.run()等驱动方式将控制权交给它时状态机才会从第一步开始逐步推进。coroutine 被 garbage collected 时Python 会尝试关闭它但如果它从未执行过任何步骤这个关闭操作不会触发任何内部逻辑。关于 Python 的 RuntimeWarningcoroutine 对象被创建后如果没有被 await 也没被显式关闭Python 会在垃圾回收时触发RuntimeWarning: coroutine ... was never awaited。但这个 warning 依赖 GC 的触发时机可能在请求结束后几秒甚至更久才出现且需要将 warning 级别提升到日志配置中才能捕获——不能作为生产环境的可靠告警信号。四、可运行示例环境Python 3.11安装依赖pip install fastapi uvicornimportasynciofromfastapiimportFastAPI appFastAPI()asyncdefwrite_to_db(data:str)-str:awaitasyncio.sleep(0.1)print(f[副作用] 写入完成:{data})returnfsaved:{data}app.get(/wrong)defwrong():returnwrite_to_db(data-1)app.get(/right)asyncdefright():returnawaitwrite_to_db(data-2)操作步骤uvicorn main:app--port8000# 另开一个终端执行curlhttp://localhost:8000/wrongcurlhttp://localhost:8000/right预期输出/wrong响应体中result字段包含coroutine object ...字符串服务端终端未打印[副作用] 写入完成:>五、验证结果与边界以下结论已在 Python 3.11 FastAPI 0.115 上验证def路由调用async def函数返回值为 coroutine 对象内部代码不执行副作用完全丢失。未 await 的 coroutine 不触发内部异常处理日志零输出。async def路由中漏写await的行为依赖版本未在所有 FastAPI 版本上系统验证。不适用场景路由声明为def且内部只用同步 I/O——不存在 coroutine 问题无需改造。async def函数已通过asyncio.run()或await显式驱动——不会返回未驱动的 coroutine。使用asyncio.create_task()显式调度——task 被事件循环驱动执行不属于本文讨论的静默失败模式。关于同步路由中用asyncio.run()的一个注意事项asyncio.run()会创建一个新的事件循环执行完毕后关闭它。在低并发场景下这不是问题但在高并发下如每秒数百个请求事件循环的反复创建会增加 CPU 开销和内存分配压力。此时应考虑将路由改为async def并沿异步链路调用。思考同步路由中用asyncio.run()桥接异步库在高并发下是否值得重构为全异步链路ruff的ASYNC规则能覆盖多少实际场景能否替代部分人工 review参考资料FastAPI 官方文档 - Async / AwaitPython 3.11 asyncio 文档 - asyncio-taskruff 官方文档