使用NewType进行FastAPI查询参数验证的问题及解决办法问询

直接用类型别名替代NewType即可，因为NewType会创建新的类型包装，导致FastAPI无法识别内部Annotated中的Query元数据，从而引发验证错误。

正确的复用方式示例 #

from fastapi import FastAPI, Query
from typing import Annotated, List

# 直接定义带Query注解的类型别名
DefaultQueryType = Annotated[List[str], Query()]

app = FastAPI()

@app.get("/items/")
async def read_items(q: DefaultQueryType):
    query_items = {"q": q}
    return query_items

# 其他路由直接复用该类型
@app.get("/products/")
async def read_products(q: DefaultQueryType):
    return {"products_q": q}

原代码报错原因 #

NewType的作用是创建逻辑上独立的类型，它不会保留内部Annotated中的额外元数据（比如Query()的参数规则）。FastAPI解析参数时，只会识别直接标注在参数上的Annotated信息，无法穿透NewType读取内部注解，因此会把q当作普通的List[str]类型处理，没有应用Query()的解析规则，最终导致参数验证失败。

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