Header 参数¶
你可以像定义 Query、Path 和 Cookie 参数一样定义 Header 参数。
导入 Header¶
首先导入 Header
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
return {"User-Agent": user_agent}
🤓 其他版本和变体
提示
如果可能，请优先使用 Annotated 版本。
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
return {"User-Agent": user_agent}
声明 Header 参数¶
然后使用与 Path、Query 和 Cookie 相同的结构声明 header 参数。
你可以定义默认值以及所有额外的验证或标注参数
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
return {"User-Agent": user_agent}
🤓 其他版本和变体
提示
如果可能，请优先使用 Annotated 版本。
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
return {"User-Agent": user_agent}
技术细节
Header 是 Path、Query 和 Cookie 的“姊妹”类。它也继承自相同的通用 Param 类。
但请记住，当你从 fastapi 导入 Query、Path、Header 等时，它们实际上是返回特殊类的函数。
注意
你需要使用 Header 来声明 header，否则这些参数会被解释为查询参数。
自动转换¶
Header 在 Path、Query 和 Cookie 提供的功能基础上，还有一些额外的功能。
大多数标准 header 都由“连字符”（即“减号”，-）分隔。
但像 user-agent 这样的变量在 Python 中是无效的。
因此，默认情况下，Header 会将参数名称中的下划线 (_) 转换为连字符 (-) 以提取并记录 header。
此外，HTTP header 是不区分大小写的，因此你可以使用标准的 Python 风格（也称为“蛇形命名法”即 snake_case）来声明它们。
所以，你可以像在 Python 代码中那样使用 user_agent，而不必将其首字母大写写成 User_Agent 或类似的形式。
如果由于某种原因你需要禁用下划线到连字符的自动转换，请将 Header 的 convert_underscores 参数设置为 False
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: Annotated[str | None, Header(convert_underscores=False)] = None,
):
return {"strange_header": strange_header}
🤓 其他版本和变体
提示
如果可能，请优先使用 Annotated 版本。
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: str | None = Header(default=None, convert_underscores=False),
):
return {"strange_header": strange_header}
警告
在将 convert_underscores 设置为 False 之前，请记住，某些 HTTP 代理和服务器不允许使用带有下划线的 header。
重复的 Header¶
有时可能会收到重复的 header。这意味着同一个 header 拥有多个值。
你可以在类型声明中使用列表 (list) 来定义这些情况。
你将以 Python list 的形式接收重复 header 中的所有值。
例如，要声明一个可以出现多次的 X-Token header，你可以这样写
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: Annotated[list[str] | None, Header()] = None):
return {"X-Token values": x_token}
🤓 其他版本和变体
提示
如果可能，请优先使用 Annotated 版本。
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: list[str] | None = Header(default=None)):
return {"X-Token values": x_token}
如果你与该路径操作通信并发送了两个如下的 HTTP header
X-Token: foo
X-Token: bar
响应将如下所示
{
"X-Token values": [
"bar",
"foo"
]
}
回顾¶
使用与 Query、Path 和 Cookie 相同的通用模式，通过 Header 声明 header。
不要担心变量名中的下划线，FastAPI 会负责转换它们。