Tortoise-ORM 与 Pydantic 2.11 版本兼容性问题解析

在 Python 生态系统中，Tortoise-ORM 作为一款异步 ORM 框架，与 Pydantic 的数据验证和序列化功能形成了完美搭配。然而近期 Pydantic 2.11 版本的发布却意外打破了这种和谐，导致 Tortoise-ORM 的 Pydantic 集成功能出现严重兼容性问题。

问题现象

当开发者尝试使用 Tortoise-ORM 的 pydantic_model_creator 功能时，会遇到一个明显的错误提示："model_config cannot be used as a model field name"。这个错误直接导致无法生成预期的 Pydantic 模型，使得原本正常工作的代码突然失效。

问题根源

深入分析后发现，Pydantic 2.11 版本对 create_model 方法进行了重大调整：

1. 严格字段名检查：Pydantic 现在明确禁止使用 model_config 作为模型字段名，这与 Tortoise-ORM 内部实现方式产生了冲突。

2. 计算字段处理变更：对于通过 @computed_field 装饰器定义的计算字段，新版本的动态模型创建机制采用了不同的处理方式，导致原有实现失效。

技术细节

Tortoise-ORM 通过 pydantic_model_creator 动态创建 Pydantic 模型时，其核心流程是：

1. 收集 ORM 模型的所有字段信息
2. 构建字段定义字典
3. 调用 Pydantic 的 create_model 方法生成最终模型类

在 Pydantic 2.11 之前，这个过程可以顺利处理包括 model_config 和计算字段在内的各种特殊情况。但新版本中：

• model_config 被保留用于模型配置，不能再作为普通字段传递
• 计算字段需要采用新的方式集成到动态创建的模型中

解决方案

社区经过讨论和测试，最终确定了以下解决方案：

1. 重构模型创建流程：不再通过 create_model 的参数字典传递 model_config，而是先创建一个包含配置的基础类。

2. 计算字段的特殊处理：将计算字段与普通字段分离，分别采用不同的集成方式。

关键实现代码展示了如何创建一个基础模型类，既包含配置信息又保留计算字段功能：

base_model = type(
    "BasePydanticModel",
    (PydanticModel,),
    {"model_config": self._pconfig, **computed_fields},
)
model = create_model(
    self._name,
    __base__=base_model,
    __module__=self._module,
    __validators__=self._validators,
    **common_fields,
)

版本兼容性建议

对于使用 Tortoise-ORM 的开发者，目前有以下建议：

1. 升级到 Tortoise-ORM 0.25.0+：该版本已包含完整的兼容性修复。

2. 临时解决方案：如果暂时无法升级，可以降级 Pydantic 到 2.10.6 版本，同时使用 pydantic-core 2.27.2。

技术启示

这一事件给我们几个重要启示：

1. 依赖管理的脆弱性：即使是次要版本升级，也可能带来破坏性变更，强调完善的依赖版本锁定机制的重要性。

2. 动态创建的复杂性：动态模型创建涉及 Python 元编程的深层次机制，需要特别关注与依赖库的交互方式。

3. 社区协作的价值：通过开源社区的快速响应和协作，复杂的技术问题能够在短时间内得到解决。

这一兼容性问题的解决，不仅恢复了 Tortoise-ORM 与 Pydantic 的协同工作能力，也为处理类似框架间集成问题提供了有价值的参考案例。