Header 参数

你可以使用定义 Query, PathCookie 参数一样的方法定义 Header 参数。

导入 Header

首先导入 Header:

Python 3.10+Python 3.9+Python 3.8+Python 3.10+ non-AnnotatedPython 3.8+ non-Annotated

  1. from typing import Annotated
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(user_agent: Annotated[str | None, Header()] = None):
  6. return {"User-Agent": user_agent}
  1. from typing import Annotated, Union
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
  6. return {"User-Agent": user_agent}
  1. from typing import Union
  2. from fastapi import FastAPI, Header
  3. from typing_extensions import Annotated
  4. app = FastAPI()
  5. @app.get("/items/")
  6. async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
  7. return {"User-Agent": user_agent}

Tip

尽可能选择使用 Annotated 的版本。

  1. from fastapi import FastAPI, Header
  2. app = FastAPI()
  3. @app.get("/items/")
  4. async def read_items(user_agent: str | None = Header(default=None)):
  5. return {"User-Agent": user_agent}

Tip

尽可能选择使用 Annotated 的版本。

  1. from typing import Union
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(user_agent: Union[str, None] = Header(default=None)):
  6. return {"User-Agent": user_agent}

声明 Header 参数

然后使用和Path, Query and Cookie 一样的结构定义 header 参数

第一个值是默认值,你可以传递所有的额外验证或注释参数:

Python 3.10+Python 3.9+Python 3.8+Python 3.10+ non-AnnotatedPython 3.8+ non-Annotated

  1. from typing import Annotated
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(user_agent: Annotated[str | None, Header()] = None):
  6. return {"User-Agent": user_agent}
  1. from typing import Annotated, Union
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
  6. return {"User-Agent": user_agent}
  1. from typing import Union
  2. from fastapi import FastAPI, Header
  3. from typing_extensions import Annotated
  4. app = FastAPI()
  5. @app.get("/items/")
  6. async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
  7. return {"User-Agent": user_agent}

Tip

尽可能选择使用 Annotated 的版本。

  1. from fastapi import FastAPI, Header
  2. app = FastAPI()
  3. @app.get("/items/")
  4. async def read_items(user_agent: str | None = Header(default=None)):
  5. return {"User-Agent": user_agent}

Tip

尽可能选择使用 Annotated 的版本。

  1. from typing import Union
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(user_agent: Union[str, None] = Header(default=None)):
  6. return {"User-Agent": user_agent}

技术细节

HeaderPath, QueryCookie 的兄弟类型。它也继承自通用的 Param 类.

但是请记得,当你从fastapi导入 Query, Path, Header, 或其他时,实际上导入的是返回特定类型的函数。

Info

为了声明headers, 你需要使用Header, 因为否则参数将被解释为查询参数。

自动转换

HeaderPath, QueryCookie 提供的功能之上有一点额外的功能。

大多数标准的headers用 “连字符” 分隔,也称为 “减号” (-)。

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

因此, 默认情况下, Header 将把参数名称的字符从下划线 (_) 转换为连字符 (-) 来提取并记录 headers.

同时,HTTP headers 是大小写不敏感的,因此,因此可以使用标准Python样式(也称为 “snake_case”)声明它们。

因此,您可以像通常在Python代码中那样使用 user_agent ,而不需要将首字母大写为 User_Agent 或类似的东西。

如果出于某些原因,你需要禁用下划线到连字符的自动转换,设置Header的参数 convert_underscoresFalse:

Python 3.10+Python 3.9+Python 3.8+Python 3.10+ non-AnnotatedPython 3.8+ non-Annotated

  1. from typing import Annotated
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(
  6. strange_header: Annotated[str | None, Header(convert_underscores=False)] = None
  7. ):
  8. return {"strange_header": strange_header}
  1. from typing import Annotated, Union
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(
  6. strange_header: Annotated[
  7. Union[str, None], Header(convert_underscores=False)
  8. ] = None
  9. ):
  10. return {"strange_header": strange_header}
  1. from typing import Union
  2. from fastapi import FastAPI, Header
  3. from typing_extensions import Annotated
  4. app = FastAPI()
  5. @app.get("/items/")
  6. async def read_items(
  7. strange_header: Annotated[
  8. Union[str, None], Header(convert_underscores=False)
  9. ] = None
  10. ):
  11. return {"strange_header": strange_header}

Tip

尽可能选择使用 Annotated 的版本。

  1. from fastapi import FastAPI, Header
  2. app = FastAPI()
  3. @app.get("/items/")
  4. async def read_items(
  5. strange_header: str | None = Header(default=None, convert_underscores=False)
  6. ):
  7. return {"strange_header": strange_header}

Tip

尽可能选择使用 Annotated 的版本。

  1. from typing import Union
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(
  6. strange_header: Union[str, None] = Header(default=None, convert_underscores=False)
  7. ):
  8. return {"strange_header": strange_header}

Warning

在设置 convert_underscoresFalse 之前,请记住,一些HTTP代理和服务器不允许使用带有下划线的headers。

重复的 headers

有可能收到重复的headers。这意味着,相同的header具有多个值。

您可以在类型声明中使用一个list来定义这些情况。

你可以通过一个Python list 的形式获得重复header的所有值。

比如, 为了声明一个 X-Token header 可以出现多次,你可以这样写:

Python 3.10+Python 3.9+Python 3.8+Python 3.10+ non-AnnotatedPython 3.9+ non-AnnotatedPython 3.8+ non-Annotated

  1. from typing import Annotated
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(x_token: Annotated[list[str] | None, Header()] = None):
  6. return {"X-Token values": x_token}
  1. from typing import Annotated, List, Union
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
  6. return {"X-Token values": x_token}
  1. from typing import List, Union
  2. from fastapi import FastAPI, Header
  3. from typing_extensions import Annotated
  4. app = FastAPI()
  5. @app.get("/items/")
  6. async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
  7. return {"X-Token values": x_token}

Tip

Prefer to use the Annotated version if possible.

  1. from fastapi import FastAPI, Header
  2. app = FastAPI()
  3. @app.get("/items/")
  4. async def read_items(x_token: list[str] | None = Header(default=None)):
  5. return {"X-Token values": x_token}

Tip

尽可能选择使用 Annotated 的版本。

  1. from typing import Union
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(x_token: Union[list[str], None] = Header(default=None)):
  6. return {"X-Token values": x_token}

Tip

尽可能选择使用 Annotated 的版本。

  1. from typing import List, Union
  2. from fastapi import FastAPI, Header
  3. app = FastAPI()
  4. @app.get("/items/")
  5. async def read_items(x_token: Union[List[str], None] = Header(default=None)):
  6. return {"X-Token values": x_token}

如果你与路径操作通信时发送两个HTTP headers,就像:

  1. X-Token: foo
  2. X-Token: bar

响应会是:

  1. {
  2. "X-Token values": [
  3. "bar",
  4. "foo"
  5. ]
  6. }

回顾

使用 Header 来声明 header , 使用和 Query, PathCookie 相同的模式。

不用担心变量中的下划线,FastAPI 会负责转换它们。