Header 参数模型¶
如果你有一组相关的 **header 参数**，你可以创建一个 **Pydantic 模型** 来声明它们。
这样你就可以在多个地方重用该模型，并且可以一次性声明所有参数的验证和元数据。😎
注意
FastAPI 0.115.0 版本开始支持此功能。🤓
使用 Pydantic 模型定义 Header 参数¶
在 **Pydantic 模型** 中声明你需要的 **header 参数**，然后将该参数声明为 Header
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
🤓 其他版本和变体
from typing import Annotated, Union
from fastapi import FastAPI, Header
from pydantic import BaseModel
app = FastAPI()
class CommonHeaders(BaseModel):
host: str
save_data: bool
if_modified_since: Union[str, None] = None
traceparent: Union[str, None] = None
x_tag: list[str] = []
@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
return headers
提示
如果可能，请优先使用 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
提示
如果可能，请优先使用 Annotated 版本。
from typing import Union
from fastapi import FastAPI, Header
from pydantic import BaseModel
app = FastAPI()
class CommonHeaders(BaseModel):
host: str
save_data: bool
if_modified_since: Union[str, None] = None
traceparent: Union[str, None] = None
x_tag: list[str] = []
@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
return headers
FastAPI 将会从请求的 **headers** 中 **提取** **每个字段** 的数据，并返回你定义的 Pydantic 模型。
查看文档¶
你可以在文档 UI (/docs) 中看到必需的 header。
禁止额外的 Header¶
在某些特殊用例中（可能并不常见），你可能希望 **限制** 你想接收的 header。
你可以使用 Pydantic 的模型配置来 forbid 任何 extra 字段
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
🤓 其他版本和变体
from typing import Annotated, Union
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: Union[str, None] = None
traceparent: Union[str, None] = None
x_tag: list[str] = []
@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
return headers
提示
如果可能，请优先使用 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
提示
如果可能，请优先使用 Annotated 版本。
from typing import Union
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: Union[str, None] = None
traceparent: Union[str, None] = None
x_tag: list[str] = []
@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
return headers
如果客户端尝试发送一些 **额外的 header**，它们将收到一个 **错误** 响应。
例如，如果客户端尝试发送一个带有 plumbus 值的 tool header，它们将收到一个 **错误** 响应，告知它们 tool header 参数是不允许的。
{
"detail": [
{
"type": "extra_forbidden",
"loc": ["header", "tool"],
"msg": "Extra inputs are not permitted",
"input": "plumbus",
}
]
}
禁用下划线转换¶
与常规 header 参数一样，当你的参数名称中包含下划线字符时，它们会被 **自动转换为连字符**。
例如，如果你在代码中有一个 header 参数 save_data，预期的 HTTP header 将是 save-data，并且在文档中也会显示为 save-data。
如果出于某种原因你需要禁用此自动转换，你也可以为 header 参数的 Pydantic 模型执行此操作。
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
🤓 其他版本和变体
from typing import Annotated, Union
from fastapi import FastAPI, Header
from pydantic import BaseModel
app = FastAPI()
class CommonHeaders(BaseModel):
host: str
save_data: bool
if_modified_since: Union[str, None] = None
traceparent: Union[str, None] = None
x_tag: list[str] = []
@app.get("/items/")
async def read_items(
headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
):
return headers
提示
如果可能，请优先使用 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
提示
如果可能，请优先使用 Annotated 版本。
from typing import Union
from fastapi import FastAPI, Header
from pydantic import BaseModel
app = FastAPI()
class CommonHeaders(BaseModel):
host: str
save_data: bool
if_modified_since: Union[str, None] = None
traceparent: Union[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 代理和服务器不允许使用带下划线的 header。
总结¶
你可以使用 **Pydantic 模型** 在 **FastAPI** 中声明 **headers**。 😎