FastAPI 的 ORM 生态

0

一、 FastAPI 的 ORM 生态

ORM介绍

ORM（Object-Relational Mapping，对象关系映射）是一种编程技术，用于在面向对象编程语言和关系型数据库之间建立映射。它允许开发者通过操作对象的方式来与数据库进行交互，而无需直接编写复杂的 SQL 语句。主要特点包括：

1. 对象与数据库表的映射：ORM 将数据库中的表映射为编程语言中的类，每一行数据对应一个对象，表的列对应对象的属性
2. 简化数据库操作：开发者可以使用面向对象的方法（如创建、查询、更新、删除对象）来操作数据库，而无需手动编写 SQL
3. 跨数据库兼容：ORM 通常支持多种数据库（如 MySQL、PostgreSQL、SQLite），通过统一的接口减少数据库切换的成本
4. 提高开发效率：通过自动化 SQL 生成和查询优化，减少重复代码，提升开发速度

工作原理

• ORM 框架定义了一个映射层，将类和数据库表关联起来
• 开发者通过 ORM 的 API 操作对象，ORM 自动将操作翻译成 SQL 语句，执行数据库操作并返回结果

优点

• 提高代码可读性和维护性
• 减少直接 SQL 操作带来的错误。
• 支持复杂查询和关系（如一对多、多对多）

缺点

• 性能可能略低于原生 SQL（因抽象层开销）
• 对于非常复杂的查询，可能需要直接编写 SQL

ORM工具介绍

• SQLAlchemy（同步/异步）：≈80% 企业项目首选，功能完备、社区成熟，支持复杂查询和事务管理。
• Tortoise（异步）：语法类似 Django ORM，适合异步优先项目，集成简便
• GINO（异步）：轻量级，基于 SQLAlchemy Core 的异步扩展，适合高性能 API

选型建议

• 传统企业项目 →SQLAlchemy（成熟稳定）
• 全异步微服务 →Tortoise-ORM或GINO

提示

FastAPI无官方 ORM

二、Tortoise-ORM配置

为什么选择 Tortoise-ORM

• 异步支持，与 FastAPI 无缝集成
• 简单易用的模型定义，类似 Django ORM
• 支持复杂关系（一对一、一对多、多对多）
• 自动生成表结构，适合快速开发

环境配置

安装必要的依赖：

pipinstalltortoise-orm==0.25.0aerich==0.9.0aiomysql==0.2.0tomlkit==0.13.2

配置数据库连接

Tortoise-ORM 需要一个配置字典来定义数据库连接信息，通常存储在 settings.py 或类似的配置文件中。

fromtypingimportDict# Tortoise-ORM 配置TORTOISE_ORM:Dict={"connections":{# 开发环境使用 SQLite（基于文件，无需服务器）"default":"sqlite://db.sqlite3",# 生产环境示例：PostgreSQL# "default": "postgres://user:password@localhost:5432/dbname",# 生产环境示例：MySQL# "default": "mysql://user:password@localhost:3306/dbname",},"apps":{"models":{"models":["app.models","aerich.models"],# 模型模块和 Aerich 迁移模型"default_connection":"default",}},# 连接池配置（推荐）"use_tz":False,# 是否使用时区"timezone":"UTC",# 默认时区"db_pool":{"max_size":10,# 最大连接数"min_size":1,# 最小连接数"idle_timeout":30# 空闲连接超时（秒）}}

配置说明

• connections：定义数据库连接字符串
  • SQLite：sqlite://db.sqlite3（开发环境，文件存储在项目根目录）
  • PostgreSQL：postgres://user:password@host:port/dbname（生产环境）
  • MySQL：mysql://user:password@host:port/dbname（生产环境）
• apps：定义应用模块，models 列表包含模型文件路径和 Aerich 的迁移模型
• db_pool：连接池参数，优化数据库连接管理，适合高并发场景
• use_tz和timezone：控制时间字段的时区行为（生产环境建议启用）

初始化 FastAPI 应用

fromfastapiimportFastAPIfromtortoise.contrib.fastapiimportregister_tortoisefromapp.core.configimportTORTOISE_ORM app=FastAPI(title="FastAPI with Tortoise-ORM")# 注册 Tortoise-ORMregister_tortoise(app,config=TORTOISE_ORM,generate_schemas=True,# 开发环境自动生成表结构add_exception_handlers=True,# 添加默认异常处理器)@app.get("/")asyncdefroot():return{"message":"Welcome to FastAPI with Tortoise-ORM!"}

三、Aerich 迁移工具的使用

Aerich 是 Tortoise-ORM 的数据库迁移工具，用于管理数据库结构的变更

Aerich 初始化

在项目根目录运行以下命令：

aerich init-tmain.TORTOISE_ORM

这将生成：

• pyproject.toml：Aerich 配置文件，指定迁移配置。
• migrations/：迁移文件目录，存放生成的 .sql 文件。

aerich init-db

生成和应用迁移

1. 生成迁移文件： 当模型发生变更时，运行以下命令生成迁移文件：

   aerich migrate--name"info"

2. 应用迁移： 运行以下命令将迁移应用到数据库：

   aerich upgrade

3. 验证迁移： 检查迁移历史

   aerichhistory

4. 回滚迁移：回退到指定版本

   aerich downgrade

模型案例

fromtortoise.modelsimportModelfromtortoise.fieldsimportCharField,DatetimeField,BooleanFieldclassUser(Model):id=CharField(max_length=36,pk=True)# 主键，UUID 字符串username=CharField(max_length=50,unique=True)# 用户名，唯一email=CharField(max_length=255,unique=True)# 邮箱，唯一is_active=BooleanField(default=True)# 是否激活created_at=DatetimeField(auto_now_add=True)# 创建时间updated_at=DatetimeField(auto_now=True)# 更新时间classMeta:table="users"# 自定义表名ordering=["-created_at"]# 默认按创建时间降序排序def__str__(self):returnself.username

效果

fromtortoiseimportBaseDBAsyncClientasyncdefupgrade(db:BaseDBAsyncClient)->str:return""" CREATE TABLE IF NOT EXISTS `users` ( `id` VARCHAR(36) NOT NULL PRIMARY KEY, `username` VARCHAR(50) NOT NULL UNIQUE, `email` VARCHAR(255) NOT NULL UNIQUE, `is_active` BOOL NOT NULL DEFAULT 1, `created_at` DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6), `updated_at` DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6) ) CHARACTER SET utf8mb4; CREATE TABLE IF NOT EXISTS `aerich` ( `id` INT NOT NULL PRIMARY KEY AUTO_INCREMENT, `version` VARCHAR(255) NOT NULL, `app` VARCHAR(100) NOT NULL, `content` JSON NOT NULL ) CHARACTER SET utf8mb4;"""asyncdefdowngrade(db:BaseDBAsyncClient)->str:return""" """

四、Tortoise-ORM 的模型定义

模型定义基础

Tortoise-ORM 的模型通过继承 tortoise.models.Model 类定义，每个模型对应数据库中的一张表。

字段定义使用 Tortoise-ORM 提供的字段类型，结合字段参数来指定约束和行为。

基本模型示例

fromtortoise.modelsimportModelfromtortoiseimportfieldsclassUser(Model):id=fields.IntField(pk=True)# 主键字段，自动递增username=fields.CharField(max_length=50,unique=True)# 唯一用户名email=fields.CharField(max_length=100,index=True)# 带索引的邮箱created_at=fields.DatetimeField(auto_now_add=True)# 自动记录创建时间is_active=fields.BooleanField(default=True)# 账户激活状态credit=fields.DecimalField(max_digits=10,decimal_places=2,default=0.0)# 精确数值classMeta:table="auth_users"# 自定义表名ordering=["-created_at"]# 默认按创建时间倒序unique_together=['username','email']#定义联合唯一约束（如 unique_together=[("field1", "field2")]）

说明

• 继承Model：所有模型必须继承 tortoise.models.Model。
• 字段定义：每个字段对应数据库表中的一列，使用 Tortoise-ORM 的字段类（如 CharField、BooleanField）。
• Meta类：用于定义模型的元数据，如表名、排序规则等。

核心字段类型详解

Tortoise-ORM 提供了多种字段类型，用于定义数据库列的类型和行为。以下是常用的字段类型及其典型用途：

字段参数详解

字段支持多种参数，用于定义约束、默认值和其他行为。以下是常用参数：

• max_length：字符串字段的最大长度（CharField 必填）
• null：是否允许字段为空（null=True 表示数据库允许 NULL）
• default：字段默认值（如 default=0、default=True）
• unique：是否唯一（unique=True 确保字段值在表中唯一）
• index：是否创建索引（index=True 提高查询性能）
• description：字段描述（用于文档或数据库注释）
• pk：是否为主键（pk=True 表示该字段是主键）
• validators：自定义验证函数

fromtortoise.validatorsimportValidatordefvalidate_credit(value):ifvalue<0:raiseValueError("信用值不能为负数")classUser(Model):credit=fields.IntField(validators=[validate_credit])# 自定义验证函数

模型元数据（Meta 类）

Meta 类用于定义模型的元数据，控制表结构和查询行为。常用属性包括：

• table：自定义数据库表名（如 table=“users”）
• unique_together：定义联合唯一约束（如 unique_together=[(“field1”, “field2”)]）
• indexes：定义索引（如 indexes=[(“field1”, “field2”)]）
• ordering：默认排序规则（如 ordering=[“-created_at”, “username”]）

classEvent(Model):name=CharField(max_length=100)location=CharField(max_length=200)date=DateField()classMeta:table="events"unique_together=[("name","date")]# 名称和日期联合唯一indexes=[("location",)]# 为 location 字段创建索引ordering=["date"]# 按日期升序排序

📌持续更新中

✒️总结

如果这篇【文章】有帮助到你💖，希望可以给我点个赞👍，创作不易，如果有对前端端或者对python感兴趣的朋友,请多多关注💖💖💖，咱们一起探讨和努力！！！
👨‍🔧 个人主页 : 前端初见