能否将Pydantic的__root__字段映射为FastAPI的查询参数？

我完全懂你的需求——想把标签名称的验证规则只定义一次，然后在查询参数、路径参数这类不同场景下复用，用带__root__的Pydantic模型确实是个很合理的思路，但FastAPI对模型参数的默认处理逻辑确实会让你踩坑。

先说说你之前两种方法行不通的原因：

• 直接用Annotated[TagName, Query()]：FastAPI的Query是用来定义单个基础类型查询参数的，而TagName是个Pydantic模型，框架默认会把非基础类型的参数当成请求体解析，所以才会抛出那个断言错误。
• 用自定义类加Depends：你的ChangeTagByNameQuery构造函数接收TagName类型参数，FastAPI会尝试从请求体里解析这个模型参数，自然就把它加到请求体的Schema里了。

给你一个能实现需求的方案，核心是用依赖函数把查询参数和模型验证结合起来，既复用验证规则，又让FastAPI正确识别参数位置：

from typing import Annotated
from fastapi import FastAPI, Depends, Query
from pydantic import BaseModel, Field

app = FastAPI()

# 只定义一次的标签验证规则
class TagName(BaseModel):
    __root__: str = Field(example='aot', max_length=128, min_length=3)

# 依赖函数：接收原始查询/路径参数，用TagName模型完成验证
def get_validated_tag(tag: Annotated[str, Query(description="要操作的标签名称")]) -> TagName:
    return TagName(__root__=tag)

# 作为查询参数使用
@app.patch('/')
async def change_tag_by_name(
    validated_tag: Annotated[TagName, Depends(get_validated_tag)]
):
    # 直接使用验证后的结果，validated_tag.__root__就是符合规则的字符串
    return {"message": f"已修改标签：{validated_tag.__root__}"}

# 路径参数也能复用同一套验证规则
@app.get('/tags/{tag}')
async def get_tag_detail(
    validated_tag: Annotated[TagName, Depends(get_validated_tag)]
):
    return {"tag_name": validated_tag.__root__, "status": "存在"}

这个方案的优势：

1. TagName的验证规则只写一次，查询参数、路径参数都能通过Depends(get_validated_tag)复用
2. FastAPI会正确识别tag是查询/路径参数，不会把它当成请求体
3. 如果参数不符合验证规则，Pydantic会自动抛出错误，FastAPI会返回标准的422格式响应，不用自己额外处理异常

要是你觉得依赖函数有点繁琐，也可以直接把验证规则通过Annotated和Query结合，但这样就没法复用模型了——所以依赖函数的方式更贴合你“一次定义、多处复用”的核心需求。

备注：内容来源于stack exchange，提问作者Iwanofu