Header 参数模型

如果你有一组相关的 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

🤓 其他版本和变体

Python 3.10+ - 非 Annotated

提示

如果可能，请优先使用 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: CommonHeaders = Header()):
    return headers

FastAPI 将会从请求的 headers 中为 每个字段提取 数据，并为你提供定义的 Pydantic 模型。

查看文档

你可以在 /docs 的文档界面中查看所需的 headers

禁止额外 Header

在某些特殊用例中（通常不太常见），你可能希望 限制 你想要接收的 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

🤓 其他版本和变体

Python 3.10+ - 非 Annotated

提示

如果可能，请优先使用 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: 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 参数一样，当参数名称中包含下划线字符时，它们会 自动转换为连字符。

例如，如果代码中有一个 header 参数 save_data，则预期的 HTTP header 将为 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

🤓 其他版本和变体

Python 3.10+ - 非 Annotated

提示

如果可能，请优先使用 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: CommonHeaders = Header(convert_underscores=False)):
    return headers

警告

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

总结

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