FastAPI 从 Pydantic v1 迁移到 Pydantic v2兼容窗口、pydantic.v1过渡方案与分步迁移实践【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本指南以 FastAPI 官方文档《Pydantic v1 から Pydantic v2 へのマイグレーション》为骨架系统讲解 FastAPI 从支持 Pydantic v1 到全面转向 Pydantic v2 的版本历程、依托pydantic.v1兼容子模块的渐进式迁移方案以及bump-pydantic一键自动化迁移等实战要点。读完你将掌握在旧版 FastAPI 中如何混用 v1/v2 模型平滑过渡、当前 FastAPI 版本对pydantic.v1的硬性限制源码级证据以及一套先测试、后工具、再手动的可靠升级路径。版本演进Pydantic v1 在 FastAPI 中是如何逐步退场的要理解迁移先要看清 FastAPI 与 Pydantic 版本关系的完整时间线。从仓库文档整理出的官方口径如下FastAPI 0.100.0同时支持 Pydantic v1 或 v2具体取决于运行环境实际安装的是哪一版本FastAPI 0.119.0为降低迁移成本开始在 Pydantic v2 内部部分兼容Pydantic v1通过pydantic.v1子模块引入FastAPI 0.126.0正式停止对原生安装的 Pydantic v1的支持但pydantic.v1子模块仍可继续使用一段时间FastAPI 0.128.0连pydantic.v1子模块支持也一并移除此后 FastAPI 的所有版本都强制要求 Pydantic v2。这一结论在当前仓库中可以得到直接验证本文所在仓库的 pyproject.toml 中运行依赖明确写为pydantic2.9.0第 46 行以及pydantic 2.9.0,3.0.0第 154 行也就是从依赖声明层面就排除了 Pydantic v1。[!WARNING] Pydantic 团队已宣布从Python 3.14起最新版 Python 上不再支持 Pydantic v1这同样覆盖pydantic.v1兼容子模块。因此若想使用 Python 3.14 及更新特性请务必确认代码库中没有任何 Pydantic v1含pydantic.v1调用点。迁移第一步先阅读官方指南并保证测试覆盖官方迁移指南Pydantic 官方维护了一份 v1 到 v2 的正式迁移指南其中系统说明了哪些行为发生了变化、为什么 v2 的校验更精确也更严格、以及升级时可能踩到的坑。在动手改代码前通读该指南能帮助你理解改动背后的原因而不是机械替换。先把测试跑起来在开始升级之前务必确认应用已有 测试 并且测试能在持续集成CI中稳定运行。文档原文特别强调这能确保你在一步步升级的过程中随时验证一切仍然按预期工作。[!TIP] 迁移的最小闭环是先改 Pydantic 版本 → 跑测试 → 看失败 → 修代码 → 再跑测试。没有测试护航的迁移等于盲改。自动化迁移试试bump-pydantic如果你的模型大多是没有深度定制的普通 Pydantic 模型那么大量迁移工作其实可以交给自动化工具完成。Pydantic 官方团队提供了bump-pydantic工具它能够自动改写绝大多数需要变更的代码。使用流程很简单在代码库上运行bump-pydantic让它批量改写 import、API 调用等差异点运行你的测试套件若全部通过迁移即告完成。文档对此的表述相当乐观跑完测试如果一切正常那就结束了 。当然前提是你的用法足够标准、没有触碰 v1/v2 行为差异巨大的边界特性详见后文校验行为差异的提示。pydantic.v1藏在 Pydantic v2 里的 v1 兼容子模块为什么会有pydantic.v1Pydantic v2 将 Pydantic v1 的全部内容以子模块pydantic.v1的形式内置。这意味着只要你安装了较新的 Pydantic v2就能从pydantic.v1中 import 旧的 v1 组件效果等同于仍然装着 Pydantic v1——前提是你的 Python 版本不高于 3.13。在代码层面二者可以这样切换from pydantic.v1 import BaseModel class Item(BaseModel): name: str description: str | None None size: float完整示例见 docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py这段代码把BaseModel的 import 从pydantic换成了pydantic.v1模型定义本身与 v1 时代完全一致。这是一个非常实用的时间机器升级 Pydantic 本身不再等于必须立刻重写所有模型v1 语义的代码可以继续跑在 v2 的进程里。FastAPI 对pydantic.v1的支持窗口0.119.0 ~ 0.128.0[!WARNING] FastAPI 对pydantic.v1模型的支持是FastAPI 0.119.0 加入、FastAPI 0.128.0 移除的本质上是为迁移到 Pydantic v2而设计的临时辅助能力。当前版本本仓库为 0.141.1的应用中若出现pydantic.v1模型会直接报错本节后续描述仅适用于那段旧版本窗口。在 0.119.0 起的过渡期你只需要两步把 Pydantic 升级到最新的 v2把所有from pydantic import ...改成from pydantic.v1 import ...。多数场景下 FastAPI 就能继续正常工作from 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完整示例见 docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py路由的请求体解析、返回类型注解全部基于pydantic.v1.ItemFastAPI 在过渡版本中可正常完成校验与序列化。[!WARNING] 请注意 Pydantic 官方对 Python 3.14 停止支持 Pydantic v1 的公告同样作用于pydantic.v1。也就是说即便你把 FastAPI 锁在 0.119.0~0.127.x一旦升到 Python 3.14这条路依然走不通。为什么当前版本已彻底拒绝pydantic.v1在当前仓库源码中拒绝 v1是显式实现的可以作为判断依据fastapi/exceptions.py 定义了专门异常类PydanticV1NotSupportedErrordocstring 写明A pydantic.v1 model is used, which is no longer supported.fastapi/utils.py 的create_model_field()在解析字段前调用annotation_is_pydantic_v1(type_)做前置检查命中即抛出上述异常并提示 Please update the response modelfastapi/encoders.py 的jsonable_encoder()在序列化时若检测到pydantic.v1模型实例同样直接抛PydanticV1NotSupportedError底层判定工具集中在 fastapi/_compat/shared.pyis_pydantic_v1_model_instance、is_pydantic_v1_model_class、annotation_is_pydantic_v1三个函数会递归检查Union、序列等泛型注解内部是否混入了pydantic.v1类型。从这套代码结构可以看出当前 FastAPI 在请求体解析、参数校验、响应编码全链路都设了 v1 检测关卡——这正是 0.128.0 之后硬切 v2的技术落实。同一应用内混用 v1 与 v2 模型的边界不支持的用法模型互相嵌套Pydantic 官方不支持在 v2 模型的字段里定义 v1 模型反之亦然这会造成字段级校验语义的混乱属于架构层面的禁区不要试图混用。支持的用法模型隔离共存Pydantic v1 与 v2 可以共存于同一个应用前提是两者保持独立、各自闭环在过渡期的 FastAPI 中甚至可以在同一个路径处理函数里同时使用 v1 与 v2一个模型负责入参校验另一个负责出参序列化。from 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完整示例见 docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py。此例中请求体item: Item是v1 模型负责接收与校验response_modelItemV2是v2 模型负责响应序列化输入输出各司其职。这种输入 v1、输出 v2或按业务模块切分的组合正是渐进迁移能够按组推进的基础。Pydantic v1 参数fastapi.temp_pydantic_v1_params过渡期内如果你的 v1 模型还需要配合Body、Query、Form等 FastAPI 专用参数工具使用应从临时兼容模块 import而不是从fastapi顶层 importfrom 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完整示例见 docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py其中用AnnotatedBody(embedTrue)把 v1 模型作为内嵌 body 参数传入。[!WARNING]fastapi.temp_pydantic_v1_params仅是临时桥接模块随 v1 支持的移除一并消失——不要在面向未来的新代码中依赖它。本文仓库版本中已搜索不到该模块印证了它属于已被清除的历史窗口产物。推荐路径按步骤、分组、渐进迁移[!WARNING] 下述同一应用中同时保留 v1 与 v2 模型的渐进迁移方案仅在 FastAPI 0.119.0 ~ 0.127.x 之间有效FastAPI 0.128.0 起被移除新版只接受纯 Pydantic v2 模型。若你已处于新版请直接采用全量改写路径不再有过渡期可用。[!TIP] 再次强调先跑bump-pydantic。如果测试通过、运行正常一条命令就结束了 ✨。只有工具不适合你的使用场景时才需要下面的手工渐进方案。渐进迁移操作步骤升级 Pydantic 到最新 v2。把全部from pydantic import ...改为from pydantic.v1 import ...让整个应用先跑在 v2 的 v1 兼容层上行为与迁移前保持一致逐个模型组迁移到原生 v2。按模块或按业务边界把模型从pydantic.v1.BaseModel改回pydantic.BaseModel并同步处理 v2 的 API 差异每组迁移后立即跑测试。利用 v1/v2 同窗共存的能力把一次爆炸式重写拆成多次小步提交每步都可回滚、可验证。手工迁移时的高频差异自查清单以下差异虽不来自本仓库文档正文但属于 v1→v2 迁移中最常见的拦路虎供你在逐组改写时对照检查建议结合官方迁移指南逐条核对校验更严格v2 会拒绝 v1 时代宽容接受的脏数据如错误类型强制转换原本侥幸通过的请求可能开始报 422validator→field_validator/model_validator装饰器名称与签名都变了且默认不再自动preTrueConfig类 →model_config ConfigDict(...)如orm_mode改名为from_attributes.dict()/.json()→.model_dump()/.model_json_schema()序列化 API 全面更名parse_obj→model_validate、from_orm→model_validate(..., from_attributesTrue)。遇到测试失败时优先对照以上清单检查多数 v1 风格代码都能机械改写成 v2 风格。小结从 FastAPI 的版本史可以看出 Pydantic 迁移的完整策略用pydantic.v1内置子模块争取迁移时间、用bump-pydantic处理机械改写、用 v1/v2 同窗机制支撑分步灰度最终在 0.128.0 完成对 v1 的彻底告别。对仍在使用旧版 FastAPI Pydantic v1 的项目建议按本文顺序操作先建好测试 → 跑bump-pydantic尝试一步到位 → 若不适用则升级 Pydantic 并在pydantic.v1兼容层上分模块渐进改写。而对于已经身处当前版本FastAPI 0.141.1、强制pydantic2.9.0的开发者唯一正确姿势就是让代码库 100% 采用 Pydantic v2 语法——源码中遍布的PydanticV1NotSupportedError检查点会替你守护这条底线。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考