Python Web 应用：FastAPI 与 Tortoise ORM 异步数据库操作实现

Python Web 应用：FastAPI 与 Tortoise ORM 异步数据库操作实现

在现代 Web 开发中，异步操作是提升应用性能的关键，尤其在数据库交互频繁的场景下。FastAPI 作为高性能的异步 Web 框架，与 Tortoise ORM 的异步数据库操作能力完美契合，能显著提升应用的并发处理能力。本文将详细讲解如何使用 FastAPI 结合 Tortoise ORM 实现异步数据库操作，涵盖环境搭建、数据模型定义、CRUD 接口开发及异步事务处理等核心内容，附实用代码示例，帮助开发者快速构建高效的异步 Web 应用，解决传统同步操作中的性能瓶颈问题。

一、技术选型与环境搭建

FastAPI 以其自动生成 API 文档、类型提示支持和高性能著称，而 Tortoise ORM 作为异步 ORM 框架，支持多种数据库且语法简洁，两者结合是异步 Web 开发的理想选择。

核心技术栈

• Web 框架：FastAPI 0.100+（支持异步路由，性能接近 Node.js 和 Go）。

• ORM 工具：Tortoise ORM 0.20+（全异步 ORM，支持 PostgreSQL、MySQL、SQLite 等）。

• 数据库：PostgreSQL（推荐用于生产环境，支持高级异步特性）；开发阶段可使用 SQLite。

• 其他工具：Uvicorn（ASGI 服务器，运行 FastAPI 应用）、Pydantic（数据验证）。

环境配置步骤

# 创建虚拟环境

python -m venv venv

source venv/bin/activate # Linux/Mac

venv\Scripts\activate # Windows

# 安装依赖

pip install fastapi==0.103.1

pip install uvicorn==0.23.2

pip install tortoise-orm==0.20.0

pip install psycopg2-binary # PostgreSQL驱动（如需使用）

pip install python-multipart # 支持文件上传（可选）

二、Tortoise ORM 数据模型定义

Tortoise ORM 采用类继承方式定义数据模型，支持字段类型指定、索引设置和关系映射，完全兼容异步操作。

数据库连接配置

首先需配置数据库连接，在应用启动时初始化 Tortoise ORM：

# main.py

from fastapi import FastAPI

from tortoise.contrib.fastapi import register_tortoise

app = FastAPI(title="异步Web应用示例")

# 配置数据库连接

DATABASE_CONFIG = {

"connections": {

# 开发环境使用SQLite，生产环境可替换为PostgreSQL

"default": "sqlite://db.sqlite3"

# PostgreSQL配置示例：

# "default": "postgres://user:password@localhost:5432/dbname"

},

"apps": {

"models": {

"models": ["models", "aerich.models"], # 数据模型所在模块

"default_connection": "default",

}

},

"use_tz": False,

"timezone": "UTC"

}

# 注册Tortoise ORM到FastAPI

register_tortoise(

app,

config=DATABASE_CONFIG,

generate_schemas=True, # 自动创建数据库表（开发环境用）

add_exception_handlers=True, # 添加异常处理器

)

数据模型定义

使用 Tortoise ORM 定义数据模型，以博客文章为例：

# models.py

from tortoise import Model, fields

from datetime import datetime

class Article(Model):

"""文章模型"""

id = fields.IntField(pk=True) # 主键

title = fields.CharField(max_length=200, index=True) # 标题，添加索引

content = fields.TextField() # 内容

author = fields.CharField(max_length=100) # 作者

created_at = fields.DatetimeField(default=datetime.utcnow) # 创建时间

updated_at = fields.DatetimeField(auto_now=True) # 更新时间

class Meta:

table = "articles" # 数据库表名

ordering = ["-created_at"] # 默认排序（按创建时间降序）

def __str__(self):

return self.title

数据库迁移工具

使用 Aerich（Tortoise ORM 的迁移工具）管理数据库 schema 变更：

# 初始化迁移环境

aerich init -t main.DATABASE_CONFIG

# 初始化数据库

aerich init-db

# 生成迁移文件

aerich migrate --name add_article_table

# 应用迁移

aerich upgrade

三、FastAPI 异步接口开发

FastAPI 的异步路由与 Tortoise ORM 的异步方法结合，可实现高效的数据库操作，避免因 IO 等待阻塞请求处理。

数据验证模型

使用 Pydantic 定义请求和响应模型，确保数据合法性：

# schemas.py

from pydantic import BaseModel, Field

from datetime import datetime

from typing import Optional

class ArticleCreate(BaseModel):

"""创建文章的请求模型"""

title: str = Field(..., max_length=200, description="文章标题")

content: str = Field(..., description="文章内容")

author: str = Field(..., max_length=100, description="作者")

class ArticleUpdate(BaseModel):

"""更新文章的请求模型"""

title: Optional[str] = Field(None, max_length=200)

content: Optional[str] = None

class ArticleResponse(ArticleCreate):

"""文章响应模型"""

id: int

created_at: datetime

updated_at: datetime

class Config:

orm_mode = True # 支持从ORM模型实例创建响应

异步 CRUD 接口实现

# main.py（续）

from fastapi import status, HTTPException

from typing import List

from models import Article

from schemas import ArticleCreate, ArticleResponse, ArticleUpdate

@app.post("/articles", response_model=ArticleResponse, status_code=status.HTTP_201_CREATED)

async def create_article(article: ArticleCreate):

"""创建新文章（异步）"""

# 调用Tortoise ORM的create方法（异步）

db_article = await Article.create(**article.dict())

return db_article

@app.get("/articles", response_model=List[ArticleResponse])

async def get_articles(skip: int = 0, limit: int = 10):

"""获取文章列表（异步分页）"""

# 异步查询，支持链式调用

articles = await Article.all().offset(skip).limit(limit)

return articles

@app.get("/articles/{article_id}", response_model=ArticleResponse)

async def get_article(article_id: int):

"""获取单篇文章详情"""

article = await Article.get_or_none(id=article_id)

if not article:

raise HTTPException(

status_code=status.HTTP_404_NOT_FOUND,

detail=f"文章ID {article_id} 不存在"

)

return article

@app.put("/articles/{article_id}", response_model=ArticleResponse)

async def update_article(article_id: int, article_update: ArticleUpdate):

"""更新文章"""

article = await Article.get_or_none(id=article_id)

if not article:

raise HTTPException(

status_code=status.HTTP_404_NOT_FOUND,

detail=f"文章ID {article_id} 不存在"

)

# 异步更新

update_data = article_update.dict(exclude_unset=True)

await article.update_from_dict(update_data).save()

return article

@app.delete("/articles/{article_id}", status_code=status.HTTP_204_NO_CONTENT)

async def delete_article(article_id: int):

"""删除文章"""

deleted = await Article.filter(id=article_id).delete()

if not deleted:

raise HTTPException(

status_code=status.HTTP_404_NOT_FOUND,

detail=f"文章ID {article_id} 不存在"

)

return None

四、异步事务与复杂查询

在涉及多步数据库操作的场景中，异步事务能确保数据一致性，而 Tortoise ORM 的查询表达式支持复杂条件查询。

异步事务处理

# main.py（续）

from fastapi import Depends

from tortoise.transactions import in_transaction

async def create_article_with_comments(article_data: ArticleCreate, comments: list):

"""在事务中创建文章及关联评论（示例）"""

async with in_transaction():

# 第一步：创建文章

article = await Article.create(** article_data.dict())

# 第二步：创建关联评论（假设存在Comment模型）

# for comment in comments:

# await Comment.create(article_id=article.id, content=comment)

return article

@app.post("/articles/with-comments", response_model=ArticleResponse)

async def add_article_with_comments(

article: ArticleCreate,

comments: list[str] = Depends()

):

return await create_article_with_comments(article, comments)

复杂查询示例

# main.py（续）

@app.get("/articles/search")

async def search_articles(keyword: str, author: Optional[str] = None):

"""带条件的复杂查询"""

query = Article.filter(title__icontains=keyword) # 标题包含关键词（不区分大小写）

if author:

query = query.filter(author=author) # 筛选特定作者

# 分页并获取总数

articles = await query.offset(0).limit(20)

total = await query.count()

return {"total": total, "articles": articles}

五、性能优化与最佳实践

合理使用异步操作和数据库优化技巧，能进一步提升应用性能，避免常见的性能陷阱。

性能优化策略

• 批量操作：使用bulk_create和bulk_update减少数据库交互次数：

# 批量创建文章

articles = [

Article(title=f"标题{i}", content=f"内容{i}", author="批量作者")

for i in range(10)

]

await Article.bulk_create(articles)

• 索引优化：为频繁查询的字段添加索引（如示例中title字段的index=True），加速查询。

• 避免 N+1 查询问题：使用prefetch_related和select_related预加载关联数据：

# 预加载关联的评论（假设有关联关系）

articles = await Article.all().prefetch_related("comments")

最佳实践

• 异常处理：使用try-except捕获数据库操作异常，返回友好的错误信息。

• 依赖注入：将数据库操作逻辑封装到服务层，通过依赖注入在路由中使用，提高代码复用性。

• 连接池配置：在生产环境中合理配置数据库连接池大小，避免连接耗尽：

# 在数据库配置中添加

"connections": {

"default": {

"engine": "tortoise.backends.asyncpg",

"credentials": {

"host": "localhost",

"port": 5432,

"user": "user",

"password": "pass",

"database": "db",

"minsize": 5, # 最小连接数

"maxsize": 20 # 最大连接数

}

}

}

结语

FastAPI 与 Tortoise ORM 的组合为 Python 异步 Web 开发提供了强大支持，通过本文介绍的方法，开发者可快速构建高性能的异步 Web 应用。核心在于充分利用两者的异步特性，减少 IO 阻塞，同时遵循数据库优化最佳实践。

实际开发中，需根据业务场景合理设计数据模型和 API 接口，重视错误处理和数据验证，确保应用的稳定性和安全性。随着异步生态的不断完善，这种技术组合将在高并发 Web 应用开发中发挥越来越重要的作用。