FastAPI + Tortoise-ORM：异步数据库操作优秀实践
在构建现代 Web 应用时，我们越来越追求 高性能 + 易维护 + 强扩展性。FastAPI 与 Tortoise-ORM 这对组合，正是实现 异步数据库操作 的黄金搭档。
本文将带你一步步搞定：
- Tortoise-ORM 快速配置与初始化
- 异步模型定义与操作
- 项目结构推荐
- 实用技巧与注意事项
为什么选 Tortoise-ORM？
Tortoise-ORM 是一个 类 Django 风格的异步 ORM，优雅 + 轻量 + 高性能。
优点包括：
- 原生支持 async / await，异步性能更佳
- 语法清晰，易于上手
- 支持多数据库（PostgreSQL、MySQL、SQLite）
- 自带迁移工具、强类型提示、关系管理
安装依赖
pip install fastapi[all] tortoise-orm如果你使用 Alembic 等迁移工具，可以跳过，Tortoise 自带 aerich：
pip install aerich目录结构推荐
app/
├── main.py # 项目入口
├── models/ # 数据模型
│ └── user.py
├── schemas/ # Pydantic 模型
│ └── user.py
├── api/ # 路由逻辑
│ └── user.py
├── core/
│ └── config.py # 配置项
│ └── db.py # 数据库初始化定义模型（models/user.py）
from tortoise import fields
from tortoise.models import Model
class User(Model):
id = fields.IntField(pk=True)
name = fields.CharField(max_length=50)
email = fields.CharField(max_length=100, unique=True)
class Meta:
table = "user"配置数据库连接（core/db.py）
from tortoise.contrib.fastapi import register_tortoise
from fastapi import FastAPI
def init_db(app: FastAPI):
register_tortoise(
app,
db_url="sqlite://db.sqlite3", # 可替换为 mysql/postgres
modules={"models": ["app.models.user"]}, # 关键点
generate_schemas=True, # 启动时自动创建表
add_exception_handlers=True
)说明：
- modules={"models": ["app.models.user"]} 指定模型路径（可传多个）
- 会自动导入并注册这些模型
初始化数据库（main.py）
from fastapi import FastAPI
from app.core.db import init_db
from app.api import user
app = FastAPI()
init_db(app) # 初始化 ORM
app.include_router(user.router)编写接口（api/user.py）
from fastapi import APIRouter, HTTPException
from app.models.user import User
from app.schemas.user import UserIn, UserOut
router = APIRouter()
@router.post("/users", response_model=UserOut)
asyncdefcreate_user(user: UserIn):
existing = await User.get_or_none(email=user.email)
if existing:
raise HTTPException(status_code=400, detail="邮箱已存在")
user_obj = await User.create(**user.dict())
return user_obj
@router.get("/users/{user_id}", response_model=UserOut)
asyncdefget_user(user_id: int):
user = await User.get_or_none(id=user_id)
ifnot user:
raise HTTPException(status_code=404, detail="用户不存在")
return userPydantic 模型（schemas/user.py）
from pydantic import BaseModel, EmailStr
class UserIn(BaseModel):
name: str
email: EmailStr
class UserOut(UserIn):
id: int使用 Aerich 管理迁移（可选）
初始化：
aerich init -t app.core.db.TORTOISE_ORM生成迁移：
aerich init-db
aerich migrate
aerich upgrade使用建议 & 常见问题
推荐做法：
- 所有 ORM 操作都使用 await
- 异步接口必须加 async def
- 初始化模块路径必须写对，否则不会加载模型
- 不建议手动写 SQL，除非非常必要
常见坑：
- 没注册模型路径，表不会生成！
- await 忘写，会返回协程对象
- 生产环境请关闭 generate_schemas=True，使用迁移工具更稳
总结
FastAPI + Tortoise-ORM 能让你拥有：
- 异步数据库高性能
- 简洁优雅的模型定义
- 良好的开发体验与类型安全
如果你追求异步、类型提示、快速开发，这是非常值得一试的组合！
