2026/9/8 20:24:12
FEATURED · 精选文章 
FastAPI Cookie 参数模型Cookie Parameter Models用 Pydantic 模型统一声明、校验与限制 Cookie【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi在 FastAPI 中当一组Cookie彼此相关时例如会话 ID、多个跟踪器 Cookie你可以把它们收敛到一个Pydantic model中整体声明并在路径操作函数中用一个Cookie参数接收整个模型。本篇文章将围绕 FastAPI 官方教程文档见 docs/en/docs/tutorial/cookie-param-models.md以及对应的 docs/hi/docs/tutorial/cookie-param-models.md 译文讲解如何定义 Cookie 参数模型、FastAPI 如何自动从请求中提取每个字段并完成校验、如何生成对应的/docs接口文档以及如何通过 Pydantic 的extra: forbid配置拒绝客户端发送的多余 Cookie。读完本文你将能写出可复用、可集中校验、可自动生成 OpenAPI 文档的 Cookie 参数代码并理解其底层工作方式。什么是 Cookie 参数模型按官方文档的说法原文用一句俏皮话开场If you have a group of cookies that are related, you can create a Pydantic model to declare them当一个接口需要同时读取多个 Cookie 时逐个用cookie_params: str Cookie()这类写法会显得零散。更优雅的做法是先定义一个Pydantic model把所有需要的 Cookie 字段、默认值、校验与元数据集中声明然后在路径操作函数中把参数类型标成该 model并用Cookie()作为其声明方式FastAPI 会自动从请求携带的 cookies 中逐个字段提取数据并组装成该 model 的实例交给你的函数。好处官方文档同样强调model 可以在多处复用所有参数的 validations 和 metadata 可以一次性声明。需要留意两个前提文档中的 note 与 tip该特性自FastAPI0.115.0版本起支持相同的技术同样适用于Query、Cookie和Header即 Pydantic 查询参数模型、请求头参数模型也是同一套机制。用 Pydantic Model 声明一组 Cookies完整可运行的示例代码在仓库的 docs_src/cookie_param_models/tutorial001_an_py310.pyfrom 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要点拆解model 字段即 Cookie 名Pydantic modelCookies中的每个字段session_id、fatebook_tracker、googall_tracker就是客户端请求中携带的 Cookie 名称必填与可选session_id: str没有默认值因此是必填 Cookie另外两个字段用str | None None声明为可选缺省时值为None接收方式路径操作参数cookies: Annotated[Cookies, Cookie()]告诉 FastAPI 该参数来自 CookieCookie()而其类型注解Cookies表明应使用 Pydantic model 来组装。对于不使用Annotated的写法等价可参考 docs_src/cookie_param_models/tutorial001_py310.pyfrom 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运行后例如客户端请求携带了Cookie: session_idabc123; fatebook_trackerxyz那么函数收到的cookies就是一个字段值为{session_id: abc123, fatebook_tracker: xyz, googall_tracker: None}的Cookies实例接口直接把它作为 JSON 返回。为什么能这样写底层依赖解析机制你可能会好奇“一个Cookie参数如何撑起多个 Cookie 字段”。从源码看这套能力由 FastAPI 的依赖参数处理逻辑实现核心在 fastapi/dependencies/utils.pyadd_param_to_fields()第 550-563 行附近根据ParamTypes.cookie把参数归入dependant.cookie_params真正的提取发生在request_params_to_args()第 780-850 行附近当len(fields) 1且该字段的类型注解是BaseModel子类时FastAPI 会把请求中收到的全部 cookie 收集成一个params_to_process字典第 830-839 行再交给_validate_value_with_model_field()用你定义的 Pydantic model 做整体校验第 841-850 行最终返回{first_field.name: v_}即组装好的 model 实例。也就是说模型级校验含必填、可选、以及下文要讲的extra限制都发生在用 model 对整包 cookie 字典做验证这一步。这也是为什么session_id缺失时能正确报出loc: [cookie, session_id]这样的校验错误。在 OpenAPI 文档一侧fastapi/openapi/utils.py 中的_get_flat_fields_from_params()第 169-172 行以及_get_openapi_operation_parameters()第 159-209 行会把“单个 Pydantic model 参数”摊平flatten成多个in: cookie的独立参数写入 schema因此接口文档中每个 Cookie 字段都单独列出。在 /docs 接口文档中查看与实测按官方文档说明在/docs的 Swagger UI 中可以看到路径操作声明的所有 cookies它们会以cookie类型的参数形式逐项展示。仓库中存在对应的运行截图 docs/en/docs/img/tutorial/cookie-param-models/image01.png注意各语言文档共用同一静态资源图片标题即Cookie Parameter Models教程的 docs UI 效果图不过官方文档特别提醒配合上图一起理解浏览器会以特殊且“幕后”的方式处理 Cookie并不允许 JavaScript 轻易读写它们。docs UI 本身是用 JavaScript 驱动的因此即便你在界面上填好数据并点击 “Execute”cookie 也不会被真正发送最终你会看到一条“好像什么都没填”的报错。这意味着仅靠 Swagger UI 无法端到端验证 Cookie 参数。想要手动实测应改用真正的 HTTP 客户端如curl -H Cookie: ...、Postman 或浏览器开发者工具中的请求它们能按需设置Cookie头。用 TestClient 验证对应仓库测试仓库的自动化测试正好演示了“真正携带 Cookie”的验证方式见 tests/test_tutorial/test_cookie_param_models/test_tutorial001.py。测试覆盖了三种情况全部字段齐全test_cookie_param_model通过client.cookies.set(...)依次写入三个 cookie 后请求/items/断言返回{session_id: 123, fatebook_tracker: 456, googall_tracker: 789}只给必填项test_cookie_param_model_defaults仅设置session_id其余两个字段按 model 默认值返回None缺少必填项test_cookie_param_model_invalid不设置任何 cookie 时得到422错误结构为{type: missing, loc: [cookie, session_id], msg: Field required, input: {}}。同一文件中test_openapi_schema还断言了生成的 OpenAPI schemasession_id是required: true的in: cookie参数两个可选字段则被声明为anyOf: [string, null]充分印证了文档中“每个 model 字段都会被展开为独立 cookie 参数”的描述。限制接收的 Cookiesforbid extra fields在少数特殊场景下你可能希望收紧API 接收的 Cookie 集合官方文档把它调侃成“API 也能拥有自己的 cookie 同意权”。这可以通过 Pydantic 的 model 配置实现——把extra设为forbid任何不在 model 中声明的多余 cookie 字段都会被拒绝。可运行示例在 docs_src/cookie_param_models/tutorial002_an_py310.pyfrom 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非Annotated等价写法见 docs_src/cookie_param_models/tutorial002_py310.py核心只有一处差别——model 定义中加入model_config {extra: forbid}。说明model_config是 Pydantic v2 的写法等价于 v1 中class Config: extra forbid。本仓库当前代码基按 Pydantic v2 风格声明。开启后如果客户端试图发送一个 model 之外的 cookie例如发送名为santa_tracker、值为good-list-please的 cookie客户端会收到如下422校验错误响应原文给出的示例 JSON{ detail: [ { type: extra_forbidden, loc: [cookie, santa_tracker], msg: Extra inputs are not permitted, input: good-list-please, } ] }这里的loc: [cookie, santa_tracker]精确指出了问题出处在 cookie 来源中santa_tracker属于未被允许的额外输入。forbid 行为的测试佐证对应测试见 tests/test_tutorial/test_cookie_param_models/test_tutorial002.pytest_cookie_param_model/test_cookie_param_model_defaults合法 cookie 正常返回200缺省字段回落为Nonetest_cookie_param_model_invalid缺少必填session_id返回422type: missingtest_cookie_param_model_extra当额外发送一个名为extra、值为track-me-here-too的 cookie 时响应为422错误体与上面 JSON 结构一致只是loc变为[cookie, extra]、input变为track-me-here-too。值得注意的是对比 test_tutorial001.py 中同名test_cookie_param_model_extra的用例——在未设置extra: forbid的 tutorial001 模型下多余 cookie 会被静默忽略并返回200而开启forbid后则转为422报错。这说明“是否容忍额外 cookie”完全由 Pydantic model 的配置决定两种策略各有用武之地。小结与最佳实践依据官方文档的总结你完全可以使用 Pydantic model 来声明 FastAPI 中的 cookies。结合本文源码与测试证据实践要点可归纳为聚合声明把一组相关的 Cookie 定义为 Pydantic model 字段用Annotated[Model, Cookie()]或model: Model Cookie()接收替代逐个Cookie()参数的写法集中校验与复用必填、默认值、类型等规则集中在 model 内可在多个路径操作间复用缺少必填 Cookie 时自动返回带loc: [cookie, ...]的422限制多余 Cookie需要严格控制输入时在 model 上设置model_config {extra: forbid}越界 cookie 会触发extra_forbidden错误默认情况下多余 cookie 会被忽略注意文档 UI 局限浏览器安全策略导致 Swagger UI 无法发送 cookie端到端调试请使用能自由设置Cookie头的 HTTP 客户端参考测试中用TestClient的client.cookies.set(...)思路该模式可推广同一技术在Query与Header参数上同样适用本次文档基于 Cookie 展开相关机制可进一步查阅教程中 query/header 参数模型章节以及 fastapi/openapi/utils.py 中参数展平逻辑。更进一步想研究实现细节可顺藤摸瓜阅读三处核心代码负责参数分类的 fastapi/dependencies/utils.py、负责“用模型校验整包 cookie”的request_params_to_args同文件 fastapi/dependencies/utils.py以及负责把模型摊平成多个 OpenAPI cookie 参数的 fastapi/openapi/utils.py。对照官方的教程原文 docs/en/docs/tutorial/cookie-param-models.md 阅读效果最佳。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
FastAPI Cookie 参数模型（Cookie Parameter Models）：用 Pydantic 模型统一声明、校验与限制 Cookie
FastAPI Cookie 参数模型Cookie Parameter Models用 Pydantic 模型统一声明、校验与限制 Cookie【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi在 FastAPI 中当一组Cookie彼此相关时例如会话 ID、多个跟踪器 Cookie你可以把它们收敛到一个Pydantic model中整体声明并在路径操作函数中用一个Cookie参数接收整个模型。本篇文章将围绕 FastAPI 官方教程文档见 docs/en/docs/tutorial/cookie-param-models.md以及对应的 docs/hi/docs/tutorial/cookie-param-models.md 译文讲解如何定义 Cookie 参数模型、FastAPI 如何自动从请求中提取每个字段并完成校验、如何生成对应的/docs接口文档以及如何通过 Pydantic 的extra: forbid配置拒绝客户端发送的多余 Cookie。读完本文你将能写出可复用、可集中校验、可自动生成 OpenAPI 文档的 Cookie 参数代码并理解其底层工作方式。什么是 Cookie 参数模型按官方文档的说法原文用一句俏皮话开场If you have a group of cookies that are related, you can create a Pydantic model to declare them当一个接口需要同时读取多个 Cookie 时逐个用cookie_params: str Cookie()这类写法会显得零散。更优雅的做法是先定义一个Pydantic model把所有需要的 Cookie 字段、默认值、校验与元数据集中声明然后在路径操作函数中把参数类型标成该 model并用Cookie()作为其声明方式FastAPI 会自动从请求携带的 cookies 中逐个字段提取数据并组装成该 model 的实例交给你的函数。好处官方文档同样强调model 可以在多处复用所有参数的 validations 和 metadata 可以一次性声明。需要留意两个前提文档中的 note 与 tip该特性自FastAPI0.115.0版本起支持相同的技术同样适用于Query、Cookie和Header即 Pydantic 查询参数模型、请求头参数模型也是同一套机制。用 Pydantic Model 声明一组 Cookies完整可运行的示例代码在仓库的 docs_src/cookie_param_models/tutorial001_an_py310.pyfrom 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要点拆解model 字段即 Cookie 名Pydantic modelCookies中的每个字段session_id、fatebook_tracker、googall_tracker就是客户端请求中携带的 Cookie 名称必填与可选session_id: str没有默认值因此是必填 Cookie另外两个字段用str | None None声明为可选缺省时值为None接收方式路径操作参数cookies: Annotated[Cookies, Cookie()]告诉 FastAPI 该参数来自 CookieCookie()而其类型注解Cookies表明应使用 Pydantic model 来组装。对于不使用Annotated的写法等价可参考 docs_src/cookie_param_models/tutorial001_py310.pyfrom 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运行后例如客户端请求携带了Cookie: session_idabc123; fatebook_trackerxyz那么函数收到的cookies就是一个字段值为{session_id: abc123, fatebook_tracker: xyz, googall_tracker: None}的Cookies实例接口直接把它作为 JSON 返回。为什么能这样写底层依赖解析机制你可能会好奇“一个Cookie参数如何撑起多个 Cookie 字段”。从源码看这套能力由 FastAPI 的依赖参数处理逻辑实现核心在 fastapi/dependencies/utils.pyadd_param_to_fields()第 550-563 行附近根据ParamTypes.cookie把参数归入dependant.cookie_params真正的提取发生在request_params_to_args()第 780-850 行附近当len(fields) 1且该字段的类型注解是BaseModel子类时FastAPI 会把请求中收到的全部 cookie 收集成一个params_to_process字典第 830-839 行再交给_validate_value_with_model_field()用你定义的 Pydantic model 做整体校验第 841-850 行最终返回{first_field.name: v_}即组装好的 model 实例。也就是说模型级校验含必填、可选、以及下文要讲的extra限制都发生在用 model 对整包 cookie 字典做验证这一步。这也是为什么session_id缺失时能正确报出loc: [cookie, session_id]这样的校验错误。在 OpenAPI 文档一侧fastapi/openapi/utils.py 中的_get_flat_fields_from_params()第 169-172 行以及_get_openapi_operation_parameters()第 159-209 行会把“单个 Pydantic model 参数”摊平flatten成多个in: cookie的独立参数写入 schema因此接口文档中每个 Cookie 字段都单独列出。在 /docs 接口文档中查看与实测按官方文档说明在/docs的 Swagger UI 中可以看到路径操作声明的所有 cookies它们会以cookie类型的参数形式逐项展示。仓库中存在对应的运行截图 docs/en/docs/img/tutorial/cookie-param-models/image01.png注意各语言文档共用同一静态资源图片标题即Cookie Parameter Models教程的 docs UI 效果图不过官方文档特别提醒配合上图一起理解浏览器会以特殊且“幕后”的方式处理 Cookie并不允许 JavaScript 轻易读写它们。docs UI 本身是用 JavaScript 驱动的因此即便你在界面上填好数据并点击 “Execute”cookie 也不会被真正发送最终你会看到一条“好像什么都没填”的报错。这意味着仅靠 Swagger UI 无法端到端验证 Cookie 参数。想要手动实测应改用真正的 HTTP 客户端如curl -H Cookie: ...、Postman 或浏览器开发者工具中的请求它们能按需设置Cookie头。用 TestClient 验证对应仓库测试仓库的自动化测试正好演示了“真正携带 Cookie”的验证方式见 tests/test_tutorial/test_cookie_param_models/test_tutorial001.py。测试覆盖了三种情况全部字段齐全test_cookie_param_model通过client.cookies.set(...)依次写入三个 cookie 后请求/items/断言返回{session_id: 123, fatebook_tracker: 456, googall_tracker: 789}只给必填项test_cookie_param_model_defaults仅设置session_id其余两个字段按 model 默认值返回None缺少必填项test_cookie_param_model_invalid不设置任何 cookie 时得到422错误结构为{type: missing, loc: [cookie, session_id], msg: Field required, input: {}}。同一文件中test_openapi_schema还断言了生成的 OpenAPI schemasession_id是required: true的in: cookie参数两个可选字段则被声明为anyOf: [string, null]充分印证了文档中“每个 model 字段都会被展开为独立 cookie 参数”的描述。限制接收的 Cookiesforbid extra fields在少数特殊场景下你可能希望收紧API 接收的 Cookie 集合官方文档把它调侃成“API 也能拥有自己的 cookie 同意权”。这可以通过 Pydantic 的 model 配置实现——把extra设为forbid任何不在 model 中声明的多余 cookie 字段都会被拒绝。可运行示例在 docs_src/cookie_param_models/tutorial002_an_py310.pyfrom 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非Annotated等价写法见 docs_src/cookie_param_models/tutorial002_py310.py核心只有一处差别——model 定义中加入model_config {extra: forbid}。说明model_config是 Pydantic v2 的写法等价于 v1 中class Config: extra forbid。本仓库当前代码基按 Pydantic v2 风格声明。开启后如果客户端试图发送一个 model 之外的 cookie例如发送名为santa_tracker、值为good-list-please的 cookie客户端会收到如下422校验错误响应原文给出的示例 JSON{ detail: [ { type: extra_forbidden, loc: [cookie, santa_tracker], msg: Extra inputs are not permitted, input: good-list-please, } ] }这里的loc: [cookie, santa_tracker]精确指出了问题出处在 cookie 来源中santa_tracker属于未被允许的额外输入。forbid 行为的测试佐证对应测试见 tests/test_tutorial/test_cookie_param_models/test_tutorial002.pytest_cookie_param_model/test_cookie_param_model_defaults合法 cookie 正常返回200缺省字段回落为Nonetest_cookie_param_model_invalid缺少必填session_id返回422type: missingtest_cookie_param_model_extra当额外发送一个名为extra、值为track-me-here-too的 cookie 时响应为422错误体与上面 JSON 结构一致只是loc变为[cookie, extra]、input变为track-me-here-too。值得注意的是对比 test_tutorial001.py 中同名test_cookie_param_model_extra的用例——在未设置extra: forbid的 tutorial001 模型下多余 cookie 会被静默忽略并返回200而开启forbid后则转为422报错。这说明“是否容忍额外 cookie”完全由 Pydantic model 的配置决定两种策略各有用武之地。小结与最佳实践依据官方文档的总结你完全可以使用 Pydantic model 来声明 FastAPI 中的 cookies。结合本文源码与测试证据实践要点可归纳为聚合声明把一组相关的 Cookie 定义为 Pydantic model 字段用Annotated[Model, Cookie()]或model: Model Cookie()接收替代逐个Cookie()参数的写法集中校验与复用必填、默认值、类型等规则集中在 model 内可在多个路径操作间复用缺少必填 Cookie 时自动返回带loc: [cookie, ...]的422限制多余 Cookie需要严格控制输入时在 model 上设置model_config {extra: forbid}越界 cookie 会触发extra_forbidden错误默认情况下多余 cookie 会被忽略注意文档 UI 局限浏览器安全策略导致 Swagger UI 无法发送 cookie端到端调试请使用能自由设置Cookie头的 HTTP 客户端参考测试中用TestClient的client.cookies.set(...)思路该模式可推广同一技术在Query与Header参数上同样适用本次文档基于 Cookie 展开相关机制可进一步查阅教程中 query/header 参数模型章节以及 fastapi/openapi/utils.py 中参数展平逻辑。更进一步想研究实现细节可顺藤摸瓜阅读三处核心代码负责参数分类的 fastapi/dependencies/utils.py、负责“用模型校验整包 cookie”的request_params_to_args同文件 fastapi/dependencies/utils.py以及负责把模型摊平成多个 OpenAPI cookie 参数的 fastapi/openapi/utils.py。对照官方的教程原文 docs/en/docs/tutorial/cookie-param-models.md 阅读效果最佳。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
