FastAPI中Pydantic模型如何正确绑定带特殊符号的GET查询参数

FastAPI内置的Pydantic模型查询参数解析逻辑，默认会将带.、[]的参数名按照嵌套对象规则拆分匹配，没法把完整的params[A]、params[B]作为独立参数别名和模型字段做绑定，最终这些参数会被塞进模型的extra_data里，完不成正常校验。
这个行为和手动在接口函数里写Query(alias="params[A]")的差异本质是：手动声明的写法完全绕开了模型的嵌套参数拆分逻辑，直接拿完整字符串当参数别名做匹配，所以能正常收参。

方案1：自定义适配特殊别名的查询依赖，绕开内置模型解析逻辑 #

不用逐一声明每个查询参数，通过工具函数自动同步Pydantic模型的字段配置、别名信息，生成和手动声明Query行为完全一致的依赖注入逻辑：

import inspect
from fastapi import Query, Depends
from pydantic import BaseModel
from typing import Type, get_type_hints

def special_alias_query_dependency(model: Type[BaseModel]):
    field_params = {}
    field_type_map = get_type_hints(model)
    # 遍历模型所有字段，读取别名、默认值配置
    for field_name, model_field in model.model_fields.items():
        alias = model_field.alias or field_name
        field_params[field_name] = Query(
            default=model_field.default,
            alias=alias,
            description=model_field.description
        )

    # 定义依赖回调，把收集到的查询参数组装成Pydantic模型实例
    def dep_callback(**kwargs):
        return model(**kwargs)

    # 把每个Query参数绑定到回调函数签名，让FastAPI能正确识别参数配置
    dep_callback.__signature__ = inspect.Signature(
        parameters=[
            inspect.Parameter(
                name=field_name,
                kind=inspect.Parameter.KEYWORD_ONLY,
                default=query_config
            ) for field_name, query_config in field_params.items()
        ]
    )
    return Depends(dep_callback)

使用方式：

from pydantic import Field

class MyModel(BaseModel):
    a: str = Field(alias="params[A]") 
    b: str = Field(alias="params[B]")

@app.get("/api")
def my_handler(model: MyModel = special_alias_query_dependency(MyModel)):
    # 可正常完成参数绑定，Swagger文档也会正确展示对应带方括号的查询参数
    return model.dict()

方案2：调整全局参数解析规则 #

如果要保留默认的Pydantic模型直接注入的写法，可以自定义FastAPI的查询参数解析规则，关闭对带[]参数名的嵌套拆分逻辑，直接匹配完整参数别名。但这种方案会侵入全局参数解析流程，容易干扰其他正常的嵌套参数业务，不推荐使用。

注意

• 自定义依赖方案的行为和逐一声明Query的逻辑完全等价，不会出现参数被归类为extra_data的问题
• 所有字段的校验规则、别名、默认值都会从Pydantic模型定义中自动同步，不需要重复维护

内容的提问来源于stack exchange，提问作者Иван Литий