FastAPI中如何为Pydantic列表类型查询参数设置validation_alias？

问题场景 #

用Pydantic模型封装FastAPI的查询参数时，filter_by_ids（list[int]类型）能正常解析，但设置了validation_alias="filterByNames"的filter_by_names（list[str]类型）调用时返回422错误，提示“Input should be a valid list”。

原因分析 #

FastAPI处理Query参数时，默认通过重复参数名的方式传递列表（比如filter_by_ids=1&filter_by_ids=3）。但仅用Field(validation_alias=...)时，FastAPI无法识别这个别名对应的是列表类型，会把最后一个参数值当作单个字符串处理，导致类型校验失败。

解决方案 #

方法一：用Annotated结合Query指定别名和列表类型 #

在模型字段上用Annotated包裹，同时通过Query明确指定validation_alias，让FastAPI识别这是一个列表参数：

from typing import Annotated

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

ITEMS = [
    {"id": 1, "name": "foo"},
    {"id": 2, "name": "bar"},
    {"id": 3, "name": "baz"},
]

app = FastAPI()


class FilterParams(BaseModel):
    filter_by_ids: list[int] = []
    # 用Annotated+Query指定validation_alias
    filter_by_names: Annotated[list[str], Query(validation_alias="filterByNames")] = Field(
        default_factory=list,
    )


@app.get("/items")
def read_items(filter_query: Annotated[FilterParams, Query()]):
    items = ITEMS[:]
    if filter_query.filter_by_ids:
        items = list(filter(lambda x: x["id"] in filter_query.filter_by_ids, items))
    if filter_query.filter_by_names:
        items = list(filter(lambda x: x["name"] in filter_query.filter_by_names, items))
    return items

方法二：开启模型的populate_by_name配置 #

在Pydantic模型的Config类中设置populate_by_name=True，让模型同时识别字段名和别名，FastAPI就能正确解析列表参数：

class FilterParams(BaseModel):
    filter_by_ids: list[int] = []
    filter_by_names: list[str] = Field(
        default_factory=list,
        validation_alias="filterByNames",
    )

    # 添加配置，开启按名称填充
    class Config:
        populate_by_name = True

验证修改 #

修改后运行测试用例，test_get_items__filter_by_names会返回200状态码，返回结果符合预期：

[{"id": 1, "name": "foo"}, {"id": 3, "name": "baz"}]

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