FastAPI中查询参数含连字符(-)的异常问题咨询

这不是FastAPI或Pydantic的Bug，核心原因是BaseModel（Pydantic模型）与直接路由参数的Query别名解析机制不同：

1. BaseModel的字段映射限制 #

Pydantic模型的字段名必须遵循Python变量命名规则（不能包含连字符、空格等特殊字符）。当你在BaseModel字段上定义Query(alias="your-name")时，虽然别名是带连字符的，但FastAPI默认不会主动将请求中的your-name参数映射到模型的your_name字段——因为默认情况下，Pydantic模型只会通过字段名（而非别名）来匹配请求参数。

2. 直接路由参数的解析逻辑 #

当你在路由函数参数中直接使用Query(alias="your-name")时，FastAPI是直接对单个参数进行解析，不需要经过Pydantic模型的字段映射逻辑，它会直接识别并绑定别名对应的请求参数，因此请求可以正常返回。

解决方法 #

要让BaseModel配合Depends支持带连字符的Query别名，只需给模型开启按别名填充的配置：

Pydantic v2 示例 #

from fastapi import FastAPI, Depends, Query
from pydantic import BaseModel, ConfigDict

app = FastAPI()

class UserQuery(BaseModel):
    # 开启按别名填充字段
    model_config = ConfigDict(populate_by_name=True)
    your_name: str = Query(alias="your-name")

@app.get("/")
async def read_user(query: UserQuery = Depends()):
    return {"your_name": query.your_name}

Pydantic v1 示例 #

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

app = FastAPI()

class UserQuery(BaseModel):
    class Config:
        # 开启按别名填充字段
        allow_population_by_field_name = True
    your_name: str = Query(alias="your-name")

@app.get("/")
async def read_user(query: UserQuery = Depends()):
    return {"your_name": query.your_name}

配置完成后，请求curl "http://127.0.0.1:8001/?your-name=amin"即可正常返回结果。

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