starlette 本身不内置复杂的表单验证库,而是通过 request 对象的 form() 方法获取原始数据,再结合第三方库如 pydantic 进行结构化校验。具体做法是:在路由中调用 await request.form() 获取 multidict 对象,将其作为参数传入 pydantic 模型实例化,利用模型的 validate() 或类型转换机制自动完成验证并抛出异常。

如何获取和解析表单数据
要处理表单,首先需要从请求中提取数据。Starlette 的 Request 对象提供了 form() 异步方法,它会自动处理 multipart/form-data 和 application/x-www-form-urlencoded 内容。该方法返回一个类似字典的对象,支持键值对访问。如果表单字段缺失,直接访问会引发 KeyError,因此通常建议配合默认值或异常捕获使用。

from starlette.requests import Request
from starlette.responses import PlainTextResponse
from starlette.routing import Route, Router
async def handle_form(request: Request):
try:
# 获取表单数据
form_data = await request.form()
username = form_data.get("username", "guest")
email = form_data.get("email")
if not email:
return PlainTextResponse("Email is required", status_code=400)
return PlainTextResponse(f"Hello {username}, verified email: {email}")
except Exception as e:
return PlainTextResponse(f"Error: {str(e)}", status_code=500)
router = Router(routes=[Route("/submit", handle_form, methods=["POST"])])
上述代码展示了基本的数据提取流程。注意 form_data.get() 比直接索引更安全,因为它在键不存在时不会报错。在实际应用中,我们很少只停留在字符串层面,通常需要验证数据的格式和类型。
如何使用Pydantic进行强类型验证
为了获得可靠的验证,最佳实践是将提取出的表单数据映射到 Pydantic 模型。Pydantic 会在实例化时自动执行类型检查和约束验证。如果数据不符合模型定义,它会抛出 ValidationError。我们需要在路由层捕获这个异常并返回友好的错误响应。这种方式将验证逻辑与业务逻辑分离,使代码更清晰。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from pydantic import BaseModel, EmailStr, Field
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.exceptions import HTTPException
import json
class UserRegistration(BaseModel):
username: str = Field(..., min_length=3, max_length=20)
email: EmailStr
age: int = Field(..., ge=18, le=120)
async def validate_with_pydantic(request: Request):
try:
form_data = await request.form()
# 将 MultiDict 转换为字典以适配 Pydantic
data = dict(form_data)
user = UserRegistration(**data)
return JSONResponse({"status": "success", "user": user.dict()})
except Exception as e:
# 捕获 Pydantic 验证错误
if hasattr(e, 'errors'):
errors = e.errors()
return JSONResponse({"status": "error", "details": errors}, status_code=422)
raise HTTPException(status_code=500, detail=str(e))
在这个例子中,UserRegistration 模型定义了严格的规则:username 长度限制、email 必须是合法邮箱格式、age 必须在 18 到 120 之间。当提交不符合这些条件的数据时,Pydantic 会生成详细的错误信息列表,包含每个字段的错误描述和位置。开发者可以直接将这些信息返回给前端,实现精确的错误提示。
当表单缺少必填字段时会发生什么
如果提交的表单中缺少 username、email 或 age 等必填字段,Pydantic 在实例化模型时会立即失败。因为我们在模型定义中使用了 Field(...) 表示必填项,且没有提供默认值。此时,dict(form_data) 生成的字典中将缺少相应的键,导致 **data 解包时触发 TypeError 或者 Pydantic 内部的验证错误。具体行为取决于 Pydantic 版本,但在 v1/v2 中,缺失必填字段通常会被归类为验证错误(Validation Error),而不是普通的 Python 类型错误。这意味着我们的异常处理块能统一捕获这些情况,并返回结构化的错误信息,告知用户哪些字段缺失或无效。










