在使用 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 # 项目说明文件
命名规范
-
模块与文件命名
- 使用小写字母,单词之间用下划线分隔。例如:
user.py
,item.py
。 - 模块目录如
api/
,models/
,schemas/
应清晰表明它们的职责。
- 使用小写字母,单词之间用下划线分隔。例如:
-
类命名
- 类名使用帕斯卡命名法(PascalCase)。例如:
UserModel
,ItemSchema
。 - 数据库模型类名通常对应数据库表名。
- 类名使用帕斯卡命名法(PascalCase)。例如:
-
函数与变量命名
- 函数和变量使用蛇形命名法(snake_case)。例如:
get_user
,create_item
。
- 函数和变量使用蛇形命名法(snake_case)。例如:
-
配置项命名
- 配置项变量通常大写,多个单词用下划线分隔。例如:
DATABASE_URL
,SECRET_KEY
。
- 配置项变量通常大写,多个单词用下划线分隔。例如:
-
API 路由
- API 路由通常使用复数形式,表示资源集合。例如:
/users
,/items
。
- API 路由通常使用复数形式,表示资源集合。例如:
补充说明
- 版本控制:在
api/v1/
目录中实现 API 的版本化,方便后期扩展或更新 API 时保持向后兼容。 - 依赖管理:将依赖项统一管理在
dependencies.py
中,方便集中注入依赖。
这种目录结构清晰、规范,适用于小型项目,并且可以轻松扩展到中大型项目。