什么是查询参数？
在 FastAPI 中，当声明的参数不是路径参数时，路径操作函数会自动将其解释为查询参数。
查询字符串是键值对的集合，位于 URL 的 ? 之后，以 & 分隔。例如：
http://127.0.0.1:8000/items/?page=1&limit=10在这个 URL 中：
page=1和limit=10就是查询参数?开始查询参数部分&分隔不同的参数
基础用法
1. 必需查询参数
from fastapi import FastAPI
app = FastAPI()
@app.get("/query1")
def page_limit(page, limit):
return {"page": page, "limit": limit}测试：
✅
http://127.0.0.1:8000/query1?page=1&limit=10❌
http://127.0.0.1:8000/query1?page=1(缺少必需参数limit)
在这种情况下，page 和 limit 都是必需参数，如果缺少任何一个，FastAPI 会自动返回错误响应。
2. 可选查询参数
@app.get("/query2")
def page_limit2(page, limit=None):
if limit:
return {"page": page, "limit": limit}
return {"page": page}测试：
✅
http://127.0.0.1:8000/query2?page=1&limit=10✅
http://127.0.0.1:8000/query2?page=1
通过给参数设置默认值（如 limit=None），可以将其变为可选参数。
3. 类型注解的查询参数
@app.get("/query3")
def page_limit3(page, limit, info: int):
return {"page": page, "limit": limit, "info": info}测试：
✅
http://127.0.0.1:8000/query3?page=1&limit=10&info=5❌
http://127.0.0.1:8000/query3?page=1&limit=10&info=abc(类型错误)
使用类型注解后，FastAPI 会自动进行类型验证和转换。
4. 混合路径参数和查询参数
@app.get("/query4/{page}")
def page_limit4(page, limit, info: int):
return {"page": page, "limit": limit, "info": info}测试：
✅
http://127.0.0.1:8000/query4/1?limit=10&info=5
这里 page 是路径参数，limit 和 info 是查询参数。
高级特性
类型验证和自动转换
FastAPI 利用 Python 的类型提示提供强大的类型验证：
from typing import Optional
@app.get("/advanced")
def advanced_query(
page: int, # 必需整数参数
limit: Optional[int] = 10, # 可选整数参数，默认值10
search: Optional[str] = None, # 可选字符串参数
active: bool = True # 布尔参数，默认True
):
return {
"page": page,
"limit": limit,
"search": search,
"active": active
}测试示例：
http://127.0.0.1:8000/advanced?page=1http://127.0.0.1:8000/advanced?page=1&limit=20&search=test&active=false
多个值查询参数
对于同一个参数名传递多个值的情况：
from typing import List
@app.get("/multi")
def multi_values(tags: List[str] = []):
return {"tags": tags}测试：
http://127.0.0.1:8000/multi?tags=python&tags=fastapi&tags=web
使用 Pydantic 模型进行复杂验证
from pydantic import BaseModel, conint
class QueryParams(BaseModel):
page: conint(ge=1) = 1 # 大于等于1的整数
limit: conint(ge=1, le=100) = 10 # 1-100之间的整数
sort: str = "desc"
@app.get("/validated")
def validated_query(params: QueryParams):
return params.dict()最佳实践
1. 始终使用类型注解
# 推荐
def get_items(page: int, limit: int = 10):
# 不推荐
def get_items(page, limit=10):2. 提供合理的默认值
def get_items(
page: int = 1,
limit: int = 10,
sort: str = "created_at",
order: str = "desc"
):3. 使用有意义的参数名
# 推荐
def search_products(query: str, category: str = None):
# 不推荐
def sp(q: str, c: str = None):错误处理
FastAPI 自动处理各种错误情况：
缺少必需参数：返回 422 状态码
类型错误：返回 422 状态码并显示详细错误信息
验证错误：返回详细的错误信息