starlette 本身不直接处理请求参数的类型校验,而是依赖 pydantic 库通过自定义的 request 类来实现。具体做法是创建一个继承自 starlette.requests.request 的类,并在其中定义一个名为 _data 的异步属性,该属性使用 pydantic.typeadapter 对解析后的 json 数据进行验证和转换。这样在路由函数中接收 request 对象时,访问其 .data 属性即可自动获得经过类型校验且符合预期类型的 python 对象,若数据不符合 schema 则会抛出 validationerror。

如何配置自定义 Request 类以启用自动校验
要启用这种机制,需要定义一个包含 _data 属性的子类,并将其作为参数传递给 Route 或 APIRouter。核心在于 _data 必须是一个返回协程的异步属性,它负责读取请求体、解析 JSON 并调用 TypeAdapter.validate_python 进行校验。当路由匹配到该请求时,Starlette 会实例化这个自定义 Request 类,开发者随后可以通过 request.data 获取已校验的数据。

import json
from starlette.requests import Request
from pydantic import TypeAdapter, ValidationError
class ValidatedRequest(Request):
@property
async def _data(self):
body = await self.body()
if not body:
return None
try:
data = json.loads(body)
except json.JSONDecodeError:
raise ValidationError("Invalid JSON")
# 假设我们期望一个包含 'name' (str) 和 'age' (int) 的对象
adapter = TypeAdapter(dict)
# 这里可以替换为具体的 Pydantic model 或更严格的 adapter
# 为了演示通用性,这里仅做基础结构校验示例
# 实际使用中通常传入特定的 BaseModel 子类
validated_data = adapter.validate_python(data)
return validated_data
# 在路由中使用
from starlette.routing import Route
from starlette.responses import JSONResponse
async def hello(request: ValidatedRequest):
data = request.data
name = data.get('name')
age = data.get('age')
return JSONResponse({"message": f"Hello {name}, you are {age}"})
routes = [
Route('/hello', endpoint=hello, methods=['POST']),
]
校验失败时系统如何处理异常
当请求体中的数据无法通过 TypeAdapter 的校验规则时,Pydantic 会抛出 ValidationError。由于 _data 是在异步属性中执行的,这个异常会在访问 request.data 时传播出来。Starlette 默认没有全局捕获这个特定异常的中间件,因此如果不在路由层或中间件中处理,它将导致 500 Internal Server Error。通常的做法是编写一个自定义中间件或使用 Starlette 的 exception_handler 来捕获 ValidationError,并将其转换为格式化的 422 Unprocessable Entity 响应,以便前端能够理解具体的字段错误信息。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import JSONResponse
from pydantic import ValidationError
class ValidationExceptionMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request, call_next):
try:
response = await call_next(request)
except ValidationError as e:
# 提取错误信息
errors = e.errors()
return JSONResponse(
status_code=422,
content={"detail": errors}
)
return response
# 将中间件添加到应用中
app.add_middleware(ValidationExceptionMiddleware)
TypeAdapter 与 BaseModel 在校验行为上的区别
在使用 TypeAdapter 时,它可以直接针对任意 Python 类型(如 dict, list, 甚至原生类型)进行校验,而不需要预先定义一个完整的 Pydantic Model 类。这使得它在处理动态结构或非标准输入时非常灵活。相比之下,BaseModel 要求定义一个明确的类结构,所有字段都必须有对应的类型注解。如果使用 BaseModel,校验会更严格地遵循字段定义,包括默认值处理和必填项检查。例如,对于同一个 JSON 输入,TypeAdapter(dict) 可能只校验键值对的基本类型,而 BaseModel 的子类可能会因为缺少必填字段或类型不匹配而直接拒绝整个对象。选择哪种方式取决于是否需要预定义的强类型结构以及是否希望利用 Pydantic 的字段元数据功能。










