FastAPI + Tortoise-ORM：異步數據庫操作優(yōu)秀實踐
作者：Ss肥魚
在構建現代 Web 應用時，我們越來越追求 高性能 + 易維護 + 強擴展性。FastAPI 與 Tortoise-ORM 這對組合，正是實現 異步數據庫操作 的黃金搭檔。
在構建現代 Web 應用時，我們越來越追求 高性能 + 易維護 + 強擴展性。FastAPI 與 Tortoise-ORM 這對組合，正是實現 異步數據庫操作 的黃金搭檔。
本文將帶你一步步搞定：
- Tortoise-ORM 快速配置與初始化
- 異步模型定義與操作
- 項目結構推薦
- 實用技巧與注意事項
為什么選 Tortoise-ORM？
Tortoise-ORM 是一個 類 Django 風格的異步 ORM，優(yōu)雅 + 輕量 + 高性能。
優(yōu)點包括：
- 原生支持 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, # 啟動時自動創(chuàng)建表
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 忘寫，會返回協程對象
- 生產環(huán)境請關閉 generate_schemas=True，使用遷移工具更穩(wěn)
總結
FastAPI + Tortoise-ORM 能讓你擁有：
- 異步數據庫高性能
- 簡潔優(yōu)雅的模型定義
- 良好的開發(fā)體驗與類型安全
如果你追求異步、類型提示、快速開發(fā)，這是非常值得一試的組合！
責任編輯：趙寧寧
來源：
Ssoul肥魚
