Header 参数模型¶
如果您有一组相关的header 参数，您可以创建一个Pydantic 模型来声明它们。
这将允许您在多个地方能够重用模型，并且可以一次性声明所有参数的验证和元数据。😎
注意
自 FastAPI 版本0.115.0 起支持此功能。🤓
使用 Pydantic 模型的 Header 参数¶
在Pydantic 模型中声明所需的header 参数，然后将参数声明为Header :
fromtypingimportAnnotatedfromfastapiimportFastAPI,HeaderfrompydanticimportBaseModelapp=FastAPI()classCommonHeaders(BaseModel):host:strsave_data:boolif_modified_since:str|None=Nonetraceparent:str|None=Nonex_tag:list[str]=[]@app.get("/items/")asyncdefread_items(headers:Annotated[CommonHeaders,Header()]):returnheaders🤓 Other versions and variants
Tip
Prefer to use theAnnotated version if possible.
fromfastapiimportFastAPI,HeaderfrompydanticimportBaseModelapp=FastAPI()classCommonHeaders(BaseModel):host:strsave_data:boolif_modified_since:str|None=Nonetraceparent:str|None=Nonex_tag:list[str]=[]@app.get("/items/")asyncdefread_items(headers:CommonHeaders=Header()):returnheadersFastAPI 将从请求中接收到的headers 中提取出每个字段的数据，并提供您定义的 Pydantic 模型。
查看文档¶
您可以在文档 UI 的/docs 中查看所需的 headers：
禁止额外的 Headers¶
在某些特殊使用情况下（可能并不常见），您可能希望限制您想要接收的 headers。
您可以使用 Pydantic 的模型配置来禁止（forbid ）任何额外（extra ）字段：
fromtypingimportAnnotatedfromfastapiimportFastAPI,HeaderfrompydanticimportBaseModelapp=FastAPI()classCommonHeaders(BaseModel):model_config={"extra":"forbid"}host:strsave_data:boolif_modified_since:str|None=Nonetraceparent:str|None=Nonex_tag:list[str]=[]@app.get("/items/")asyncdefread_items(headers:Annotated[CommonHeaders,Header()]):returnheaders🤓 Other versions and variants
Tip
Prefer to use theAnnotated version if possible.
fromfastapiimportFastAPI,HeaderfrompydanticimportBaseModelapp=FastAPI()classCommonHeaders(BaseModel):model_config={"extra":"forbid"}host:strsave_data:boolif_modified_since:str|None=Nonetraceparent:str|None=Nonex_tag:list[str]=[]@app.get("/items/")asyncdefread_items(headers:CommonHeaders=Header()):returnheaders如果客户尝试发送一些额外的 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 模型中进行设置。
fromtypingimportAnnotatedfromfastapiimportFastAPI,HeaderfrompydanticimportBaseModelapp=FastAPI()classCommonHeaders(BaseModel):host:strsave_data:boolif_modified_since:str|None=Nonetraceparent:str|None=Nonex_tag:list[str]=[]@app.get("/items/")asyncdefread_items(headers:Annotated[CommonHeaders,Header(convert_underscores=False)],):returnheaders🤓 Other versions and variants
Tip
Prefer to use theAnnotated version if possible.
fromfastapiimportFastAPI,HeaderfrompydanticimportBaseModelapp=FastAPI()classCommonHeaders(BaseModel):host:strsave_data:boolif_modified_since:str|None=Nonetraceparent:str|None=Nonex_tag:list[str]=[]@app.get("/items/")asyncdefread_items(headers:CommonHeaders=Header(convert_underscores=False)):returnheaders警告
在将convert_underscores 设为False 之前，请注意某些 HTTP 代理和服务器不允许使用带下划线的 headers。
总结¶
您可以使用Pydantic 模型在FastAPI 中声明headers。😎