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

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

一个 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**是你的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 端点。它按照应用程序中的特定实体和功能划分成不同的子文件夹。

例如: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/** 文件夹包含了应用程序的配置设置，如数据库配置、密钥等。

例如：**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/** 文件夹中包含了一些 Pydantic 模式定义，用于验证进出的数据。

例如:**item.py**位于**schemas/**

从 pydantic 导入 BaseModel  # 导入 BaseModel 类

class Item(BaseModel):
    id: int  # 唯一标识符
    name: str  # 名称
    description: str  # 描述

    class Config:
        orm_mode = True

**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/** 文件夹包含数据库配置文件，其中包括数据库会话文件和初始化文件，

例如：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/**文件夹下，包含你的应用的单元和集成测试。测试你的代码非常重要，可以确保其可靠性和稳定性。

例如:**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"

1. 结论

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

想要了解FastAPI的最佳实践和教程内容吗？订阅我们的邮件列表，获取更多实用技巧和独家内容。不要错过！

现在就订阅，增强您的 FastAPI 项目！

注：栈ademic 直译自 “stackademic”，意指与技术栈相关的学术或讨论。

感谢您一直读到最后。在您离开之前：

如果您有任何问题或意见，请随时告诉我们。

• 请考虑为作者点赞并点关注！ 👏
• 关注我们：X | LinkedIn | YouTube | Discord
• 了解我们的其他平台: In Plain English | CoFeed | Differ
• 更多内容请见 Stackademic.com