FastAPI中Annotated与Field搭配失效问题及解决方案咨询

结论 #

这是预期设计，并非Bug，核心原因是Pydantic对Annotated中元数据的处理规则限制。

报错原因解析 #

你遇到的ValueError: Field default cannot be set in Annotated，本质是因为：

• 在Pydantic中，Annotated用于为字段添加元数据（比如验证规则、描述信息），但不能在Annotated的元数据项中携带字段的默认值（包括...这种必填标记）。
• 当你写Annotated[str, Field(Path(...))]时，Field内部的Path(...)包含了必填默认值...，这违反了Pydantic的规则——默认值应该定义在字段的赋值位置（如field: Type = Field(...)），而非Annotated的元数据里。

正确的用法示例 #

1. 直接在Annotated中使用Path/Query等FastAPI类 #

这是你最后发现的可行方案，也是推荐的方式：

from typing import Annotated
import uvicorn
from fastapi import FastAPI, Depends, Path
from pydantic import BaseModel

app = FastAPI()

class TestInput(BaseModel):
    test_id: Annotated[str, Path(..., title="a test title", description="a test description")]

@app.get("/test/{test_id}")
def test(inp: TestInput = Depends()):
    return "Hello world"

def main():
    uvicorn.run("run:app", host="0.0.0.0", reload=True, port=8001)

if __name__ == "__main__":
    main()

原因：FastAPI的Path/Query/Body等类本身继承自Pydantic的FieldInfo，既可以传递元数据（title、description），又能让FastAPI识别参数的来源（路径参数、查询参数等），无需嵌套Field。

2. 结合Annotated与Field（无默认值） #

如果需要使用Field的特性（比如自定义验证器、额外元数据），可以在Annotated中使用Field，但不能在Field中设置默认值，默认值需放在字段赋值位置：

from typing import Annotated
from pydantic import BaseModel, Field

class TestInput(BaseModel):
    # 必填字段：Annotated中只放元数据，默认值隐含为必填（无需写...）
    test_id: Annotated[str, Field(title="a test title", description="a test description")]
    # 可选字段：在赋值位置设置默认值
    optional_id: Annotated[str, Field(title="optional field")] = "default_value"

为什么之前test_id: str = Field(Path(...))可行？ #

在字段赋值位置使用Field(Path(...))时，Field是用来定义字段的默认值和元数据，此时Path(...)作为默认值传入，同时FastAPI会识别其中的元数据生成文档，这符合Pydantic的赋值规则，因此可以正常工作。

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