starlette 默认基于 python 的 `asyncio` 事件循环构建,因此原生支持异步请求处理,无需额外安装特殊依赖即可直接使用。要配置 starlette 以支持异步请求,只需在路由定义中使用 `async def` 声明视图函数或类方法,并确保所有 i/o 操作(如数据库查询、http 请求)均使用异步库(如 `httpx`、`aiomysql`)而非同步阻塞库。当请求进入时,starlette 会自动将异步协程挂起并交由事件循环调度,从而实现高并发下的非阻塞处理。

如何定义一个异步路由处理器
在 Starlette 中,定义异步路由处理器非常简单,只需在 `Route` 或 `APIRouter` 中指向一个标记为 `async` 的函数即可。框架会自动检测该函数的可等待性(awaitable),并在事件循环中运行它。以下是一个完整的示例程序,展示了如何创建一个包含异步 GET 和 POST 端点的 Starlette 应用,并使用 `uvicorn` 启动。
from starlette.applications import Starlette
from starlette.routing import Route, Mount
from starlette.responses import JSONResponse
import asyncio
async def homepage(request):
# 模拟异步 I/O 操作
await asyncio.sleep(0.1)
return JSONResponse({"status": "ok", "message": "Hello Async"})
async def process_data(request):
body = await request.json()
# 模拟数据处理
await asyncio.sleep(0.05)
return JSONResponse({"received": body, "processed": True})
routes = [
Route("/", endpoint=homepage),
Route("/data", endpoint=process_data, methods=["POST"]),
]
app = Starlette(routes=routes)
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
运行上述代码后,访问 `http://localhost:8000/` 将返回 JSON 响应。预期结果为:GET 请求返回 `{"status": "ok", "message": "Hello Async"}`,POST 请求到 `/data` 并携带 JSON 体时,返回包含原始数据和 `processed: true` 的响应。所有 I/O 操作均未阻塞主线程。

如何处理中间件中的异步逻辑
Starlette 的中间件同样支持异步执行。若需在请求到达路由前或响应发送后执行异步任务(如日志记录、缓存检查),应使用 `ASGIApp` 类型的异步中间件。以下代码展示了一个简单的异步认证中间件,它在请求处理前检查 Header 中的 Token,若无效则提前返回 401 错误,否则继续调用下一个 App。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
from starlette.responses import JSONResponse
import asyncio
class AuthMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
token = request.headers.get("Authorization")
if not token:
return JSONResponse({"error": "Missing token"}, status_code=401)
# 模拟异步令牌验证
await asyncio.sleep(0.01)
is_valid = token == "valid-token"
if not is_valid:
return JSONResponse({"error": "Invalid token"}, status_code=403)
response = await call_next(request)
return response
# 将中间件添加到应用中
app.add_middleware(AuthMiddleware)
此中间件通过继承 `BaseHTTPMiddleware` 并重写 `dispatch` 方法实现。注意 `dispatch` 必须是 `async` 函数,且必须 `await call_next(request)` 以获取后续处理结果。若跳过 `await`,可能导致竞态条件或资源泄漏。预期行为:无 Token 请求返回 401,Token 不为 `valid-token` 返回 403,其他请求正常通过并返回原响应。

当异步函数抛出异常时 Starlette 如何响应
在异步路由或中间件中,若未捕获的异常被抛出,Starlette 会将其转换为 HTTP 500 错误响应。例如,若在 `homepage` 函数中故意引发 `ValueError`,客户端将收到状态码 500 及默认错误页面。开发者可通过全局异常处理器自定义此类行为。以下代码演示了如何注册一个异常处理器,将特定异常映射为自定义 JSON 响应。
from starlette.exceptions import HTTPException
from starlette.requests import Request
from starlette.responses import JSONResponse
async def custom_exception_handler(request: Request, exc: Exception):
if isinstance(exc, ValueError):
return JSONResponse(
{"error": "Bad data", "detail": str(exc)},
status_code=400
)
# 其他异常保持默认 500 行为
raise exc
app.add_exception_handler(ValueError, custom_exception_handler)
添加上述处理器后,再次触发 `ValueError` 将返回 400 状态码及详细错误信息,而非通用 500 错误。这有助于前端根据状态码区分业务逻辑错误与服务器内部错误。注意:仅 `ValueError` 会被拦截,其他异常仍由默认机制处理。预期结果:调用引发 `ValueError(










