Header 参数¶

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

English version

定义 Header 参数的方式与定义 Query、Path、Cookie 参数相同。

导入 `Header`¶

首先，导入 Header：

Python 3.10+

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}

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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 参数。

第一个值是默认值，还可以传递所有验证参数或注释参数：

Python 3.10+

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}

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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 提供了更多功能。

大部分标准请求头用连字符分隔，即减号（-）。

但是 user-agent 这样的变量在 Python 中是无效的。

因此，默认情况下，Header 把参数名中的字符由下划线（_）改为连字符（-）来提取并存档请求头。

同时，HTTP 的请求头不区分大小写，可以使用 Python 标准样式（即 snake_case）进行声明。

因此，可以像在 Python 代码中一样使用 user_agent ，无需把首字母大写为 User_Agent 等形式。

如需禁用下划线自动转换为连字符，可以把 Header 的 convert_underscores 参数设置为 False：

Python 3.10+

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}

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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 代理和服务器不支持使用带有下划线的请求头。

重复的请求头¶

有时，可能需要接收重复的请求头。即同一个请求头有多个值。

类型声明中可以使用 list 定义多个请求头。

使用 Python list 可以接收重复请求头所有的值。

例如，声明 X-Token 多次出现的请求头，可以写成这样：

Python 3.10+

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}

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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 请求头：

X-Token: foo
X-Token: bar

响应结果是：

{
    "X-Token values": [
        "bar",
        "foo"
    ]
}

小结¶

使用 Header 声明请求头的方式与 Query、Path 、Cookie 相同。

不用担心变量中的下划线，FastAPI 可以自动转换。

Header 参数¶

导入 Header¶

声明 Header 参数¶

自动转换¶

重复的请求头¶

小结¶

导入 `Header`¶

声明 `Header` 参数¶