FastAPI中Pydantic模型作为查询参数及Enum支持问题求解

FastAPI 原生支持直接将Pydantic模型作为查询参数，无需借助Depends，同时完美兼容Enum类型校验，以下是具体实现方案：

1. 基础实现代码 #

from fastapi import FastAPI
from pydantic import BaseModel
from enum import Enum

# 定义Enum类型
class SortDirection(str, Enum):
    ASC = "asc"
    DESC = "desc"

# 定义查询参数对应的Pydantic模型
class ItemQueryParams(BaseModel):
    # 给所有字段设置默认值，确保查询参数可选
    page: int = 1
    page_size: int = 10
    sort_by: str = "id"
    sort_dir: SortDirection = SortDirection.ASC  # 直接使用Enum作为字段类型
    search: str | None = None

app = FastAPI()

# 路径操作函数中直接声明模型参数
@app.get("/items/")
async def list_items(query: ItemQueryParams):
    return {
        "request_query": query.dict(),
        "data": []  # 替换为实际业务逻辑
    }

2. 增强：添加校验与元数据 #

如果需要给查询参数添加校验规则、描述信息或别名，可以结合Pydantic的Field或FastAPI的Query：

from pydantic import BaseModel, Field
from fastapi import Query

class ItemQueryParams(BaseModel):
    page: int = Field(1, ge=1, description="当前页码，最小值为1")
    page_size: int = Field(10, ge=1, le=100, description="每页条数，范围1-100")
    sort_by: str = Field("id", description="排序字段名")
    sort_dir: SortDirection = Field(SortDirection.ASC, description="排序方向，可选asc/desc")
    # 用Query自定义查询参数的别名
    search_key: str | None = Query(None, alias="search", description="搜索关键词")

3. 核心特性说明 #

• Enum自动校验：当传入的sort_dir不是asc或desc时，FastAPI会自动返回422参数校验错误，无需额外处理。
• 模型字段映射：Pydantic模型的每个字段会自动映射为一个独立的查询参数，比如page对应?page=2，sort_dir对应?sort_dir=desc。
• 嵌套模型支持：如果模型包含嵌套结构，FastAPI会自动解析为点分隔的查询参数（比如user.name对应?user.name=xxx）。

注意事项 #

• 所有查询参数字段建议设置默认值，避免必填参数导致的请求失败（查询参数通常为可选）。
• Enum类型必须继承自str或int，确保FastAPI能正确将URL中的字符串/数值转换为Enum实例。
• 该特性要求FastAPI版本≥0.95.0（更早版本可能需要通过Depends间接实现，建议升级到最新稳定版）。

内容的提问来源于stack exchange，提问作者innicoder