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