FastAPI 查询参数

FastAPI 查询参数（Query Parameters）

1. 基础用法

查询参数是 URL 中?之后的部分，FastAPI 根据函数参数自动识别：

fromfastapiimportFastAPIfromtypingimportOptional app=FastAPI()@app.get("/items")asyncdefread_items(skip:int=0,limit:int=10):return{"skip":skip,"limit":limit}

curl"http://localhost:8000/items?skip=5&limit=20"# {"skip": 5, "limit": 20}curl"http://localhost:8000/items"# {"skip": 0, "limit": 10} ← 使用默认值

参数分类规则

FastAPI 根据以下规则自动判断参数类型：

# 三种参数共存@app.get("/items/{item_id}")asyncdefread_item(item_id:int,# 路径参数（与路径变量同名）q:Optional[str]=None,# 查询参数short:bool=False,# 查询参数):return{"item_id":item_id,"q":q,"short":short}

2. 必填 vs 可选 vs 默认值

fromfastapiimportQueryfromtypingimportOptional@app.get("/items")asyncdefread_items(# 必填查询参数（无默认值）keyword:str,# 等价写法keyword:str=Query(...),# 可选查询参数（None 默认值）category:Optional[str]=None,# 等价写法category:Optional[str]=Query(default=None),# 带默认值skip:int=0,limit:int=10,):return{"keyword":keyword,"category":category,"skip":skip,"limit":limit}

# keyword 必填，缺失则 422curl"http://localhost:8000/items"# {"detail":[{"loc":["query","keyword"],"msg":"field required","type":"value_error.missing"}]}curl"http://localhost:8000/items?keyword=phone"# {"keyword":"phone","category":null,"skip":0,"limit":10}curl"http://localhost:8000/items?keyword=phone&category=electronics&skip=5"# {"keyword":"phone","category":"electronics","skip":5,"limit":10}

3. Query() 验证

字符串约束

@app.get("/search")asyncdefsearch(q:str=Query(...,min_length=1,# 最少 1 个字符max_length=50,# 最多 50 个字符pattern="^[a-zA-Z0-9 ]+$",# 正则匹配title="搜索关键词",description="输入要搜索的关键词",),):return{"q":q}

数值约束

@app.get("/items")asyncdeflist_items(skip:int=Query(default=0,ge=0),# 大于等于 0limit:int=Query(default=20,ge=1,le=100),# 1~100price_min:Optional[float]=Query(default=None,gt=0),price_max:Optional[float]=Query(default=None,gt=0),):return{"skip":skip,"limit":limit}

布尔类型自动转换

@app.get("/items")asyncdeflist_items(short:bool=False):return{"short":short}

# 以下都等价于 short=Truecurl"http://localhost:8000/items?short=true"curl"http://localhost:8000/items?short=True"curl"http://localhost:8000/items?short=1"curl"http://localhost:8000/items?short=yes"curl"http://localhost:8000/items?short=on"# 以下都等价于 short=Falsecurl"http://localhost:8000/items?short=false"curl"http://localhost:8000/items?short=0"curl"http://localhost:8000/items?short=no"

4. 多值查询参数

fromtypingimportList,Optional@app.get("/items")asyncdeflist_items(tags:List[str]=Query(default=[]),):return{"tags":tags}

curl"http://localhost:8000/items?tags=python&tags=fastapi&tags=web"# {"tags": ["python", "fastapi", "web"]}# 也可以用逗号分隔（需要声明）# tags: str = Query(default="") → 手动 split(",")

多值 + 验证

@app.get("/items")asyncdeflist_items(tags:List[str]=Query(default=[],min_length=1,# 每个值至少 1 个字符max_length=20,# 每个值最多 20 个字符),):return{"tags":tags}

5. 别名（alias）

当查询参数名不是合法的 Python 标识符时，使用别名：

@app.get("/items")asyncdeflist_items(item_type:Optional[str]=Query(default=None,alias="type",# URL 中用 type，代码中用 item_type),):return{"type":item_type}

# URL 中使用别名curl"http://localhost:8000/items?type=electronics"# {"type": "electronics"}

6. 废弃参数（deprecated）

标记参数为废弃，文档中会显示删除线，但仍可使用：

@app.get("/items")asyncdeflist_items(q:Optional[str]=Query(default=None,deprecated=True),search:Optional[str]=Query(default=None),):return{"search":search}

7. 参数排除（exclude）

从 OpenAPI 文档和验证中隐藏参数：

@app.get("/items")asyncdeflist_items(q:Optional[str]=Query(default=None,include_in_schema=False),):return{"q":q}

8. 查询参数模型

当查询参数过多时，用 Pydantic 模型组织：

frompydanticimportBaseModel,FieldfromtypingimportOptionalclassItemFilter(BaseModel):keyword:Optional[str]=Field(default=None,min_length=1,max_length=50)category:Optional[str]=Nonemin_price:Optional[float]=Field(default=None,gt=0)max_price:Optional[float]=Field(default=None,gt=0)skip:int=Field(default=0,ge=0)limit:int=Field(default=20,ge=1,le=100)@app.get("/items")asyncdeflist_items(filter:ItemFilter=Query()):# filter 是查询参数模型，不是请求体returnfilter.model_dump()

curl"http://localhost:8000/items?keyword=phone&min_price=100&max_price=500&skip=0&limit=10"# {"keyword":"phone","category":null,"min_price":100.0,"max_price":500.0,"skip":0,"limit":10}

关键：filter: ItemFilter = Query()告诉 FastAPI 这是查询参数模型，不是请求体。如果写成filter: ItemFilter则会被识别为请求体。

9. 查询参数的必填/可选总结

fromfastapiimportQueryfromtypingimportOptional@app.get("/demo")asyncdefdemo(# ── 必填 ──a:str,# 无默认值b:str=Query(...),# 显式必填# ── 可选（None） ──c:Optional[str]=None,# 简写d:str|None=None,# Python 3.10+e:Optional[str]=Query(default=None),# 显式# ── 带默认值 ──f:int=0,# 简写g:int=Query(default=10),# 显式):return{"a":a,"b":b,"c":c,"d":d,"e":e,"f":f,"g":g}

10. 实际示例：分页 + 筛选 + 排序

fromfastapiimportFastAPI,QueryfromtypingimportOptionalfromenumimportEnum app=FastAPI()classSortOrder(str,Enum):asc="asc"desc="desc"@app.get("/products")asyncdeflist_products(# 分页page:int=Query(default=1,ge=1,description="页码"),page_size:int=Query(default=20,ge=1,le=100,description="每页数量"),# 筛选keyword:Optional[str]=Query(default=None,min_length=1,max_length=100,description="搜索关键词",),category:Optional[str]=Query(default=None,description="商品分类"),min_price:Optional[float]=Query(default=None,gt=0,description="最低价格"),max_price:Optional[float]=Query(default=None,gt=0,description="最高价格"),in_stock:Optional[bool]=Query(default=None,description="仅显示有货"),# 排序sort_by:Optional[str]=Query(default="created_at",description="排序字段"),sort_order:SortOrder=Query(default=SortOrder.desc,description="排序方向"),# 标签（多值）tags:list[str]=Query(default=[],description="标签筛选"),):offset=(page-1)*page_sizereturn{"pagination":{"page":page,"page_size":page_size,"offset":offset},"filters":{"keyword":keyword,"category":category,"price_range":[min_price,max_price],"in_stock":in_stock,"tags":tags,},"sort":{"by":sort_by,"order":sort_order},}

curl"http://localhost:8000/products?page=2&page_size=10&keyword=phone&min_price=100&max_price=999&tags=5g&tags=flagship&sort_by=price&sort_order=asc"

速查表

总结：查询参数的核心是URL?key=value+ 函数默认值/类型注解自动识别。Query()提供验证约束和文档元数据，Optional或默认值控制必填/可选，List处理多值，alias解决命名冲突，Pydantic 模型组织复杂参数。FastAPI 的自动识别规则让简单场景零配置，复杂场景有Query()兜底。