FastAPI与Tortoise-ORM集成全攻略

2025年11月14日 互联网

FastAPI 集成 Tortoise-ORM 实践

在当今的Python Web开发领域，FastAPI凭借其高性能、易用性和异步支持，已成为构建API服务的热门选择。而Tortoise-ORM作为一个异步的ORM框架，与FastAPI的结合能够充分发挥异步编程的优势，简化数据库操作，提升开发效率。本文将深入探讨如何在FastAPI项目中集成Tortoise-ORM，从基础配置到高级用法，为开发者提供一份详尽的实践指南。

一、Tortoise-ORM简介

Tortoise-ORM是一个基于Python的异步ORM框架，专为异步Web框架如FastAPI、Sanic等设计。它支持多种数据库后端，包括PostgreSQL、MySQL、SQLite等，提供了类似Django ORM的API风格，但完全异步化，能够更好地与FastAPI的异步特性兼容。Tortoise-ORM的主要特点包括：

  • 异步支持：所有数据库操作都是异步的，适合高并发场景。
  • 类型提示：利用Python的类型提示系统，提供更好的代码可读性和IDE支持。
  • 模型定义简单：通过继承tortoise.models.Model类，可以轻松定义数据库模型。
  • 事务管理：支持事务操作，确保数据一致性。

二、FastAPI集成Tortoise-ORM的准备工作

1. 安装依赖

首先，需要安装FastAPI、Uvicorn（ASGI服务器）和Tortoise-ORM：

  1. pip install fastapi uvicorn tortoise-orm

2. 配置数据库连接

在FastAPI项目中，通常会在一个配置文件中管理数据库连接信息。例如，创建一个config.py文件：

  1. # config.py
  2. from pydantic import BaseSettings
  4. class Settings(BaseSettings):
  5.     DATABASE_URL: str = "sqlite://db.sqlite3"  # 默认使用SQLite，生产环境应替换为其他数据库
  7.     class Config:
  8.         env_file = ".env"  # 可选，用于从.env文件加载环境变量
  10. settings = Settings()

3. 初始化Tortoise-ORM

在FastAPI应用的启动文件中（如main.py），初始化Tortoise-ORM并配置数据库连接：

  1. # main.py
  2. from fastapi import FastAPI
  3. from tortoise.contrib.fastapi import register_tortoise
  4. from config import settings
  6. app = FastAPI()
  8. register_tortoise(
  9.     app,
  10.     db_url=settings.DATABASE_URL,
  11.     modules={"models": ["app.models"]},  # 指定模型所在的模块
  12.     generate_schemas=True,  # 自动生成数据库表结构
  13.     add_exception_handlers=True,  # 添加异常处理器
  14. )

三、定义模型

在app/models.py中定义数据库模型。例如，定义一个简单的User模型：

  1. # app/models.py
  2. from tortoise import fields, models
  4. class User(models.Model):
  5.     id = fields.IntField(pk=True)
  6.     name = fields.CharField(max_length=100)
  7.     email = fields.CharField(max_length=100, unique=True)
  9.     def __str__(self):
  10.         return self.name

四、CRUD操作

1. 创建记录

使用Tortoise-ORM创建记录非常简单：

  1. # app/crud.py
  2. from app.models import User
  4. async def create_user(name: str, email: str):
  5.     user = await User.create(name=name, email=email)
  6.     return user

2. 查询记录

Tortoise-ORM提供了多种查询方式：

  1. # app/crud.py
  2. async def get_user_by_id(user_id: int):
  3.     return await User.get(id=user_id)
  5. async def get_user_by_email(email: str):
  6.     return await User.get(email=email)
  8. async def get_all_users():
  9.     return await User.all()

3. 更新记录

更新记录同样简单：

  1. # app/crud.py
  2. async def update_user(user_id: int, name: str = None, email: str = None):
  3.     user = await User.get(id=user_id)
  4.     if name:
  5.         user.name = name
  6.     if email:
  7.         user.email = email
  8.     await user.save()
  9.     return user

4. 删除记录

删除记录只需调用delete()方法：

  1. # app/crud.py
  2. async def delete_user(user_id: int):
  3.     user = await User.get(id=user_id)
  4.     await user.delete()
  5.     return {"message": "User deleted successfully"}

五、事务管理

在需要保证数据一致性的场景下，可以使用事务：

  1. # app/crud.py
  2. from tortoise import transactions
  4. async def transfer_funds(from_user_id: int, to_user_id: int, amount: float):
  5.     async with transactions.in_transaction() as conn:
  6.         from_user = await User.get(id=from_user_id)
  7.         to_user = await User.get(id=to_user_id)
  9.         if from_user.balance < amount:
  10.             raise ValueError("Insufficient funds")
  12.         from_user.balance -= amount
  13.         to_user.balance += amount
  15.         await from_user.save(using_db=conn)
  16.         await to_user.save(using_db=conn)
  18.     return {"message": "Funds transferred successfully"}

六、高级用法

1. 自定义查询集

可以通过继承tortoise.queryset.QuerySet来自定义查询集：

  1. # app/models.py
  2. class UserQuerySet(models.QuerySet):
  3.     async def active(self):
  4.         return self.filter(is_active=True)
  6. class User(models.Model):
  7.     # ... 其他字段 ...
  8.     is_active = fields.BooleanField(default=True)
  10.     objects = UserQuerySet.as_manager()

2. 信号处理

Tortoise-ORM支持信号处理，可以在模型事件发生时执行自定义逻辑：

  1. # app/models.py
  2. from tortoise.signals import pre_save, post_save
  3. from tortoise.contrib.pydantic import pydantic_model_creator
  5. @pre_save(User)
  6. async def pre_save_user(sender, instance, using_db, **kwargs):
  7.     # 在保存前执行的操作
  8.     pass
  10. @post_save(User)
  11. async def post_save_user(sender, instance, created, using_db, **kwargs):
  12.     # 在保存后执行的操作
  13.     pass

七、总结与展望

FastAPI集成Tortoise-ORM能够显著提升Web应用的开发效率和性能。通过异步ORM，开发者可以更轻松地处理数据库操作，同时享受FastAPI带来的高性能和易用性。未来，随着异步编程的普及和ORM框架的不断发展，FastAPI与Tortoise-ORM的集成将成为更多开发者的首选。

本文从基础配置到高级用法，全面介绍了FastAPI集成Tortoise-ORM的实践方法。希望这份指南能够帮助开发者更好地利用这两个工具，构建出高效、稳定的Web应用。

最新文章
热门标签