笙亿网络策划

FastAPI怎么处理请求头和Cookie？

约 5 分钟读完 10 阅
文章导读
FastAPI 提供了 Header 和 Cookie 类型，用于从 HTTP 请求头和 Cookie 中获取数据。
📋 目录
  1. 壹 请求头参数
  2. 贰 实例
  3. 叁 请求头的自动转换
  4. 肆 实例
  5. 伍 接收重复的请求头
  6. 陆 实例
  7. 柒 Cookie 参数
  8. 捌 实例
  9. 玖 请求头与 Cookie 同时使用
  10. 拾 实例
A A

FastAPI 请求头与 Cookie

FastAPI 提供了 Header 和 Cookie 类型，用于从 HTTP 请求头和 Cookie 中获取数据。

请求头参数

使用 Header 声明请求头参数：

实例

from typing import Annotated
from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    # 接收 User-Agent 请求头
    user_agent: Annotated[str | None, Header()] = None,
):
    return {"User-Agent": user_agent}

访问 http://127.0.0.1:8000/items/，返回的 JSON 中包含浏览器的 User-Agent 信息。

请求头的自动转换

HTTP 请求头中的字段名使用连字符（如 X-Token），而 Python 变量名不能包含连字符。FastAPI 会自动进行转换：

实例

from typing import Annotated
from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    # Python 变量名用下划线，FastAPI 自动转换为 X-Token 请求头
    x_token: Annotated[list[str] | None, Header()] = None,
):
    return {"X-Token values": x_token}

转换规则：

Python 变量名HTTP 请求头说明
x_tokenX-Token下划线自动转为连字符
user_agentUser-Agent同上
content_typeContent-Type同上

FastAPI 自动将变量名中的下划线 _ 转换为连字符 - 来匹配请求头。如果你需要禁用此转换，设置 Header(convert_underscores=False)。

接收重复的请求头

有些请求头可能出现多次（如 Set-Cookie），使用 list 类型接收：

实例

from typing import Annotated
from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    # 接收多个 X-Token 请求头
    x_token: Annotated[list[str] | None, Header()] = None,
):
    return {"X-Token values": x_token}

请求示例：

GET /items/ HTTP/1.1
X-Token: foo
X-Token: bar

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

Cookie 参数

使用 Cookie 声明 Cookie 参数：

实例

from typing import Annotated
from fastapi import FastAPI, Cookie

app = FastAPI()


@app.get("/items/")
async def read_items(
    # 接收名为 session_token 的 Cookie
    session_token: Annotated[str | None, Cookie()] = None,
):
    return {"session_token": session_token}

请求头与 Cookie 同时使用

可以在同一个路由中同时获取请求头和 Cookie：

实例

from typing import Annotated
from fastapi import FastAPI, Header, Cookie

app = FastAPI()


@app.get("/items/")
async def read_items(
    user_agent: Annotated[str | None, Header()] = None,
    session_token: Annotated[str | None, Cookie()] = None,
    ads_id: Annotated[str | None, Cookie()] = None,
):
    return {
        "User-Agent": user_agent,
        "Session-Token": session_token,
        "Ads-ID": ads_id,
    }

小结

  • 使用 Header 获取 HTTP 请求头参数
  • 使用 Cookie 获取 Cookie 参数
  • FastAPI 自动将 Python 变量名中的下划线转为请求头中的连字符
  • 使用 list[str] 接收重复的请求头
  • 请求头和 Cookie 参数支持与查询参数相同的校验规则