starlette 处理请求超时主要依赖 asgi 服务器的配置,而非框架内部逻辑。开发者需要在启动命令中设置 timeout 参数,例如使用 uvicorn 时指定 --timeout-keep-alive 或针对特定应用的超时限制。当请求处理时间超过设定值时,服务器会主动断开连接并返回错误,确保资源不被长期占用。

Uvicorn 如何配置全局超时
在开发或部署环境中,通过命令行参数直接控制超时时间是最高效的方式。使用 uvicorn 启动应用时,可以通过 --timeout-keep-alive 设置保持连接的超时时间,或者通过环境变量 UVICORN_TIMEOUT_KEEP_ALIVE 进行配置。默认情况下,Uvicorn 的 keep-alive 超时为 5 秒,这意味着如果客户端在 5 秒内没有发送新请求,连接将被关闭。对于长轮询或 SSE 场景,需要适当增加此值。

uvicorn main:app --host 0.0.0.0 --port 8000 --timeout-keep-alive 60
上述命令将 keep-alive 超时设置为 60 秒。在实际运行中,如果客户端在建立连接后 60 秒内未发送任何数据,Uvicorn 将终止该连接。这有助于防止空闲连接占用服务器资源。需要注意的是,这个设置仅影响 HTTP/1.1 的 keep-alive 行为,不影响请求处理的总时长。
ASGI 中间件如何实现自定义超时
除了服务器层面的配置,Starlette 允许通过中间件实现更细粒度的超时控制。开发者可以创建一个自定义中间件,在请求处理过程中监控耗时,并在超过阈值时抛出异常或提前终止响应。这种方式适用于需要针对不同路由或特定业务逻辑设置不同超时的场景。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

import time
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import Response
class TimeoutMiddleware(BaseHTTPMiddleware):
def __init__(self, app, timeout=10):
super().__init__(app)
self.timeout = timeout
async def dispatch(self, request, call_next):
start_time = time.time()
try:
response = await call_next(request)
process_time = time.time() - start_time
if process_time > self.timeout:
return Response(content="Request timed out", status_code=408)
return response
except Exception as e:
return Response(content=str(e), status_code=500)
app.add_middleware(TimeoutMiddleware, timeout=5)
该中间件在每个请求处理前后记录时间戳,计算处理耗时。如果耗时超过设定的 timeout 值(默认为 10 秒),则返回 408 状态码及错误信息。这种机制允许开发者在不修改具体视图逻辑的情况下,统一控制请求的处理时限。需要注意的是,中间件中的超时检查是在请求处理完成后进行的,因此无法中断正在进行的长时间操作,只能用于事后判断和响应。
如何处理长时间运行的异步任务超时
当 Starlette 应用中包含长时间运行的异步任务(如数据库查询、外部 API 调用)时,简单的中间件超时可能不足以应对。此时可以使用 Python 的 asyncio.wait_for 函数来包装异步操作,设置具体的等待超时时间。如果在指定时间内任务未完成,将抛出 asyncio.TimeoutError,开发者可以在中间件或视图中捕获该异常并进行相应处理。
import asyncio
from starlette.applications import Starlette
from starlette.routing import Route
from starlette.responses import JSONResponse
async def long_running_task(request):
try:
# 模拟一个耗时操作
result = await asyncio.wait_for(asyncio.sleep(15), timeout=5)
return JSONResponse({"status": "completed"})
except asyncio.TimeoutError:
return JSONResponse({"status": "timed_out"}, status_code=408)
routes = [
Route("/task", long_running_task),
]
app = Starlette(routes=routes)
在上述代码中,asyncio.wait_for 设置了 5 秒的超时限制。如果 asyncio.sleep(15) 在 5 秒内未完成,将触发 TimeoutError,并被捕获后返回 408 状态码。这种方式比中间件级别的超时更精确,因为它直接作用于具体的异步操作,而不是整个请求生命周期。开发者可以根据业务需求,为不同的异步任务设置不同的超时策略,从而提高系统的稳定性和响应速度。

















