FastAPI 使用 Pydantic 模型声明 Header 参数：模型复用、extra 校验与下划线自动转换实战

当接口需要接收一组彼此相关的 Header 请求头时，逐字段用 Header 声明不仅冗长，也难以复用。FastAPI 自 0.115.0 起支持将一组 Header 参数聚合声明到一个 Pydantic 模型中：只需要在路径操作的函数参数中把模型标注为 Header，FastAPI 就会自动从请求头中按字段抽取数据、完成类型校验，并在 /docs 与 OpenAPI 文档中为每个字段生成独立的参数说明。读完本文，你将掌握这种"模型化"Header 声明的完整写法、extra: forbid 严格校验、convert_underscores 下划线转换机制及其底层实现原理，可直接用于实际项目。

为什么用 Pydantic 模型声明 Header 参数

先回顾普通写法：在 docs/en/docs/tutorial/header-params.md 中，每个 Header 参数都要单独写一个带默认值 ... 或 None 的函数参数，并为每个参数分别配置校验与元数据。当需要同时接收 host、save_data、if_modified_since、traceparent、x_tag 等一批请求头时，函数签名会迅速膨胀。

改用 Pydantic 模型聚合后获得两点核心收益（与原文档对应）：

1. 跨位置复用：模型可以定义在共享模块中，被多个路由、多个应用重复引用，避免重复声明；
2. 一次声明全部规则：类型、默认值、校验约束、描述等元数据在模型字段上集中声明，FastAPI 会在生成参数文档与执行校验时逐字段应用。

基础用法：在 Pydantic 模型中声明 Header 字段

原文档给出的核心示例位于 docs_src/header_param_models/tutorial001_an_py310.py：

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

要点拆解：

• 每个字段对应一个请求头：Pydantic 字段名即 HTTP 请求头名（受下划线转换规则影响，见后文）；host: str 与 save_data: bool 不带默认值，属于必填 Header，缺失时 FastAPI 返回 422；
• 可选 Header 用默认值表达：if_modified_since: str | None = None 与 traceparent: str | None = None 表示可选；
• list[str] 支持同名多值 Header：x_tag: list[str] = [] 表明客户端可以发送多个同名 x-tag 请求头（例如两条 x-tag: one、x-tag: two），FastAPI 会聚合成列表。这一点有测试用例佐证：在 tests/test_tutorial/test_header_param_models/test_tutorial003.py 的 test_header_param_model 中同时发送 ("x_tag", "one") 与 ("x_tag", "two")，返回体为 "x_tag": ["one", "two"]；
• Annotated 元数据写法：将 Header() 作为 Annotated 的第二类型参数传入。不习惯 Annotated 的读者也可以使用旧式写法（见 docs_src/header_param_models/tutorial001_py310.py）：

@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

运行时，FastAPI 会从请求头中抽取每个字段所需数据，组装后把定义好的 Pydantic 模型实例注入函数。因此下面的请求（save_data: true、if_modified_since: yesterday、traceparent: 123、两条 x_tag）会得到响应 {"host": "testserver", "save_data": true, "if_modified_since": "yesterday", "traceparent": "123", "x_tag": ["one", "two"]}——其中 host 由 HTTP 客户端自动补全（测试客户端填入 testserver）。

底层机制：字段抽取与模型校验

从源码实现看，该能力建立在 FastAPI 已有的"用模型字段处理参数"机制上。在 fastapi/dependencies/utils.py 中，当检测到某个非标量注解是 BaseModel 子类且以 Header 声明时，FastAPI 会调用 get_cached_model_fields(...) 取回该模型的字段元数据（见 _extract_parameter_type_annotation 与 get_typed_annotation 附近逻辑，例如第 164、797、970 行），然后逐字段从请求头取值，再经 _validate_value_with_model_field(...)（第 734 行定义）用对应字段的 Pydantic Field 执行类型转换与约束校验。也就是说：Header 模型既不是一个请求体，也不会作为一个整体参与 JSON 解析，它本质上是"一组命名 Header 参数 + 统一的模型组装与校验"。

文档与 OpenAPI 的表现

在原文档"Check the Docs"一节中可以看到，访问 /docs 后，Swagger UI 会把这些字段逐条展示为"必须/可选"的 Header 参数（请求头 x-tag 显示为数组类型）。

需要说明的是：本仓库快照中未收录该节引用的截屏图片文件，故此处以实际可验证的 OpenAPI 输出来印证。运行 /openapi.json 后，CommonHeaders 的每个字段都会被展开成 parameters 数组中的独立 Header 参数项。这一行为在 tests/test_tutorial/test_header_param_models/test_tutorial003.py 的 test_openapi_schema 中有完整断言，例如：

{
    "name": "save_data",
    "in": "header",
    "required": true,
    "schema": {"type": "boolean", "title": "Save Data"}
}

因此"查看文档"既是交互式调试入口，也是验证各 Header 是否被正确识别、默认值是否生效的快捷途径。

限制额外 Header：模型配置 extra = "forbid"

Pydantic 模型默认 extra 为 ignore，即客户端多发送的请求头会被静默忽略（见 tests/test_tutorial/test_header_param_models/test_tutorial003.py 的 test_header_param_model_extra：即使额外发送 tool: plumbus，仍返回 200）。

在少数需要严格限定可接收请求头的场景下，可通过 Pydantic 的模型配置显式 forbid 一切额外字段。原文档给出的写法位于 docs_src/header_param_models/tutorial002_an_py310.py，相比基础版只多了一行：

class CommonHeaders(BaseModel):
    model_config = {"extra": "forbid"}

    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []

此后，一旦客户端尝试发送模型之外的请求头（例如 tool: plumbus），FastAPI 会返回 422，错误响应体与原文档一致：

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["header", "tool"],
            "msg": "Extra inputs are not permitted",
            "input": "plumbus",
        }
    ]
}

注意 loc 为 ["header", "tool"]，说明该错误正是定位在"请求头"这一来源上的额外字段违规，而非模型内部错误。需要提示的是：开启 extra: forbid 会显著增加接口的脆弱性（例如反向代理自动注入的 x-forwarded-*、CDN 追加的缓存类请求头都可能触发 422），仅应在确实需要白名单化请求头、且完全掌握上游链路时使用。

下划线自动转换为连字符：默认行为与关闭方式

HTTP 头字段名通常以下划线之外的形式存在，而 Python 标识符喜欢下划线。为此，FastAPI 对 Header 参数名做了一项约定：参数名中的下划线 _ 会自动转换为连字符 -。

在模型化声明中同样如此。以 save_data 为例：

• 代码中的字段名是 save_data；
• 实际期望的 HTTP 请求头是 save-data；
• /docs 与 /openapi.json 中展示的也是 save-data。

这一转换由 Header 参数的 convert_underscores 开关控制，其默认值为 True。从源码看，fastapi/params.py 中 Header 类的签名如下（第 303 行起）：

class Header(Param):
    in_ = ParamTypes.header

    def __init__(
        self,
        default: Any = Undefined,
        *,
        ...
        convert_underscores: bool = True,
        ...
    ):
        self.convert_underscores = convert_underscores

如果因某些原因需要关闭该转换（即让代码字段名与请求头名称逐字符一致），只需在 Header() 中显式传入 convert_underscores=False，示例见 docs_src/header_param_models/tutorial003_an_py310.py：

@app.get("/items/")
async def read_items(
    headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
):
    return headers

关闭后，客户端必须发送字面意义上的 save_data（保留下划线）才能命中该字段。这一点被 tests/test_tutorial/test_header_param_models/test_tutorial003.py 的 test_header_param_model_no_underscore 反向验证：convert_underscores=False 时，即使发送了规范的 save-data、if-modified-since、x-tag，依然会因缺少字段 save_data 而返回 422。

务必牢记的警告：在把 convert_underscores 设为 False 之前，请确认你的整个部署链路（HTTP 代理、网关、反向代理、应用服务器）都允许包含下划线的请求头——事实上，不少代理与服务器会直接丢弃或拒绝下划线请求头（部分服务器以 RFC 7230 的 token 规范为由）。原文档在这一点上也给出了相同的警示。

小结与最佳实践

原文档的结论简洁明确：在 FastAPI 中，完全可以使用 Pydantic 模型来声明 Header 请求头。结合源码与测试，可以沉淀出以下实践建议：

• 优先聚合、统一声明：将业务上同组的 Header（如 host、save_data、x_tag）放入一个 BaseModel，把字段默认值、str | None 可选性、list[str] 多值语义一次写清；
• 跨路由复用模型：把模型定义放进共享模块（如 schemas/headers.py），多个路径操作甚至多个子应用引用同一模型，避免签名漂移；
• 保留默认的 convert_underscores=True：让代码与 HTTP 头名解耦（save_data ↔ save-data）；仅在确认全链路允许下划线请求头后再关闭；
• 慎用 extra: forbid：它会让任何未声明请求头都触发 422，适合安全要求极高的白名单场景，但需评估代理注入头带来的误伤风险；
• 多值 Header 用 list[str]：同名请求头出现多次时自动聚合成列表，无需自行拼接。

如果需要继续深入，可以对照阅读本教程的同类实现：query-param-models 相关教程、cookie-param-models 相关教程，以及覆盖 Header 模型各种组合行为的边界测试 tests/test_query_cookie_header_model_extra_params.py；底层参数抽取与校验逻辑可回溯至 fastapi/dependencies/utils.py 与 fastapi/params.py。