文章
FastApi参数类型判定规则
参数类型判定规则
| 参数位置/标记 | 判定结果 | 示例 |
|---|---|---|
参数名出现在路由路径 {...} 中 | 路径参数 | /hello/{name} → name: str |
不在路径中，且是基础类型（str、int、float、bool 等） | 查询参数 | skip: int = 0、q: str | None = None |
类型是 Pydantic 模型（BaseModel 子类） | 请求体（JSON Body） | item: Item |
用 Header() 标记 | 请求头参数 | user_agent: Annotated[str | None, Header()] |
用 Cookie() 标记 | Cookie 参数 | username: Annotated[str | None, Cookie()] |
用 Body() 标记 | 请求体参数 | item: Annotated[Item, Body()] |
用 Query() 标记 | 查询参数 | q: Annotated[str | None, Query()] |
用 Path() 标记 | 路径参数 | name: Annotated[str, Path(max_length=10)] |
用 Depends() 标记 | 依赖注入 | params: Dict = Depends(common) |
需要补充的几点
- 显式标记优先于默认推断
比如一个基础类型int，默认是查询参数，但如果你写成Annotated[int, Body()]，它就变成请求体参数。 - 复杂类型默认可能进 Body
list、dict等非基础类型且不是 Pydantic 模型时，FastAPI 通常会把它们当作请求体。如果想作为查询参数，需要显式加Query()，例如：
tags: Annotated[list[str], Query()] = []3. Depends 是特殊的一类
它不是直接从请求的某一部分取值，而是调用一个依赖函数/类。依赖内部还可以再声明查询参数、Header 等。
4. 多个 Body 参数
如果函数里有多个 Pydantic 模型或 Body() 参数，FastAPI 会期望一个 JSON 对象，按参数名分组，例如：
{
"item": {...},
"user": {...}
}路径里出现的就是路径参数；没出现的，基础类型默认查询参数，Pydantic 模型默认请求体；用 Header、Cookie、Body、Query、Path、Depends 可以显式改变来源。