FastAPI 请求参数 API 参考：Query、Path、Body、Cookie、Header、Form、File 全参数详解

本篇基于 FastAPI 官方参考文档 Request Parameters 展开，系统讲解 Query()、Path()、Body()、Cookie()、Header()、Form()、File() 七个请求参数声明函数的完整参数表（默认值、取值、弃用状态），并结合 fastapi/param_functions.py、fastapi/params.py 与 fastapi/dependencies/utils.py 的源码实现，说明这些参数在路由解析与 OpenAPI 生成中的真实作用，帮助读者写出准确、可验证的请求参数声明。

快速导入

这七个特殊函数用于放在 path operation function（路由处理函数）的参数中，或放在依赖函数（Depends 指向的函数）的参数中，配合 Annotated 从请求中获取并校验数据。它们都可以直接从 fastapi 顶层导入：

from fastapi import Body, Cookie, File, Form, Header, Path, Query

顶层导出实现在 fastapi/init.py 中，全部来自 param_functions 模块：

from .param_functions import Body as Body
from .param_functions import Cookie as Cookie
from .param_functions import File as File
from .param_functions import Form as Form
from .param_functions import Header as Header
from .param_functions import Path as Path
from .param_functions import Query as Query

典型用法（Path 官方 docstring 中的示例，完整定义见 fastapi/param_functions.py）：

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
):
    return {"item_id": item_id}

内部类层次：Param 与 FieldInfo

理解参数行为的关键在于 fastapi/params.py 中的类层次结构：

• ParamTypes 枚举：取值 query、header、path、cookie，见 fastapi/params.py#L19-L24；
• Param(FieldInfo)：所有非 Body 类参数的基类，携带 in_: ParamTypes 属性用于区分来源；
• Path(Param)、Query(Param)、Header(Param)、Cookie(Param)：分别将 in_ 固定为 path/query/header/cookie；
• Body(FieldInfo)：直接继承 Pydantic 的 FieldInfo，额外携带 embed 与 media_type 两个属性；
• Form(Body)、File(Form)：继承链逐级收紧，通过不同的默认 media_type 区分表单与文件上传。

值得注意的是，fastapi 导出的 Path、Query 等函数（定义在 fastapi/param_functions.py）并不是类本身，而是带 Doc 文档注解的工厂函数，内部实例化 params.Path、params.Query 等类并返回。文档中看到的每个参数说明，正是这些工厂函数签名上 Annotated[..., Doc(...)] 中的文档字符串。

各函数的 in_ 类型

类	in_（ParamTypes）	默认值行为
Path	path	必为 ...（Ellipsis），不允许默认值
Query	query	默认为 Undefined（未设置则必填）
Header	header	默认为 Undefined
Cookie	cookie	默认为 Undefined
Body	无 in_（Body 类）	默认为 Undefined
Form	继承 Body	默认 media_type="application/x-www-form-urlencoded"
File	继承 Form	默认 media_type="multipart/form-data"

Path 的强制约束写在 fastapi/params.py#L185：assert default is ..., "Path parameters cannot have a default value"。在 Param/Query 等类中，Undefined 来自 fastapi._compat，表示"参数缺失时视为必填"，这也是为什么 Query(...) 等价于"没有默认值的必填查询参数"。

公共参数完整参考

以下参数对 Query、Path、Header、Cookie、Body、Form、File 全部可用（每个函数签名逐一声明并透传给底层类）。参数说明继承自 fastapi/param_functions.py 中各函数的 Doc 注解。

默认值相关

参数	类型 / 默认值	说明
default	Any，Path 固定为 ...；Query/Header/Cookie/Body/Form/File 默认为 Undefined（必填）	参数字段未设置时的默认值。对 Path 无效（值总是必填），仅为兼容性保留。
default_factory	Callable[[], Any] | None，默认未设置	生成默认值的可调用对象。同样不适用于 Path。

一个容易踩坑的规则：使用 Annotated 声明时，Query 等对象内部不能再设置 default，默认值必须通过函数参数的 = 赋值。源码在 fastapi/dependencies/utils.py#L426-L442 中直接断言：

assert (
    field_info.default == Undefined or field_info.default == RequiredParam
), (
    f"`{field_info.__class__.__name__}` default value cannot be set in"
    f" `Annotated` for {param_name!r}. Set the default value with `=` instead."
)
if value is not inspect.Signature.empty:
    assert not is_path_param, "Path parameters cannot have default values"
    field_info.default = value
else:
    field_info.default = RequiredParam

别名（alias）相关

参数	类型 / 默认值	说明
alias	str | None，默认 None	字段的替代名称，用于从请求中抽取数据以及生成 OpenAPI。当想要的名字是 Python 保留字等无法用作参数名时特别有用。
alias_priority	int | None，默认未设置	别名的优先级，影响是否使用 alias 生成器。
validation_alias	str | AliasPath | AliasChoices | None，默认 None	"白名单"式验证步骤：只允许别名或别名集中定义的字段通过验证。
serialization_alias	str | None，默认 None	"黑名单"式验证步骤：序列化时只使用原始字段名，忽略别名。

在 fastapi/params.py#L113-L126 可以看到别名的归一化逻辑：如果显式未设置 serialization_alias 且 alias 是字符串，则 serialization_alias 自动等于 alias；同理 validation_alias 默认回退到 alias。

元数据（title / description）

参数	类型 / 默认值	说明
title	str | None，默认 None	人类可读的标题，展示在 /docs 等自动生成的 OpenAPI UI 中。
description	str | None，默认 None	人类可读的描述。

数值验证（仅对 number 生效）

参数	类型 / 默认值	说明
gt	float | None，默认 None	大于：值必须严格大于该值。
ge	float | None，默认 None	大于等于。
lt	float | None，默认 None	小于：值必须严格小于该值。
le	float | None，默认 None	小于等于。
multiple_of	float | None，默认未设置	值必须是该值的整数倍。
allow_inf_nan	bool | None，默认未设置	是否允许 inf、-inf、nan。
max_digits	int | None，默认未设置	Decimal 值允许的最大位数。
decimal_places	int | None，默认未设置	Decimal 值允许的最大小数位数。
strict	bool | None，默认未设置	为 True 时对字段执行严格验证（不做隐式类型转换）。

字符串验证

参数	类型 / 默认值	说明
min_length	int | None，默认 None	字符串最小长度。
max_length	int | None，默认 None	字符串最大长度。
pattern	str | None，默认 None	字符串的正则表达式模式。
regex	str | None，默认 None	已弃用（FastAPI 0.100.0 / Pydantic v2 起），请改用 pattern。

regex 的弃用警告在 fastapi/params.py#L104-L109 触发，并通过 kwargs["pattern"] = pattern or regex（第 127 行）做兼容回退，即旧代码传 regex 仍会生效但会收到 FastAPIDeprecationWarning。

结构与其他

参数	类型 / 默认值	说明
discriminator	str | None，默认 None	用于带标签联合类型（tagged union）区分类型的字段名。
examples	list[Any] | None，默认 None	该字段的示例值列表，写入 JSON Schema 的 examples。
example	Any | None，默认未设置	已弃用（OpenAPI 3.1 采用 JSON Schema 2020-12，仍受支持），请改用 examples。
openapi_examples	dict[str, Example] | None，默认 None	OpenAPI 专用示例（带值的完整示例对象）。会被加入生成的 OpenAPI（如在 /docs 中可见）；Swagger UI 对 OpenAPI 专用示例的支持优于 JSON Schema 的 examples，这是它的主要用途。
deprecated	bool | str | None，默认 None	将该参数标记为弃用，影响生成的 OpenAPI（在 /docs 中可见）。
include_in_schema	bool，默认 True	是否将该参数包含在生成的 OpenAPI 中。一般用不到，但可用。
json_schema_extra	dict[str, Any] | None，默认 None	附加到 JSON Schema 的任意额外数据。
**extra	Any	已弃用：extra kwargs 不再推荐，请改用 json_schema_extra。在 Param/Body 中 json_schema_extra or extra 二选一生效（fastapi/params.py#L110）。

各函数特有参数

Header 特有：convert_underscores

Header 比其余函数多一个参数（fastapi/param_functions.py#L761-L771）：

参数	类型 / 默认值	说明
convert_underscores	bool，默认 True	自动将参数名中的下划线转换为连字符。例如 user_agent 会匹配请求头 User-Agent。

实现证据有两处：

1. 字段创建阶段，fastapi/dependencies/utils.py#L524-L528：若未显式设置 alias 且 convert_underscores 生效，则 alias = param_name.replace("_", "-")；
2. 请求抽取阶段，fastapi/dependencies/utils.py#L811-L828 对 Headers 逐个字段做下划线转连字符的 alias 处理，并对 Pydantic 模型级别的 Header 字段从模型级 FieldInfo 上读取 convert_underscores（默认 True，可被 Header(convert_underscores=False) 覆盖）。

Body 特有：embed 与 media_type

Body 额外携带两个属性（fastapi/params.py#L469-L518）：

参数	类型 / 默认值	说明
embed	bool | None，默认 None	为 True 时，参数将作为 JSON body 中的一个 key 出现，而不是整个 JSON body 本身。当声明了多个 Body 参数时会自动发生这种包裹。
media_type	str，默认 "application/json"	该参数字段的媒体类型。修改它会影响生成的 OpenAPI，但当前不影响数据解析。

Body/Form/File 的默认媒体类型链：Body → application/json，Form → application/x-www-form-urlencoded（fastapi/params.py#L588），File → multipart/form-data（fastapi/params.py#L670）。

Form / File

Form 除 media_type 默认为 application/x-www-form-urlencoded 外，其余参数与 Body 完全一致；File 除 media_type 默认为 multipart/form-data 外，其余参数与 Form 一致，且继承链为 File → Form → Body → FieldInfo。

参数如何被解析：analyze_param 的关键流程

从源码结构看，参数声明的落地发生在 fastapi/dependencies/utils.py 的 analyze_param（第 381-547 行），核心规则：

1. 解析 Annotated：analyze_param 从注解中取出类型（annotated_args[0]）和 FastAPI 注解（FieldInfo 或 params.Depends 实例）。若同时声明了 Annotated 内的参数对象和函数默认值，默认值会被写入 field_info.default；两者冲突（如 Annotated 中放 Query 又在 = 后放 Depends）会触发断言错误。
2. 按类型推断参数来源：当参数既无 FieldInfo 也无 Depends 时（fastapi/dependencies/utils.py#L491-L505）：
   • 路径参数 → 自动构造 params.Path；
   • UploadFile（或其序列）注解 → 自动构造 params.File；
   • 非标量注解（如 Pydantic 模型）→ 自动构造 params.Body；
   • 其余标量类型 → 自动构造 params.Query。
3. 强制校验：路径参数必须是 params.Path 实例且必须为标量字段（Path params must be of one of the supported types）；Query 参数必须是标量、标量序列或 BaseModel 子类（fastapi/dependencies/utils.py#L540-L545）。使用 Form 时还会检查 multipart 库是否已安装（ensure_multipart_is_installed()）。
4. 归类：add_param_to_fields 依据 field_info.in_ 把字段分别放进 dependant.path_params / query_params / header_params / cookie_params（fastapi/dependencies/utils.py#L550-L563）。
5. 请求时取值与验证：request_params_to_args（fastapi/dependencies/utils.py#L780-L866）按 alias（含 Header 的下划线转换）从 QueryParams/Headers 等取值，缺失值回退 field.default，必填缺失则走 Pydantic 字段验证错误路径。

因此 include_in_schema、deprecated、examples、openapi_examples、title、description、pattern 等参数最终都随 FieldInfo 进入 OpenAPI 生成环节，影响 /docs、/openapi.json 的内容；而 gt/lt/min_length/strict 等则真正参与请求校验。

参数对象的可读性

Param 与 Body 类都重写了 __repr__（fastapi/params.py#L133-L134），直接输出类名与默认值：

def __repr__(self) -> str:
    return f"{self.__class__.__name__}({self.default})"

行为由 tests/test_params_repr.py 完整覆盖，例如 repr(Query(1)) == "Query(1)"、repr(Path()) == "Path(PydanticUndefined)"。当你在 IDE 变量视图中看到 Path(PydanticUndefined) 时，即表示该路径参数为必填（... 即未定义默认值）。

弃用项小结（以当前仓库源码为准）

弃用项	替代方案	触发机制
regex	pattern	Param/Body 中 regex is not None 时发出 FastAPIDeprecationWarning
example	examples	example is not _Unset 时发出 FastAPIDeprecationWarning
**extra	json_schema_extra	签名上以 deprecated(...) 标注；运行时 json_schema_extra or extra 兼容取用

这三处弃用均针对 OpenAPI 3.1 / JSON Schema 2020-12 迁移（见 fastapi/params.py#L48-L67 的 Annotated[..., deprecated(...)] 声明），旧写法仍可运行但会告警。

参考资料（仓库内路径）

• 参考文档主体：docs/en/docs/reference/parameters.md
• 带文档注解的公开函数（本文参数表的来源）：fastapi/param_functions.py
• 内部类实现（Param/Path/Query/Header/Cookie/Body/Form/File/Depends/Security）：fastapi/params.py
• 参数解析流程：fastapi/dependencies/utils.py
• 顶层导出：fastapi/init.py
• __repr__ 行为测试：tests/test_params_repr.py