Tortoise-ORM与Pydantic集成教程：模型转换与序列化实践

Tortoise-ORM与Pydantic集成教程：模型转换与序列化实践

tortoise-orm tortoise/tortoise-orm: 是一个基于 Python 的对象关系映射 (ORM) 库，它支持 SQLite、 MySQL、 PostgreSQL 等多种数据库。适合用于 Python 应用程序的数据库操作和 ORM，特别是对于需要轻量级、高性能的 ORM 库的场景。特点是轻量级、高性能、支持多种数据库、易于使用。 项目地址: https://gitcode.com/gh_mirrors/to/tortoise-orm

前言

在现代Python开发中，ORM框架和模型验证库是两个非常重要的组件。Tortoise-ORM作为一款优秀的异步ORM框架，与Pydantic这一强大的数据验证和设置管理库有着天然的契合点。本教程将详细介绍如何使用Tortoise-ORM与Pydantic进行集成，实现模型转换和数据序列化。

核心概念

Tortoise-ORM模型

Tortoise-ORM模型是数据库表的Python类表示，定义了表结构和字段类型。如示例中的Tournament类：

class Tournament(Model):
    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=100)
    created_at = fields.DatetimeField(auto_now_add=True)

Pydantic模型

Pydantic模型主要用于数据验证和序列化，它能够确保输入数据的有效性，并提供方便的序列化方法。

模型转换

创建Pydantic模型

Tortoise-ORM提供了pydantic_model_creator工具函数，可以轻松地将Tortoise模型转换为Pydantic模型：

Tournament_Pydantic = pydantic_model_creator(Tournament)

这一行代码就完成了从数据库模型到验证模型的转换，保留了所有字段定义和类型信息。

文档字符串处理

转换过程中会保留模型的文档字符串和字段注释：

• 类文档字符串会转换为Pydantic模型的描述
• 字段注释（以#:开头的注释）会转换为对应字段的描述

模式验证

生成Pydantic模型后，可以查看其JSON Schema：

print(Tournament_Pydantic.schema_json(indent=4))

输出结果会展示模型的完整结构，包括字段类型、是否必需、描述等信息。这在API文档生成和前端对接时非常有用。

数据序列化

数据库操作与序列化

示例中展示了完整的流程：

1. 初始化数据库连接
2. 创建数据库记录
3. 将ORM对象转换为Pydantic对象
4. 序列化为不同格式

# 创建对象
tournament = await Tournament.create(name="New Tournament")
# 转换为Pydantic对象
tourpy = await Tournament_Pydantic.from_tortoise_orm(tournament)

序列化选项

Pydantic提供了两种常用的序列化方法：

1. model_dump() - 转换为Python字典

print(tourpy.model_dump())

输出包含Python原生对象，如datetime对象。

2. model_dump_json() - 转换为JSON字符串

print(tourpy.model_dump_json(indent=4))

输出为JSON格式，所有非JSON原生类型（如datetime）会自动转换为字符串表示。

实际应用场景

这种集成方式特别适合以下场景：

• 构建Web API时，快速将数据库模型转换为响应模型
• 数据验证和输入过滤
• 生成API文档
• 在不同系统间传递数据时确保数据一致性

总结

通过本教程，我们学习了：

1. 如何使用pydantic_model_creator将Tortoise-ORM模型转换为Pydantic模型
2. 模型文档和注释的处理方式
3. 如何查看生成的JSON Schema
4. 两种常用的序列化方法及其区别

这种集成方式大大简化了从数据库到API的数据流转过程，同时保证了数据的完整性和一致性，是构建健壮后端服务的利器。

tortoise-orm tortoise/tortoise-orm: 是一个基于 Python 的对象关系映射 (ORM) 库，它支持 SQLite、 MySQL、 PostgreSQL 等多种数据库。适合用于 Python 应用程序的数据库操作和 ORM，特别是对于需要轻量级、高性能的 ORM 库的场景。特点是轻量级、高性能、支持多种数据库、易于使用。 项目地址: https://gitcode.com/gh_mirrors/to/tortoise-orm