FastAPI 从 Pydantic v1 迁移到 Pydantic v2版本演进与渐进式迁移实战指南【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文围绕 FastAPI 官方文档 docs/fr/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md英文原版见 docs/en/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md展开系统讲解如何将老旧的 Pydantic v1 应用迁移到 Pydantic v2包括 FastAPI 各版本对 Pydantic 的支持历史、pydantic.v1兼容子模块的使用、FastAPI 为渐进式迁移提供的临时桥接能力以及如何借助bump-pydantic实现“一键”升级。读完本文你将掌握一套有测试兜底、可分批推进、在单个应用中同时暂存 v1/v2 模型的迁移路线并理解最新 FastAPI 为何必须使用 Pydantic v2 的源码级原因。迁移背景FastAPI 对 Pydantic v1/v2 的支持时间线如果你维护着一个较老的 FastAPI 应用很可能仍在使用 Pydantic 1.x。要理解迁移路径首先需要看清 FastAPI 各版本对 Pydantic 的兼容策略变化FastAPI 版本Pydantic 支持情况0.100.0同时兼容 Pydantic v1 或 v2取决于你实际安装的是哪一版0.119.0引入对pydantic.v1Pydantic v2 内置的 v1 子模块的部分支持为平滑迁移铺路0.126.0移除对原生 Pydantic v1 的支持但短时间内仍支持pydantic.v10.128.0连pydantic.v1的支持一并移除最新版本强制要求 Pydantic v2从当前仓库的依赖声明可以印证这一点在 pyproject.toml 中FastAPI 本体直接声明pydantic2.9.0示例代码与开发工具链同样要求pydantic2.9.0,3.0.0见 pyproject.toml。也就是说最新版 FastAPI 从安装层面就与 Pydantic v1 划清了界限。⚠️重要警告Python 3.14 是硬性分水岭Pydantic 团队已宣布不再为 Pydantic v1 提供面向最新 Python 版本的支持从 Python 3.14 起生效。这同时意味着pydantic.v1子模块在 Python 3.14 及以上版本中也不再受支持。如果你想使用最新版本的 Python 特性就必须确保自己使用的是 Pydantic v2。当前仓库中的“拒绝 v1”实现若你已经处于 FastAPI 0.128.0 之后的最新版本把pydantic.v1模型塞进应用会直接报错而不是静默降级。源码层面提供了专门的异常类型在 fastapi/exceptions.py 中定义了PydanticV1NotSupportedError(FastAPIError)语义即“检测到使用了不再受支持的 pydantic.v1 模型”在 fastapi/utils.py 中当某个注解被识别为 Pydantic v1 模型时直接抛出该异常提示“pydantic.v1 models are no longer supported by FastAPI. Please update the response model”在 fastapi/encoders.py 中也预留了同样语意的报错分支底层识别逻辑集中在 fastapi/_compat/shared.pyis_pydantic_v1_model_instance、is_pydantic_v1_model_class、annotation_is_pydantic_v1三个辅助函数共同负责探测实例、类和嵌套在Union中的 v1 类型源码中的TODO注释明确写着“待 Pydantic 完全移除 pydantic.v1 后删除本函数”。配套测试 tests/test_pydantic_v1_error.py 用六个用例系统覆盖了 v1 模型出现在各类位置的场景全部断言抛出PydanticV1NotSupportedError路径操作函数参数、函数返回类型注解、response_model参数、responses中额外响应模型、Union 联合类型以及**list[ModelV1]序列嵌套**。这说明新版 FastAPI 对 v1 模型的拒绝是全面且显式的。同时该测试文件开头通过skip_module_if_py_gte_314()来自 tests/utils.py在 Python ≥ 3.14 环境下整模块跳过——因为 Python 3.14 中连pydantic.v1导入都不可用了这也反向验证了文档中 Python 3.14 的警告。迁移前的第一道保险测试与持续集成正式开始升级前请务必确保你的应用有一套可靠的测试并在持续集成CI中自动运行。本文此处引用的测试指南以英文版 docs/en/docs/tutorial/testing.md 为权威来源FastAPI 官方提供了该指南的多语言翻译版本可在 docs/fr/docs/tutorial/ 等翻译目录下找到对应文档。测试是迁移的“安全网”依赖从 v1 换成 v2 后字段校验、类型序列化、错误信息格式等行为都会变化只有先跑通测试才能放心断言“升级后一切照旧”。整个迁移流程的第一原则就是改一步、跑一次测试、确认全绿再走下一步。优先尝试自动化bump-pydantic在你手写任何迁移代码之前先考虑自动化工具。对于大量“规规矩矩”的普通 Pydantic 模型没有重度自定义大部分迁移工作是可以脚本化完成的。bump-pydantic正是 Pydantic 官方团队出品的迁移辅助工具它能够自动改写迁移中需要变动的大部分代码例如把from pydantic import BaseModel之类的导入改写为 v2 等价形式自动处理 v1 到 v2 中改名/改签名的 API如验证器、Config、字段定义等同步调整受影响的类型注解与调用点。使用流程非常简单运行bump-pydantic对代码库执行自动改写运行你已有的测试套件检查一切是否仍然正常如果测试全绿迁移就在这一条命令后宣告完成。✨需要说明的是本仓库是只读的bump-pydantic需在你的本地项目副本中安装使用。它并非总能覆盖全部场景——如果你的模型包含复杂自定义逻辑请继续阅读下文的手动渐进式迁移方案。Pydantic v2 内置的 v1 兼容子模块pydantic.v1理解渐进迁移的钥匙是认识到Pydantic v2 把 Pydantic v1 的完整实现作为子模块pydantic.v1原样内置注意该子模块在 Python 3.14 及以上版本已不再受支持。这意味着你完全可以只安装最新版 Pydantic v2却仍然从pydantic.v1导入并运行旧的 v1 组件——效果等同于旧版 Pydantic v1 仍然可用。仓库中的示例 docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py 展示了最纯粹的形式from pydantic.v1 import BaseModel class Item(BaseModel): name: str description: str | None None size: float这段代码无需安装旧版 Pydantic只需 Pydantic v2 即可定义出一个“仍然是 v1 语义”的模型类。FastAPI 对pydantic.v1的桥接支持仅限 0.119.0 ~ 0.127.x⚠️版本范围警告FastAPI 对pydantic.v1模型的桥接支持于0.119.0 加入、0.128.0 移除它本质上是为迁移到 Pydantic v2 准备的临时拐杖。在最新版 FastAPI 中把pydantic.v1模型用于应用会直接抛出PydanticV1NotSupportedError见上文源码分析。本小节描述的临时支持只存在于那些旧版本中。从 FastAPI 0.119.0 起你可以在保持旧代码形态不变的前提下完成“换引擎”把 Pydantic 升级到最新 v2只改动 import让旧模型改从pydantic.v1子模块导入在很多情况下原有代码无需其他修改即可照常工作。参考 docs_src/pydantic_v1_in_v2/tutorial002_an_py310.pyfrom fastapi import FastAPI from pydantic.v1 import BaseModel class Item(BaseModel): name: str description: str | None None size: float app FastAPI() app.post(/items/) async def create_item(item: Item) - Item: return item这段代码除了 import 从pydantic换成pydantic.v1之外与 v1 时代的写法几乎毫无差别FastAPI 仍然能解析该模型、生成请求体验证与响应序列化。这就构成了“先换底层库、代码几乎不动”的第一步把大迁移拆成一次低风险的依赖升级。⚠️ 再次提醒由于 Pydantic 团队自 Python 3.14 起不再支持 Pydantic v1pydantic.v1在 Python 3.14 中同样不可用。如果你需要跟进最新 Python 版本最终归宿必然是 Pydantic v2。同一应用内混用 v1 与 v2 模型迁移并非一蹴而就真实工程中更现实的诉求是让 v1 与 v2 模型暂时共存。这需要精确理解 Pydantic 的边界约束。不被支持的用法v1/v2 模型相互嵌套Pydantic不支持在一个 v2 模型里把字段定义为 v1 模型反之亦然——两类模型在内部机制校验引擎、序列化协议、__fields__结构上并不互通不能作为对方字段类型直接嵌套被支持的用法各自独立的模型共存虽然不能嵌套但在同一应用中分别使用 v1 模型和 v2 模型是被允许的——只要它们彼此独立、各自内部自成体系更进一步在 FastAPI 的**同一条路径操作path operation**中混用两类模型都是可行的。参考 docs_src/pydantic_v1_in_v2/tutorial003_an_py310.pyfrom fastapi import FastAPI from pydantic import BaseModel as BaseModelV2 from pydantic.v1 import BaseModel class Item(BaseModel): name: str description: str | None None size: float class ItemV2(BaseModelV2): name: str description: str | None None size: float app FastAPI() app.post(/items/, response_modelItemV2) async def create_item(item: Item): return item这个例子巧妙地演示了渐进迁移的核心手段入参模型item仍是 Pydantic v1 模型而响应模型response_modelItemV2已经切换到 Pydantic v2。FastAPI 在 0.119.0 ~ 0.127.x 期间能够分别用 v1 引擎解析请求体、用 v2 引擎校验并序列化响应让一条接口先完成“输出侧”升级。v1 专用参数工具fastapi.temp_pydantic_v1_params如果你的 v1 模型还需要配合 FastAPI 特有的参数工具——Body、Query、Form等——在完成迁移前的过渡期内可以从fastapi.temp_pydantic_v1_params导入它们而不是普通的fastapi模块。见 docs_src/pydantic_v1_in_v2/tutorial004_an_py310.pyfrom typing import Annotated from fastapi import FastAPI from fastapi.temp_pydantic_v1_params import Body from pydantic.v1 import BaseModel class Item(BaseModel): name: str description: str | None None size: float app FastAPI() app.post(/items/) async def create_item(item: Annotated[Item, Body(embedTrue)]) - Item: return item这里通过Annotated[Item, Body(embedTrue)]把 v1 模型作为请求体参数接收。普通参数工具Body、Query、Form等在解析模型字段时默认面向 Pydantic v2 的字段信息结构fastapi.temp_pydantic_v1_params则提供了适配 v1 字段信息体系的对应实现从而让“过渡期接口”也能享受完整的参数声明能力。该模块名中的temptemporary直白地表明其临时性质——它只存在于 FastAPI 0.119.0 ~ 0.127.x当前源码树见仓库 fastapi/ 目录已不再包含该模块示例仅作历史参考。推荐路线分步骤渐进式迁移综合以上能力官方推荐的完整迁移路线如下。首先再次明确版本前提⚠️ 下文描述的“同一应用内同时使用 v1/v2 模型进行渐进迁移”只在 FastAPI 0.119.0 到 0.127.x 之间可用0.128.0 起该能力被移除最新版本要求全部使用Pydantic v2模型。先试自动化的建议优先跑一次bump-pydantic如果测试通过、一切正常一条命令就结束了只有自动工具在你的场景下行不通时才值得引入上述混用机制做手工渐进迁移。当bump-pydantic无法覆盖你的场景时按如下节奏推进升级引擎代码保持 v1 形态先把 Pydantic 升级到最新 v2然后把你所有模型的 import 改为使用pydantic.v1。此时应用行为与 v1 时代基本一致属于低风险过渡——这是整个迁移中风险最低、收益最高的一步。分组分批迁移模型开始按功能模块或业务边界把pydantic.v1模型分批迁回真正的 Pydantic v2from pydantic import BaseModel等原生导入。每迁移一组就跑一遍完整测试与 CI确保行为符合预期后再动下一组。收尾清理当所有模型都迁移到 v2 后删除pydantic.v1相关 import 与temp_pydantic_v1_params依赖最后升级到支持纯 v2 的最新 FastAPI 版本。至此整条渐进迁移之路走完。这套“先换引擎、再换模型、分组推进、测试护航”的路线之所以可行正是因为pydantic.v1子模块提供了完整、隔离的 v1 运行环境而 FastAPI0.119.0 ~ 0.127.x又允许两类模型在请求入参、响应模型甚至同一条路径操作中独立共存从而把一次“爆炸半径”巨大的全量重写拆解为多个可独立验证的小步骤。总结把 FastAPI 应用从 Pydantic v1 迁移到 v2本质上是一条先自动化、后渐进、全程由测试护航的路径版本坐标FastAPI 0.100 双兼容 → 0.119 支持pydantic.v1桥接 → 0.126 移除原生 v1 → 0.128 完全移除pydantic.v1当前仓库依赖pydantic2.9.0最新 FastAPI 强制 Pydantic v2并对 v1 模型显式抛出PydanticV1NotSupportedError。自动化优先普通模型优先尝试官方bump-pydantic一条命令完成大部分改写。渐进迁移复杂场景则利用pydantic.v1子模块把“升库”与“改码”解耦再按模型分组从 v1 迁往 v2期间可利用fastapi.temp_pydantic_v1_params维持 v1 模型的参数声明能力。硬性约束v1/v2 模型不可相互嵌套但可在同一应用、甚至同一条路径操作中各自独立使用Python 3.14 及以上不再支持 v1含pydantic.v1想跟进新 Python 版本就必须迁移到 v2。仓库中的 docs_src/pydantic_v1_in_v2/ 四个教程示例tutorial001~tutorial004即 tutorial001_an_py310.py、tutorial002_an_py310.py、tutorial003_an_py310.py、tutorial004_an_py310.py保留着这套渐进迁移路线的完整代码示范可与本文对照学习。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考