FastAPI怎么设置请求超时时间-Python教程-PHP中文网

fastapi本身不内置请求超时控制，必须由uvicorn（如--timeout参数）、starlette的timeoutmiddleware中间件或业务代码（如asyncio.wait_for）显式实现；@app.get不支持timeout=参数。

fastapi怎么设置请求超时时间

FastAPI 本身不内置请求超时控制逻辑，超时必须由 ASGI 服务器（如 Uvicorn）、中间件或业务代码显式介入。直接在 @app.get 装饰器里加 timeout= 参数是无效的 —— 那个参数并不存在。

Uvicorn 启动参数决定底层连接与请求生命周期

绝大多数 FastAPI 应用跑在 Uvicorn 上，它的 --timeout-keep-alive 和 --timeout-graceful-shutdown 控制连接复用和进程退出，但真正影响“单个请求被强制终止”的是 --timeout（即 timeout 参数，非 keep-alive）。

--timeout 30：表示请求处理超过 30 秒，Uvicorn 会主动 kill 当前 worker 协程，并返回 504 Gateway Timeout（如果反向代理存在）或直接断连
这个超时是硬性中断，不触发 Python 层的 asyncio.TimeoutError，无法被捕获或清理资源
它作用于整个 ASGI scope 生命周期，包括中间件、路由、依赖项、响应生成全过程
若你用 gunicorn + uvicorn.workers.UvicornWorker，需通过 gunicorn 的 --timeout 传递，行为略有差异（更偏向 worker 进程级）

Starlette TimeoutMiddleware 提供可捕获的 HTTP 层超时

相比 Uvicorn 硬中断，TimeoutMiddleware 在 ASGI 中间件层拦截，能抛出 starlette.exceptions.HTTPException(status_code=504)，允许你自定义响应体、记录日志或触发清理逻辑。

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

它包装的是整个请求生命周期，但异常可被 try/except 捕获（需在更高层中间件或全局异常处理器中）
超时后，后台任务（BackgroundTasks）默认仍继续执行 —— TimeoutMiddleware 不取消它们

示例：

from starlette.middleware.timeout import TimeoutMiddleware
app.add_middleware(TimeoutMiddleware, timeout=8)

注意：该中间件对 WebSocket 路由无效；且若路由内有阻塞同步调用（如 time.sleep()），它无法中断线程，只对 async 控制流有效

路由内用 `asyncio.wait_for` 或 `anyio.move_on_after` 精确控制某段逻辑

当你只想给数据库查询、外部 API 调用或文件处理设限，而不是整条请求链路，就该在函数内部做超时封装。这是最灵活、也最易出错的方式。

asyncio.wait_for(coro, timeout=5.0)：原生支持，但仅适用于协程对象；超时抛 asyncio.TimeoutError，需手动 except
anyio.move_on_after(5)：推荐，兼容更多异步运行时（包括 Uvicorn 默认的 asyncio），语法更清晰，且自动处理取消传播
错误示范：在 BackgroundTasks.add_task() 里传入一个已用 wait_for 包裹的函数 —— 这不会让后台任务本身受超时约束，只是那个函数内部可能提前退出
关键点：超时后，被中断的协程若持有数据库连接、文件句柄或锁，必须确保 finally 或异步上下文管理器（async with）能正常释放

别忽略客户端与反向代理的超时叠加效应

一个请求实际卡住，往往不是 FastAPI 没设超时，而是 Nginx、Cloudflare、Postman 或前端 fetch 的 signal.timeout() 先断开了连接。

Nginx 默认 proxy_read_timeout 60，若你 Uvicorn 设了 --timeout 120，但 Nginx 在 60 秒就关连接，用户看到的是 504，而 FastAPI 日志里可能没报错
Postman 的全局超时在 Settings → General → Request timeout in ms，默认 0（无限），但生产环境务必设为略大于服务端超时值
前端调用时，fetch(url, { signal: AbortSignal.timeout(8000) }) 是现代标准，比旧版 timeout 选项更可靠
最容易被忽略的是：Uvicorn 的 --timeout 和中间件 TimeoutMiddleware 同时启用时，谁先触发取决于具体耗时路径 —— 它们互不感知，可能得到两种不同错误码（504 vs 自定义 JSON）