starlette 处理复杂 query string 的核心机制依赖于底层 asgi 服务器(如 uvicorn)对 url 的解析,并通过 request 对象的 query_params 属性暴露为 queryparams 对象。开发者可以直接访问该对象获取原始参数,或结合 pydantic 模型进行自动验证与类型转换。对于嵌套结构、数组或多值参数,starlette 默认遵循标准 http 规范,即重复键名生成列表,而复杂的嵌套 json 字符串则需要手动解析。

如何获取和处理多值及重复参数
当查询字符串中包含重复的键名时,例如 ?tag=a&tag=b,Starlette 会自动将这些值聚合为一个列表。开发者可以通过 request.query_params.getlist('tag') 方法直接获取所有值组成的列表,或者使用 get() 仅获取第一个值。这种处理方式使得处理多选框或过滤条件变得非常简单,无需手动拆分字符串。

Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
from starlette.requests import Request
async def handle_multi_value(request: Request):
# 假设 URL 为 /items?category=electronics&category=books
categories = request.query_params.getlist('category')
return JSONResponse({"categories": categories})
app = Starlette(routes=[Route("/items", handle_multi_value)])
如何利用 Pydantic 验证复杂查询参数
对于需要严格类型检查和数据验证的场景,推荐使用 Pydantic 模型来定义查询参数结构。通过继承 BaseModel 并标记字段,Starlette 的路由系统可以自动将 query_params 中的值映射到模型实例中。如果参数缺失或类型不匹配,Pydantic 会抛出验证错误,从而保证进入业务逻辑的数据是安全且符合预期的。这种方法特别适用于处理分页、排序和复杂过滤条件。

from pydantic import BaseModel, Field
from typing import List, Optional
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
from starlette.requests import Request
class ProductFilter(BaseModel):
category: str
tags: List[str] = Field(default_factory=list)
min_price: Optional[float] = None
async def filter_products(request: Request, filter: ProductFilter):
# Starlette 自动注入并验证 filter 参数
result = {
"category": filter.category,
"tags": filter.tags,
"min_price": filter.min_price
}
return JSONResponse(result)
app = Starlette(routes=[Route("/products", filter_products)])
如何处理非标准的嵌套 JSON 查询参数
Starlette 原生不支持直接将 ?filter[name]=John 这样的嵌套结构解析为字典,它会将整个值视为字符串。如果需要传递复杂的嵌套对象,通常的做法是将 JSON 字符串作为单个参数的值传递,例如 ?filter={"name":"John","age":30}。在视图函数中,开发者需要手动从 request.query_params['filter'] 获取字符串,并使用 Python 的 json.loads() 进行反序列化。这种方式虽然增加了手动处理的步骤,但提供了最大的灵活性,能够应对任何深度的嵌套结构。

















