FastAPI中使用Pydantic模型结合Depends无法解析List[int]类型多值查询参数的问题

我之前碰到过一模一样的问题，FastAPI默认情况下，当你把Pydantic模型作为Depends()的参数接收查询参数时，不会自动把重复的查询键（比如industries=4&industries=5）解析成列表。这是因为Pydantic本身没意识到这是查询参数的多值场景，得我们明确告诉FastAPI该怎么处理这个字段。

下面给你两种可行的解决办法：

方法1：在Pydantic模型字段中使用Query #

你可以在模型的industries字段上用Query来指定它是多值参数，同时设置默认值为None或者空列表。推荐结合Annotated（Python 3.9及以上版本支持）来让类型提示更清晰：

from fastapi import Depends, Query
from pydantic import BaseModel
from typing import Optional, List, Annotated

class GuestGetItemsSchema(BaseModel):
    s: Optional[str] = None
    latitude: Optional[float] = None
    longitude: Optional[float] = None
    # 用Annotated + Query明确指定这是多值查询参数
    industries: Optional[List[int]] = Query(None)
    page_size: Optional[int] = None
    next_token: Optional[str] = None
    previous_token: Optional[str] = None

@app.get("/api/v1/items/guest")
async def get_services(schema: GuestGetItemsSchema = Depends()):
    return schema

现在发送GET /api/v1/items/guest?industries=4&industries=5&industries=6请求，industries就会被正确解析成[4,5,6]了。如果希望默认是空列表而非None，把Query(None)改成Query([])就行。

方法2：用依赖函数手动解析 #

要是不想修改Pydantic模型，也可以写个依赖函数手动提取并解析查询参数：

from fastapi import Depends, Query
from pydantic import BaseModel
from typing import Optional, List

class GuestGetItemsSchema(BaseModel):
    s: Optional[str] = None
    latitude: Optional[float] = None
    longitude: Optional[float] = None
    industries: Optional[List[int]] = None
    page_size: Optional[int] = None
    next_token: Optional[str] = None
    previous_token: Optional[str] = None

async def get_guest_query_params(
    s: Optional[str] = None,
    latitude: Optional[float] = None,
    longitude: Optional[float] = None,
    industries: Optional[List[int]] = Query(None),
    page_size: Optional[int] = None,
    next_token: Optional[str] = None,
    previous_token: Optional[str] = None
):
    return GuestGetItemsSchema(
        s=s,
        latitude=latitude,
        longitude=longitude,
        industries=industries,
        page_size=page_size,
        next_token=next_token,
        previous_token=previous_token
    )

@app.get("/api/v1/items/guest")
async def get_services(schema: GuestGetItemsSchema = Depends(get_guest_query_params)):
    return schema

为什么原来的代码不生效？ #

当你直接把Pydantic模型传给Depends()时，FastAPI会把模型的每个字段当成单个查询参数处理，它不会自动识别重复的键应该合并成列表。而Query(None)则明确告诉FastAPI：这个参数可以接收多个值，要解析成列表类型。

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