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

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

在开发FastAPI项目时，一个清晰且合理的项目结构不仅能提高代码的可读性和可维护性，还能促进团队协作和功能扩展。本文将为您详细介绍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应用程序的入口点。它初始化应用程序，并定义了路由。

例如：

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/
import 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/文件夹

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

例如：

# item.py 位于 models/
from sqlalchemy import Column, Integer, String  
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/
from pydantic import 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/ 目录下。
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from app.core.config import 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项目组织得当，从而使这些过程更加简便，使开发、调试和协作过程更加容易。