2026/9/7 5:16:33
FEATURED · 精选文章 
FastAPI Cookie 参数模型用 Pydantic 模型统一声明、校验与复用 Cookie 参数【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本篇技术指南基于 FastAPI 官方文档中的《Cookie-Parameter-Modelle》Cookie 参数模型章节展开讲解如何用一个 Pydantic 模型集中声明一组逻辑相关的 Cookie实现跨多端点复用、统一校验与批量元数据配置。读完本文你将掌握Annotated[Model, Cookie()]的声明方式、/docs文档界面的 Cookie 限制、通过model_config {extra: forbid}禁止额外 Cookie 的用法以及该机制在 FastAPI 源码中的字段提取与验证链路。背景用 Pydantic 模型声明一组 Cookie当你的 API 有一组逻辑上属于同一业务域的 Cookie例如会话 ID 加若干个跟踪 Cookie逐个用Annotated[str, Cookie()]声明会变得冗长且难以维护。此时可以创建一个Pydantic 模型来集中声明它们。这样带来两个直接收益多端点复用同一个模型可以在多个路径操作path operation中重复使用统一校验与元数据一次声明即可为所有参数同时定义校验规则和元数据。注意该特性自 FastAPI 版本0.115.0起受支持。提示同样的技术同样适用于Query、Cookie和Header三种参数位置。基础示例Cookie 绑定 Pydantic 模型声明所需的Cookie字段到一个Pydantic 模型中然后在端点签名里把该参数标注为Cookie示例代码见 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 cookiesFastAPI会针对每个字段从请求中携带的Cookie里提取对应数据并向你提供定义好的 Pydantic 模型实例session_id: str是必填字段客户端必须发送该 Cookie否则返回 422fatebook_tracker与googall_tracker默认为None即允许缺失端点直接return cookiesFastAPI 会把模型序列化后作为响应体返回方便联调时直观确认提取结果。源码视角字段从哪里提取从源码结构看Cookie参数类定义在 fastapi/params.py 中它继承自Param并通过in_ ParamTypes.cookie标记参数来源位置。请求处理时fastapi/dependencies/utils.py 会按参数位置把字段收集到cookie_params列表并在_get_flat_fields_from_params()中对“单个模型参数”做字段展开——也就是说FastAPI 把模型注解的每个子字段视作独立的 Cookie 参数从请求头Cookie中逐一取值后交给 Pydantic 完成校验与组装模型实例最终以参数形式注入到路径操作函数中。在文档界面/docs中测试你可以在/docs文档界面看到已定义的 Cookie 模型参数上图即/docs中该端点的表单模型字段被展平为独立的 Cookie 输入项。需要特别注意浏览器对 Cookie 的安全限制浏览器以特殊方式在后台管理 Cookie不允许JavaScript随意读写任意 Cookie因此即使你在/docs界面中填写数据并点击“运行”Execute文档界面背后的 JavaScript 也无法实际把这些 Cookie 附加到请求上结果是你会看到一条错误响应表现如同你没有输入任何值必填的session_id缺失导致 422。所以验证 Cookie 参数应使用curl -b或带 Cookie 的测试客户端如TestClient而不是/docs界面的“运行”按钮。禁止额外 Cookieextra forbid在一些特殊应用场景中虽然并不常见你希望限制客户端只能发送你声明过的 Cookie——你的 API 由此获得了控制自己“Cookie 同意权”Cookie 同意的玩笑的能力。可以使用 Pydantic 的模型配置把extra字段设为forbid完整示例见 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当客户端尝试发送任何额外 Cookie时会收到一条错误响应Error-Response。例如客户端发送一个值为good-list-please的santa_trackerCookie 显然不批准缺少 Cookie 的行为会得到如下响应{ detail: [ { type: extra_forbidden, loc: [cookie, santa_tracker], msg: Extra inputs are not permitted, input: good-list-please, } ] }错误位置loc为[cookie, santa_tracker]类型extra_forbidden与 Pydantic v2 的标准校验错误结构一致。补充extra的另一种模式与多值行为官方测试 tests/test_query_cookie_header_model_extra_params.py 覆盖了model_config {extra: allow}的场景未声明的 Cookie如param2会被原样收集进模型并返回。其中test_cookie_pass_extra_list还揭示了一个 HTTP 语义细节——当客户端对同一 Cookie 名发送多个值时param2456与param2789Cookie 头只保留最后一个值测试断言param2 789这与 Query/Header 可以保留列表值的行为不同。设计 Cookie 模型时字段应假定每个 Cookie 名只有单个字符串值。小结可以使用Pydantic 模型在FastAPI中集中声明Cookie在离开前再拿最后一块 Cookie模型参数需以Annotated[Cookies, Cookie()]形式标注字段自动从请求 Cookie 中逐一提取并校验该写法自 FastAPI0.115.0支持且同样适用于Query与Header需要白名单式控制时用model_config {extra: forbid}拒绝未声明的 Cookie/docs界面只能查看 Cookie 表单而不能真正发送 Cookie 请求实测请走curl -b或测试客户端。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
FastAPI Cookie 参数模型：用 Pydantic 模型统一声明、校验与复用 Cookie 参数
FastAPI Cookie 参数模型用 Pydantic 模型统一声明、校验与复用 Cookie 参数【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本篇技术指南基于 FastAPI 官方文档中的《Cookie-Parameter-Modelle》Cookie 参数模型章节展开讲解如何用一个 Pydantic 模型集中声明一组逻辑相关的 Cookie实现跨多端点复用、统一校验与批量元数据配置。读完本文你将掌握Annotated[Model, Cookie()]的声明方式、/docs文档界面的 Cookie 限制、通过model_config {extra: forbid}禁止额外 Cookie 的用法以及该机制在 FastAPI 源码中的字段提取与验证链路。背景用 Pydantic 模型声明一组 Cookie当你的 API 有一组逻辑上属于同一业务域的 Cookie例如会话 ID 加若干个跟踪 Cookie逐个用Annotated[str, Cookie()]声明会变得冗长且难以维护。此时可以创建一个Pydantic 模型来集中声明它们。这样带来两个直接收益多端点复用同一个模型可以在多个路径操作path operation中重复使用统一校验与元数据一次声明即可为所有参数同时定义校验规则和元数据。注意该特性自 FastAPI 版本0.115.0起受支持。提示同样的技术同样适用于Query、Cookie和Header三种参数位置。基础示例Cookie 绑定 Pydantic 模型声明所需的Cookie字段到一个Pydantic 模型中然后在端点签名里把该参数标注为Cookie示例代码见 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 cookiesFastAPI会针对每个字段从请求中携带的Cookie里提取对应数据并向你提供定义好的 Pydantic 模型实例session_id: str是必填字段客户端必须发送该 Cookie否则返回 422fatebook_tracker与googall_tracker默认为None即允许缺失端点直接return cookiesFastAPI 会把模型序列化后作为响应体返回方便联调时直观确认提取结果。源码视角字段从哪里提取从源码结构看Cookie参数类定义在 fastapi/params.py 中它继承自Param并通过in_ ParamTypes.cookie标记参数来源位置。请求处理时fastapi/dependencies/utils.py 会按参数位置把字段收集到cookie_params列表并在_get_flat_fields_from_params()中对“单个模型参数”做字段展开——也就是说FastAPI 把模型注解的每个子字段视作独立的 Cookie 参数从请求头Cookie中逐一取值后交给 Pydantic 完成校验与组装模型实例最终以参数形式注入到路径操作函数中。在文档界面/docs中测试你可以在/docs文档界面看到已定义的 Cookie 模型参数上图即/docs中该端点的表单模型字段被展平为独立的 Cookie 输入项。需要特别注意浏览器对 Cookie 的安全限制浏览器以特殊方式在后台管理 Cookie不允许JavaScript随意读写任意 Cookie因此即使你在/docs界面中填写数据并点击“运行”Execute文档界面背后的 JavaScript 也无法实际把这些 Cookie 附加到请求上结果是你会看到一条错误响应表现如同你没有输入任何值必填的session_id缺失导致 422。所以验证 Cookie 参数应使用curl -b或带 Cookie 的测试客户端如TestClient而不是/docs界面的“运行”按钮。禁止额外 Cookieextra forbid在一些特殊应用场景中虽然并不常见你希望限制客户端只能发送你声明过的 Cookie——你的 API 由此获得了控制自己“Cookie 同意权”Cookie 同意的玩笑的能力。可以使用 Pydantic 的模型配置把extra字段设为forbid完整示例见 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当客户端尝试发送任何额外 Cookie时会收到一条错误响应Error-Response。例如客户端发送一个值为good-list-please的santa_trackerCookie 显然不批准缺少 Cookie 的行为会得到如下响应{ detail: [ { type: extra_forbidden, loc: [cookie, santa_tracker], msg: Extra inputs are not permitted, input: good-list-please, } ] }错误位置loc为[cookie, santa_tracker]类型extra_forbidden与 Pydantic v2 的标准校验错误结构一致。补充extra的另一种模式与多值行为官方测试 tests/test_query_cookie_header_model_extra_params.py 覆盖了model_config {extra: allow}的场景未声明的 Cookie如param2会被原样收集进模型并返回。其中test_cookie_pass_extra_list还揭示了一个 HTTP 语义细节——当客户端对同一 Cookie 名发送多个值时param2456与param2789Cookie 头只保留最后一个值测试断言param2 789这与 Query/Header 可以保留列表值的行为不同。设计 Cookie 模型时字段应假定每个 Cookie 名只有单个字符串值。小结可以使用Pydantic 模型在FastAPI中集中声明Cookie在离开前再拿最后一块 Cookie模型参数需以Annotated[Cookies, Cookie()]形式标注字段自动从请求 Cookie 中逐一提取并校验该写法自 FastAPI0.115.0支持且同样适用于Query与Header需要白名单式控制时用model_config {extra: forbid}拒绝未声明的 Cookie/docs界面只能查看 Cookie 表单而不能真正发送 Cookie 请求实测请走curl -b或测试客户端。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
