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-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. 定义模型（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"1.2.3.4.5.6.7.8.9.10. 配置数据库连接（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 )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. 编写接口（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 user1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20. Pydantic 模型（schemas/user.py） 复制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 管理迁移（可选）

初始化：

复制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 能让你拥有：

异步数据库高性能简洁优雅的模型定义良好的开发体验与类型安全

如果你追求异步、类型提示、快速开发，这是非常值得一试的组合！