FastAPI项目结构的最佳实践：让你的代码更清晰、易扩展

FastAPI项目结构的最佳实践：让你的代码更清晰、易扩展

正确地组织一个 FastAPI 项目对于保持代码整洁、易于理解且可扩展至关重要。一个良好的项目结构有助于团队成员之间的协作，并减少添加新功能或解决bug所需的时间。在这篇文章中，我们将探讨组织 FastAPI 项目的最佳实践，并用代码示例帮助你有效组织文件夹和文件。

快速API项目的结构基础

一个 FastAPI 项目的最基本结构可以简化如下：

  
    my_project/  
    ├── app/  # 应用主目录
    │   ├── main.py  # 主程序文件
    │   ├── api/  # API接口目录
    │   │   ├── __init__.py  
    │   │   └── controllers/  # 控制器目录
    │   │       ├── __init__.py  
    │   │       └── items.py  # 项目项控制器
    │   ├── core/  # 核心配置目录
    │   │   ├── __init__.py  
    │   │   └── config.py  # 配置文件
    │   ├── models/  # 模型目录
    │   │   ├── __init__.py  
    │   │   └── item.py  # 项目项模型
    │   ├── schemas/  # 模式目录
    │   │   ├── __init__.py  
    │   │   └── item.py  # 项目项模式
    │   ├── crud/  # 增删查改操作目录
    │   │   ├── __init__.py  
    │   │   └── item.py  # 项目项增删查改操作
    │   ├── db/  # 数据库目录
    │   │   ├── __init__.py  
    │   │   └── session.py  # 会话文件
    │   └── tests/  # 测试目录
    │       ├── __init__.py  
    │       └── test_items.py  # 项目项测试文件
    ├── .env  # 环境配置文件
    ├── requirements.txt  # 依赖文件
    └── README.md  # 项目说明文件  

文件夹结构的细节

主要脚本：main.py（主程序入口）

main.py 是你的FastAPI应用程序的入口点。它初始化应用程序，并定义了路由。

例如:

main.py

  
from fastapi import FastAPI  
from app.api.controllers import items  
app = FastAPI()  
app.include_router(items.router)  
@app.get("/")  
def read_root():  
    return {"message": "欢迎来到FastAPI"}  

API/

api/ 文件夹包含了所有的 API 端点。它按照应用程序中的特定实体和功能划分成不同的子文件夹。

例如:

items.py

在 api/controllers

  
from fastapi import APIRouter, Depends, HTTPException  
from sqlalchemy.orm import Session  
from app.schemas.item import Item  
from app.crud.item import get_item, create_item  
from app.db.session import get_db  
router = APIRouter()  
@router.post("/items/", response_model=Item)  
def 创建新项目(item: Item, db: Session = Depends(get_db)):  
    db_item = get_item(db, item_id=item.id)  
    如果 db_item:  
        raise HTTPException(status_code=400, detail="项目已存在了")  
    return create_item(db=db, item=item)  

core/

core/ 文件夹包含了应用程序的配置设置，如数据库配置、密钥等。

例如：

config.py

在 core/

  
导入 os
# from dotenv import load_dotenv
load_dotenv()
# 定义设置类，用于存储项目配置信息
class Settings:
    PROJECT_NAME: str = "FastAPI Project"
    SQLALCHEMY_DATABASE_URI: str = os.getenv("DATABASE_URL")
settings = Settings()  

模型/

models/ 文件夹包含数据库模型的定义。每个模型对应数据库中的一个表。

例如:

item.py

位于 models/

  
// 从sqlalchemy导入列、整数和字符串等模块
from sqlalchemy import Column, Integer, String  
// 从app.db.session导入Base类
from app.db.session import Base  
// 定义一个继承自Base的Item类
class Item(Base):  
    // 设置表名为"items"
    __tablename__ = "items"  
    // 定义一个名为id的列，类型为整数，设置为主键和索引
    id = Column(Integer, primary_key=True, index=True)  
    // 定义一个名为name的列，类型为字符串，设置为索引
    name = Column(String, index=True)  
    // 定义一个名为description的列，类型为字符串，设置为索引
    description = Column(String, index=True)  

schemas/

在 schemas/ 文件夹中包含了一些 Pydantic 模式定义，用于验证进出的数据。

例如:

item.py

位于 schemas/

  
从 pydantic 导入 BaseModel  # 导入 BaseModel 类
class Item(BaseModel):
    id: int  # 唯一标识符
    name: str  # 名称
    description: str  # 描述
    class Config:
        orm_mode = True  

CRUD/（增删改查）

crud/ 文件夹里包含了与数据库交互的 CRUD（创建、读取、更新、删除）操作。

例如:

item.py

在 crud/

  
from sqlalchemy.orm import Session  
from app.models.item import Item as ItemModel  
from app.schemas.item import Item as ItemSchema  
def get_item(db: Session, item_id: int):  
    return db.query(ItemModel).filter(ItemModel.id == item_id).first()  
def create_item(db: Session, item: ItemSchema):  
    db_item = ItemModel(id=item.id, name=item.name, description=item.description)  
    db.add(db_item)  
    db.commit()  
    db.refresh(db_item)  
    return db_item  

db/（数据库目录）

db/ 文件夹包含数据库配置文件，其中包括数据库会话文件和初始化文件，

例如：

session.py

这个文件在 db/ 目录下。

  
从 sqlalchemy 导入 create_engine
从 sqlalchemy.ext.declarative 导入 declarative_base
从 sqlalchemy.orm 导入 sessionmaker
从 app.core.config 导入 settings
SQLALCHEMY_DATABASE_URL = settings.SQLALCHEMY_DATABASE_URI
engine = create_engine(SQLALCHEMY_DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()  

测试目录 (tests/)

在 tests/ 文件夹下，包含你的应用的单元和集成测试。测试你的代码非常重要，可以确保其可靠性和稳定性。

例如:

test_items.py

位于 tests/ 文件夹中

  
from fastapi.testclient import TestClient  
from app.main import app  
client = TestClient(app)  
def test_create_item():  
    response = client.post("/items/", json={"id": 1, "name": "Item 1", "description": "A sample item"})  
    assert response.status_code == 200  
    assert response.json()["name"] == "Item 1"  

结论

良好的项目结构对于保持代码的干净和可扩展性至关重要。通过遵循这些最佳实践，您可以使您的FastAPI项目组织得当，从而使这些过程更加简便，使开发、调试和协作过程更加容易。