Header 参数模型¶

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

English version

如果您有一组相关的 header 参数，您可以创建一个 Pydantic 模型来声明它们。

这将允许您在多个地方能够重用模型，并且可以一次性声明所有参数的验证和元数据。😎

注意

自 FastAPI 版本 0.115.0 起支持此功能。🤓

使用 Pydantic 模型的 Header 参数¶

在 Pydantic 模型中声明所需的 header 参数，然后将参数声明为 Header :

Python 3.10+

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

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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: CommonHeaders = Header()):
    return headers

FastAPI 将从请求中接收到的 headers 中提取出每个字段的数据，并提供您定义的 Pydantic 模型。

查看文档¶

您可以在文档 UI 的 /docs 中查看所需的 headers：

禁止额外的 Headers¶

在某些特殊使用情况下（可能并不常见），您可能希望限制您想要接收的 headers。

您可以使用 Pydantic 的模型配置来禁止（ forbid ）任何额外（ extra ）字段：

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


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] = []


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

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


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] = []


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

如果客户尝试发送一些额外的 headers，他们将收到错误响应。

例如，如果客户端尝试发送一个值为 plumbus 的 tool header，客户端将收到一个错误响应，告知他们 header 参数 tool 是不允许的：

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

禁用下划线转换¶

与常规的 header 参数相同，当参数名中包含下划线时，会自动转换为连字符。

例如，如果你的代码中有一个名为 save_data 的 header 参数，那么预期的 HTTP 头将是 save-data，并且在文档中也会以这种形式显示。

如果由于某些原因你需要禁用这种自动转换，你也可以在用于 header 参数的 Pydantic 模型中进行设置。

Python 3.10+

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(convert_underscores=False)],
):
    return headers

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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: CommonHeaders = Header(convert_underscores=False)):
    return headers

警告

在将 convert_underscores 设为 False 之前，请注意某些 HTTP 代理和服务器不允许使用带下划线的 headers。

总结¶

您可以使用 Pydantic 模型在 FastAPI 中声明 headers。😎