FastAPI + Tortoise-ORM：异步数据库操作优秀实践
在构建现代 Web 应用时，我们越来越追求 高性能 + 易维护 + 强扩展性。FastAPI 与 Tortoise-ORM 这对组合，正是实现 异步数据库操作 的黄金搭档。
本文将带你一步步搞定：
Tortoise-ORM 快速配置与初始化异步模型定义与操作项目结构推荐实用技巧与注意事项
Tortoise-ORM 是一个 类 Django 风格的异步 ORM，优雅 + 轻量 + 高性能。
优点包括：
原生支持 async / await，异步性能更佳 语法清晰，易于上手支持多数据库（PostgreSQL、MySQL、SQLite）自带迁移工具、强类型提示、关系管理安装依赖复制
pip install fastapi[all] tortoise-orm1.
如果你使用 Alembic 等迁移工具，可以跳过，Tortoise 自带 aerich：
复制
pip install aerich1.
复制
app/
├── main.py # 项目入口
├── models/ # 数据模型
│ └── user.py
├── schemas/ # Pydantic 模型
│ └── user.py
├── api/ # 路由逻辑
│ └── user.py
├── core/
│ └── config.py # 配置项
│ └── db.py # 数据库初始化1.2.3.4.5.6.7.8.9.10.11.
复制
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"1.2.3.4.5.6.7.8.9.10.
复制
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
)1.2.3.4.5.6.7.8.9.10.11.
说明：
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)1.2.3.4.5.6.7.8.9.
复制
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 user1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.
复制
from pydantic import BaseModel, EmailStr
class UserIn(BaseModel):
name: str
email: EmailStr
class UserOut(UserIn):
id: int1.2.3.4.5.6.7.8.
初始化：
复制
aerich init -t app.core.db.TORTOISE_ORM1.
生成迁移：
复制
aerich init-db
aerich migrate
aerich upgrade1.2.3.
推荐做法：
所有 ORM 操作都使用 await异步接口必须加 async def初始化模块路径必须写对，否则不会加载模型不建议手动写 SQL，除非非常必要常见坑：
没注册模型路径，表不会生成！await 忘写，会返回协程对象生产环境请关闭 generate_schemas=True，使用迁移工具更稳总结FastAPI + Tortoise-ORM 能让你拥有：
异步数据库高性能简洁优雅的模型定义良好的开发体验与类型安全如果你追求异步、类型提示、快速开发，这是非常值得一试的组合！
阅读剩余
THE END
