FastAPI 如何构建一个结构良好的项目

在本文中，我们将介绍如何构建一个结构良好的 FastAPI 项目的最佳实践。FastAPI 是一个快速（性能接近于 Node.js 和 Go）、易学、快速编码和更少代码的高性能 Web 框架。一个结构良好的项目能够更好地组织代码，提高开发效率和维护性，下面是一些构建 FastAPI 项目的最佳实践。

阅读更多：FastAPI 教程

项目结构

首先，让我们从项目结构开始。一个良好的项目结构可以使代码更具有可读性和可维护性。以下是一个常见的 FastAPI 项目结构示例：

project
├── app
│   ├── api
│   ├── core
│   ├── db
│   ├── models
│   ├── schemas
│   └── main.py
├── tests
├── .env
├── .gitignore
└── requirements.txt

• app 目录是整个 FastAPI 项目的主要目录，包含了用于处理请求的所有逻辑代码。我们可以根据功能模块将代码进行划分。
• api 目录用于存放所有的路由、请求和响应的逻辑代码。
• core 目录包含与应用程序核心逻辑相关的代码，比如引擎初始化、配置、日志和中间件。
• db 目录用于存放所有与数据库相关的代码，如连接数据库、创建模型和执行查询等。
• models 目录用于存放所有数据库模型的定义，这些模型将被用于数据库操作。
• schemas 目录定义了所有输入和输出的模型结构，用于请求和响应的验证。
• main.py 文件是 FastAPI 项目的入口文件。

路由设计

在 FastAPI 中，路由定义是相当重要的一部分。一个结构良好的路由设计可以使项目易于维护和扩展。以下是一些有关路由设计的最佳实践：

使用模块化的路由

将路由按模块进行划分可以使代码更易于组织和理解。在 api 目录下，我们可以为每个模块创建一个单独的文件，并在主文件中导入和注册这些模块的路由。

# app/api/users.py

from fastapi import APIRouter

router = APIRouter()

@router.get("/users")
def get_users():
    ...


# app/api/items.py

from fastapi import APIRouter

router = APIRouter()

@router.get("/items")
def get_items():
    ...


# app/api/main.py

from fastapi import FastAPI
from .users import router as users_router
from .items import router as items_router

app = FastAPI()

app.include_router(users_router)
app.include_router(items_router)

使用通用的 CRUD 路由

在编写路由时，使用通用的 CRUD （增删改查）路由可以减少重复的代码，提高代码的复用性。FastAPI 提供了 CRUDRouter 类来帮助我们快速编写通用的 CRUD 路由。

# app/api/users.py

from fastapi import APIRouter
from fastapi_crudrouter import (
    MemoryCRUDRouter,
    SQLAlchemyCRUDRouter
)

router = APIRouter()
crude_router = MemoryCRUDRouter(schema=User, prefix="/users", tags=["users"])
router.include_router(crud_router)

异步处理

FastAPI 支持异步处理，这意味着我们可以编写异步的代码来提高性能。以下是一些异步处理的最佳实践：

使用异步数据库

在 FastAPI 中，我们可以使用异步数据库来提高数据库操作的性能。例如，可以使用异步的 SQL 数据库框架如 SQLAlchemy async API 或者异步 NoSQL 数据库框架如 Motor（MongoDB 驱动程序）。

# app/db.py

import asyncio
from databases import Database

database = Database("sqlite:///example.db")

async def connect_to_db():
    await database.connect()

async def close_db_connection():
    await database.disconnect()


-- app/api/main.py

from fastapi import FastAPI
from app.db import connect_to_db, close_db_connection

app = FastAPI()

@app.on_event("startup")
async def startup():
    await connect_to_db()

@app.on_event("shutdown")
async def shutdown():
    await close_db_connection()

使用异步任务

在处理耗时的操作时，可以使用异步任务来避免阻塞请求处理过程。FastAPI 支持使用 BackgroundTasks 类来处理异步任务。

from fastapi import BackgroundTasks

@app.post("/run_task")
async def run_task(background_tasks: BackgroundTasks):
    def task():
        # 耗时任务
        ...

    background_tasks.add_task(task)

测试和文档

对于一个优秀的项目，良好的测试覆盖率和清晰的文档是非常重要的。以下是一些关于测试和文档的最佳实践：

单元测试

编写单元测试可以帮助我们验证代码的正确性和增加可维护性。FastAPI 项目可以借助 Pytest 进行单元测试。

功能测试

不仅单元测试，还需要编写功能测试来确保项目整体功能的正常运行。FastAPI 提供了一个 TestClient 类，方便我们编写功能测试。

自动生成文档

使用 FastAPI，我们可以通过注释快速生成文档。FastAPI 支持自动生成交互式文档，并且还可以生成 Swagger UI 和 ReDoc。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    """读取一个项目"""
    ...

总结

通过本文，我们了解了构建一个结构良好的 FastAPI 项目的最佳实践。从项目结构、路由设计、异步处理、测试和文档等方面，我们可以编写出易于维护和扩展的 FastAPI 项目。希望本文对你构建 FastAPI 项目时有所帮助。