【FastAPI】小型项目的目录结构设计与命名规范

在使用 FastAPI 进行小型项目开发时，良好的目录结构与命名规范能让代码更易于维护和扩展。下面是一个适合小型项目的目录结构示例，以及相关的命名规范建议：

FastAPI 小型项目目录结构示例

project_name/
│
├── app/
│   ├── __init__.py            # 使 app 目录成为一个模块
│   ├── main.py                # FastAPI 应用入口
│   ├── api/                   # API 路由
│   │   ├── __init__.py
│   │   └── v1/                # 版本化 API
│   │       ├── __init__.py
│   │       ├── endpoints/     # 具体的 API 端点
│   │       │   ├── __init__.py
│   │       │   ├── user.py    # 示例：用户相关的 API
│   │       │   └── item.py    # 示例：物品相关的 API
│   │       └── dependencies.py # 依赖项管理
│   ├── core/                  # 核心功能
│   │   ├── __init__.py
│   │   └── config.py          # 配置文件
│   ├── models/                # 数据库模型
│   │   ├── __init__.py
│   │   └── user.py            # 示例：用户数据库模型
│   ├── crud/                  # 数据库操作
│   │   ├── __init__.py
│   │   └── user.py            # 示例：用户数据的增删改查
│   ├── schemas/               # 数据验证模型 (Pydantic 模型)
│   │   ├── __init__.py
│   │   └── user.py            # 示例：用户的数据模式
│   └── utils/                 # 辅助工具函数
│       ├── __init__.py
│       └── security.py        # 安全相关工具函数，如密码哈希
│
├── tests/                     # 单元测试
│   ├── __init__.py
│   └── test_user.py           # 示例：用户相关的测试
│
├── .env                       # 环境变量文件
├── requirements.txt           # 项目依赖
└── README.md                  # 项目说明文件

命名规范

1. 模块与文件命名

   • 使用小写字母，单词之间用下划线分隔。例如：user.py，item.py。
   • 模块目录如 api/, models/, schemas/ 应清晰表明它们的职责。

2. 类命名

   • 类名使用帕斯卡命名法（PascalCase）。例如：UserModel, ItemSchema。
   • 数据库模型类名通常对应数据库表名。

3. 函数与变量命名

   • 函数和变量使用蛇形命名法（snake_case）。例如：get_user, create_item。

4. 配置项命名

   • 配置项变量通常大写，多个单词用下划线分隔。例如：DATABASE_URL, SECRET_KEY。

5. API 路由

   • API 路由通常使用复数形式，表示资源集合。例如：/users，/items。

补充说明

• 版本控制：在 api/v1/ 目录中实现 API 的版本化，方便后期扩展或更新 API 时保持向后兼容。
• 依赖管理：将依赖项统一管理在 dependencies.py 中，方便集中注入依赖。

这种目录结构清晰、规范，适用于小型项目，并且可以轻松扩展到中大型项目。