Skip to content

Cookie 参数模型

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

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

/// 注意

自 FastAPI 版本 0.115.0 起支持此功能。🤓

///

/// 提示

这种技术同样适用于 Query、Cookie 和 Header。😎

///

使用 Pydantic 模型的 Cookies

在 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.9+

from typing import Annotated, Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[str, None] = None


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

////

//// 标签 | Python 3.8+

from typing import Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel
from typing_extensions import Annotated

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[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

////

//// 标签 | Python 3.8+ 非 Annotated

/// 提示

如果可能，建议使用 Annotated 版本。

///

from typing import Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[str, None] = None


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

////

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

查看文档

你可以在 /docs 的文档 UI 中看到定义的 cookies：

/// 信息

请注意，由于 浏览器以特殊方式处理 cookies 并且在幕后操作，它们 不允许 JavaScript 轻松访问它们。

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

但即使你 填写数据 并点击 "Execute"，由于文档 UI 使用 JavaScript，cookies 不会被发送，你将看到一个 错误 消息，就好像你没有写任何值一样。

///

禁止额外的 Cookies

在某些特殊用例（可能不是很常见）中，你可能希望 限制 你想要接收的 cookies。

你的 API 现在有能力控制自己的 cookie 同意。🤪🍪

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

//// 标签 | Python 3.9+

from typing import Annotated, Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[str, None] = None


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

////

//// 标签 | Python 3.8+

from typing import Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel
from typing_extensions import Annotated

app = FastAPI()


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

    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[str, None] = None


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

////

//// 标签 | Python 3.8+ 非 Annotated

/// 提示

如果可能，建议使用 Annotated 版本。

///

from typing import Union

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    session_id: str
    fatebook_tracker: Union[str, None] = None
    googall_tracker: Union[str, None] = None


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

////

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

可怜的 cookie 横幅，它们努力争取你的同意，以便 API 拒绝它。🍪

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

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["cookie", "santa_tracker"],
            "msg": "不允许额外的输入",
            "input": "good-list-please",
        }
    ]
}

总结

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