title: FastAPI与Tortoise-ORM开发的神奇之旅

date: 2025/05/05 00:15:48

updated: 2025/05/05 00:15:48

excerpt:

FastAPI与Tortoise-ORM结合实现全链路开发，涵盖环境配置、数据模型定义、Pydantic模式设计及API端点实现。文章模型包含软删除功能，通过is_deleted字段实现逻辑删除。API支持创建、分页查询、条件更新和软删除操作，确保数据安全与完整性。分页机制通过offset和limit实现，条件更新使用exclude_unset=True避免未传字段被覆盖。软删除通过filter().update()实现原子操作。系统具备用户认证、输入验证、防注入和细粒度权限控制等安全特性。

categories:

后端开发
FastAPI

tags:

FastAPI
TortoiseORM
全链路开发
数据模型
API端点
分页机制
软删除

扫描二维码

关注或者微信搜一搜：编程智域前端至全栈交流与成长

探索数千个预构建的 AI 应用，开启你的下一个伟大创意：https://tools.cmdragon.cn/

从API到数据库：FastAPI + Tortoise-ORM全链路开发指南

1. 环境准备与包安装

首先创建Python虚拟环境并安装必要依赖：

bash 复制代码

python -m venv venv
source venc/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

pip install fastapi uvicorn tortoise-orm pydantic python-multipart

2. 数据模型定义

创建包含软删除功能的文章模型：

python 复制代码

# models.py
from tortoise.models import Model
from tortoise import fields


class Article(Model):
    id = fields.IntField(pk=True)
    title = fields.CharField(max_length=255)
    content = fields.TextField()
    author_id = fields.IntField()
    created_at = fields.DatetimeField(auto_now_add=True)
    updated_at = fields.DatetimeField(auto_now=True)
    is_deleted = fields.BooleanField(default=False)

    class Meta:
        table = "articles"

    class PydanticMeta:
        exclude = ["is_deleted"]

3. Pydantic模式定义

定义请求响应数据结构：

python 复制代码

# schemas.py
from pydantic import BaseModel
from datetime import datetime


class ArticleCreate(BaseModel):
    title: str
    content: str


class ArticleUpdate(BaseModel):
    title: str | None = None
    content: str | None = None


class ArticleResponse(BaseModel):
    id: int
    title: str
    content: str
    author_id: int
    created_at: datetime
    updated_at: datetime

    class Config:
        orm_mode = True

4. FastAPI应用配置

配置数据库连接和路由：

python 复制代码

# main.py
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from tortoise.contrib.fastapi import register_tortoise

app = FastAPI()

# 数据库配置
DATABASE_URL = "sqlite://./db.sqlite3"

register_tortoise(
    app,
    db_url=DATABASE_URL,
    modules={"models": ["models"]},
    generate_schemas=True,
    add_exception_handlers=True,
)

# 模拟用户认证
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


async def get_current_user(token: str = Depends(oauth2_scheme)):
    return {"id": 1}  # 模拟返回用户信息

5. 完整API端点实现

5.1 创建文章

python 复制代码

@app.post("/articles", response_model=ArticleResponse)
async def create_article(
        article: ArticleCreate,
        user: dict = Depends(get_current_user)
):
    db_article = await Article.create(
        **article.dict(),
        author_id=user["id"]
    )
    return await ArticleResponse.from_tortoise_orm(db_article)

5.2 分页查询

python 复制代码

@app.get("/articles", response_model=list[ArticleResponse])
async def list_articles(
        page: int = 1,
        per_page: int = 10
):
    skip = (page - 1) * per_page
    query = Article.all().offset(skip).limit(per_page)
    return await ArticleResponse.from_queryset(query)

5.3 条件更新

python 复制代码

@app.patch("/articles/{article_id}", response_model=ArticleResponse)
async def update_article(
        article_id: int,
        update_data: ArticleUpdate,
        user: dict = Depends(get_current_user)
):
    # 只允许作者修改自己的文章
    db_article = await Article.get_or_none(id=article_id, author_id=user["id"])
    if not db_article:
        raise HTTPException(status_code=404, detail="Article not found")

    await db_article.update_from_dict(update_data.dict(exclude_unset=True))
    await db_article.save()
    return await ArticleResponse.from_tortoise_orm(db_article)

5.4 软删除

python 复制代码

@app.delete("/articles/{article_id}")
async def delete_article(
        article_id: int,
        user: dict = Depends(get_current_user)
):
    updated_count = await Article.filter(
        id=article_id,
        author_id=user["id"]
    ).update(is_deleted=True)

    if not updated_count:
        raise HTTPException(status_code=404, detail="Article not found")
    return {"message": "Article deleted"}

6. 关键实现解析

6.1 分页机制原理

计算skip值：skip = (page - 1) * per_page
数据库查询使用offset和limit实现分页
实际生产环境建议使用游标分页（Cursor Pagination）

6.2 条件更新安全

通过get_or_none确保记录存在
使用filter().update()实现原子操作
exclude_unset=True忽略未传字段

6.3 软删除实现

添加is_deleted字段
重写默认查询过滤器：

python 复制代码

class SoftDeleteManager(fields.Model):
    def get_queryset(self):
        return super().get_queryset().filter(is_deleted=False)

7. 课后Quiz

Q1：如何防止SQL注入攻击？

A：使用ORM的参数化查询，避免拼接SQL语句。Tortoise-ORM会自动处理查询参数，例如：

python 复制代码

await Article.filter(title="Safe' OR 1=1--")

实际生成的SQL会是参数化查询，特殊字符会被正确转义

Q2：为什么在更新时使用exclude_unset=True？

A：该参数会忽略未提供的字段，实现部分更新。例如用户只修改标题时，不会影响content字段

Q3：如何实现真正的物理删除？

A：直接使用delete()方法：

python 复制代码

await Article.filter(id=1).delete()

8. 常见报错解决方案

错误1：422 Validation Error

原因：请求体不符合Pydantic模型要求
解决：检查请求头Content-Type是否正确（应为application/json），确认字段类型和必填项

错误2：404 Not Found

原因：尝试操作不存在的记录
解决：在更新/删除前先使用get_or_none检查记录是否存在

错误3：RuntimeError - Event loop closed

原因：在同步代码中调用异步方法
解决：确保所有数据库操作都在async函数中执行，使用await调用

启动服务命令：

bash 复制代码

uvicorn main:app --reload

访问 http://localhost:8000/docs 即可测试API接口。本文实现的系统具备以下安全特性：

用户认证隔离数据访问
所有输入参数自动验证
数据库操作防注入
细粒度的权限控制

余下文章内容请点击跳转至个人博客页面或者扫码关注或者微信搜一搜：编程智域前端至全栈交流与成长，阅读完整的文章：FastAPI与Tortoise-ORM开发的神奇之旅 | cmdragon's Blog

FastAPI与Tortoise-ORM开发的神奇之旅

从API到数据库：FastAPI + Tortoise-ORM全链路开发指南

1. 环境准备与包安装

2. 数据模型定义

3. Pydantic模式定义

4. FastAPI应用配置

5. 完整API端点实现

5.1 创建文章

5.2 分页查询

5.3 条件更新

5.4 软删除

6. 关键实现解析

6.1 分页机制原理

6.2 条件更新安全

6.3 软删除实现

7. 课后Quiz

8. 常见报错解决方案

往期文章归档：