Cookie 参数模型¶

如果你有一组相关的 Cookie，你可以创建一个 Pydantic 模型来声明它们。🍪

这样你就可以在多个地方重用该模型，并且可以一次性声明所有参数的验证和元数据。😎

注意

FastAPI 0.115.0 版本开始支持此功能。🤓

提示

同样的技巧也适用于 Query、Cookie 和 Header。😎

使用 Pydantic 模型处理 Cookie¶

在 Pydantic 模型中声明你需要的 Cookie 参数，然后将该参数声明为 Cookie。

Python 3.10+

from typing import Annotated

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Annotated[Cookies, Cookie()]):
    return cookies

🤓 其他版本和变体

Python 3.10+ - 非 Annotated

提示

如果可能，请优先使用 Annotated 版本。

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Cookies = Cookie()):
    return cookies

FastAPI 将会从请求中收到的 Cookie 中提取每个字段的数据，并为你提供你定义的 Pydantic 模型。

查看文档¶

你可以在 /docs 的文档 UI 中查看定义的 Cookie。

信息

请记住，由于浏览器处理 Cookie 的方式比较特殊，且在后台运行，它们并不轻易允许 JavaScript 触碰 Cookie。

如果你访问 /docs 的 API 文档 UI，你将能够看到你的路径操作对应的 Cookie 文档。

但即使你填写了数据并点击“Execute”，由于文档 UI 是通过 JavaScript 工作的，Cookie 不会被发送，你会看到一条错误消息，就像你没有填写任何值一样。

禁止额外的 Cookie¶

在某些特殊用例中（可能不太常见），你可能希望限制所接收的 Cookie。

你的 API 现在有权控制它自己的 Cookie 同意。🤪🍪

你可以使用 Pydantic 的模型配置来 forbid 任何 extra 字段

Python 3.10+

from typing import Annotated

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    model_config = {"extra": "forbid"}

    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Annotated[Cookies, Cookie()]):
    return cookies

🤓 其他版本和变体

Python 3.10+ - 非 Annotated

提示

如果可能，请优先使用 Annotated 版本。

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    model_config = {"extra": "forbid"}

    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Cookies = Cookie()):
    return cookies

如果客户端尝试发送一些额外的 Cookie，它们将收到一个错误响应。

可怜的 Cookie 横幅费尽心思想要获取你对 API 拒绝它的同意。🍪

例如，如果客户端尝试发送一个值为 good-list-please 的 santa_tracker Cookie，客户端将收到一个错误响应，告知它们 santa_tracker Cookie 是不允许的

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["cookie", "santa_tracker"],
            "msg": "Extra inputs are not permitted",
            "input": "good-list-please",
        }
    ]
}

总结¶

你可以使用 Pydantic 模型在 FastAPI 中声明 Cookie。😎