155 lines
6.0 KiB
Markdown
155 lines
6.0 KiB
Markdown
|
# 项目结构说明
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
template/
|
|||
|
|
├── src/ # 源代码目录
|
|||
|
|
│ └── your_app/ # 主应用包（需要重命名为你的应用名）
|
|||
|
|
│ ├── __init__.py # 应用工厂，创建Flask应用实例
|
|||
|
|
│ ├── app.py # 应用入口（可选，可直接运行）
|
|||
|
|
│ ├── models/ # 数据模型
|
|||
|
|
│ │ ├── __init__.py # 导出db实例和所有模型
|
|||
|
|
│ │ └── example.py # 示例模型
|
|||
|
|
│ ├── routes/ # 路由定义
|
|||
|
|
│ │ ├── __init__.py # 主路由蓝图
|
|||
|
|
│ │ └── *.py # 其他路由模块
|
|||
|
|
│ ├── services/ # 业务逻辑层
|
|||
|
|
│ │ └── __init__.py # 服务模块初始化
|
|||
|
|
│ ├── utils/ # 工具函数
|
|||
|
|
│ │ ├── __init__.py # 工具模块初始化
|
|||
|
|
│ │ └── helpers.py # 辅助函数
|
|||
|
|
│ ├── forms/ # 表单定义（可选，如果使用WTForms）
|
|||
|
|
│ │ └── __init__.py
|
|||
|
|
│ ├── static/ # 静态资源（CSS、JS、图片等）
|
|||
|
|
│ │ ├── css/
|
|||
|
|
│ │ ├── js/
|
|||
|
|
│ │ └── images/
|
|||
|
|
│ └── templates/ # Jinja2模板文件
|
|||
|
|
│ ├── base.html # 基础模板
|
|||
|
|
│ └── *.html # 其他模板
|
|||
|
|
│
|
|||
|
|
├── config/ # 配置管理
|
|||
|
|
│ ├── __init__.py # 配置选择器，根据环境变量选择配置
|
|||
|
|
│ ├── base.py # 基础配置类，所有环境通用配置
|
|||
|
|
│ ├── development.py # 开发环境配置
|
|||
|
|
│ ├── production.py # 生产环境配置
|
|||
|
|
│ ├── testing.py # 测试环境配置
|
|||
|
|
│ └── local.py # 本地环境配置
|
|||
|
|
│
|
|||
|
|
├── requirements/ # 依赖管理（分类管理）
|
|||
|
|
│ ├── base.txt # 基础依赖（项目运行必需）
|
|||
|
|
│ ├── development.txt # 开发依赖（开发工具）
|
|||
|
|
│ ├── production.txt # 生产依赖（WSGI服务器等）
|
|||
|
|
│ └── test.txt # 测试依赖（测试框架）
|
|||
|
|
│
|
|||
|
|
├── tests/ # 测试目录
|
|||
|
|
│ ├── __init__.py
|
|||
|
|
│ ├── conftest.py # pytest配置和fixtures
|
|||
|
|
│ └── test_*.py # 测试文件
|
|||
|
|
│
|
|||
|
|
├── migrations/ # 数据库迁移（Flask-Migrate自动生成）
|
|||
|
|
│ ├── versions/ # 迁移版本文件
|
|||
|
|
│ ├── env.py # 迁移环境配置
|
|||
|
|
│ └── alembic.ini # Alembic配置
|
|||
|
|
│
|
|||
|
|
├── logs/ # 日志目录（自动生成）
|
|||
|
|
│ └── app.log # 应用日志
|
|||
|
|
│
|
|||
|
|
├── uploads/ # 上传文件目录（自动生成）
|
|||
|
|
│
|
|||
|
|
├── docs/ # 文档目录
|
|||
|
|
│ ├── README.md # 文档索引
|
|||
|
|
│ ├── api/ # API文档
|
|||
|
|
│ │ └── README.md
|
|||
|
|
│ ├── development/ # 开发文档
|
|||
|
|
│ │ └── README.md
|
|||
|
|
│ └── deployment/ # 部署文档
|
|||
|
|
│ └── README.md
|
|||
|
|
│
|
|||
|
|
├── scripts/ # 工具脚本
|
|||
|
|
│ └── init_project.py # 项目初始化脚本
|
|||
|
|
│
|
|||
|
|
├── .gitignore # Git忽略文件
|
|||
|
|
├── .flake8 # flake8代码检查配置
|
|||
|
|
├── pytest.ini # pytest测试配置
|
|||
|
|
├── env.example # 环境变量模板
|
|||
|
|
├── gunicorn.conf.py # Gunicorn生产服务器配置
|
|||
|
|
├── run_dev.py # 开发环境启动脚本
|
|||
|
|
├── run_production.py # 生产环境启动脚本（测试用）
|
|||
|
|
├── README.md # 项目说明文档
|
|||
|
|
├── QUICK_START.md # 快速开始指南
|
|||
|
|
└── PROJECT_STRUCTURE.md # 本文件
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 核心文件说明
|
|||
|
|
|
|||
|
|
### 应用工厂 (`src/your_app/__init__.py`)
|
|||
|
|
|
|||
|
|
使用工厂模式创建Flask应用，支持：
|
|||
|
|
- 多环境配置
|
|||
|
|
- 扩展初始化
|
|||
|
|
- 蓝图注册
|
|||
|
|
- 错误处理
|
|||
|
|
|
|||
|
|
### 配置管理 (`config/`)
|
|||
|
|
|
|||
|
|
- **base.py**: 所有环境通用的配置
|
|||
|
|
- **development.py**: 开发环境（调试模式开启）
|
|||
|
|
- **production.py**: 生产环境（安全配置）
|
|||
|
|
- **testing.py**: 测试环境（内存数据库）
|
|||
|
|
- **local.py**: 本地环境（可自定义）
|
|||
|
|
|
|||
|
|
通过 `FLASK_ENV` 环境变量自动选择配置。
|
|||
|
|
|
|||
|
|
### 依赖管理 (`requirements/`)
|
|||
|
|
|
|||
|
|
分类管理依赖，便于不同环境安装：
|
|||
|
|
- **base.txt**: 核心依赖
|
|||
|
|
- **development.txt**: 开发工具
|
|||
|
|
- **production.txt**: 生产服务器
|
|||
|
|
- **test.txt**: 测试框架
|
|||
|
|
|
|||
|
|
### 测试 (`tests/`)
|
|||
|
|
|
|||
|
|
使用pytest框架：
|
|||
|
|
- **conftest.py**: 定义测试fixtures
|
|||
|
|
- **test_*.py**: 测试用例
|
|||
|
|
|
|||
|
|
## 使用建议
|
|||
|
|
|
|||
|
|
### 1. 项目命名
|
|||
|
|
|
|||
|
|
将 `your_app` 替换为你的实际项目名称：
|
|||
|
|
- 目录: `src/your_app` -> `src/my_project`
|
|||
|
|
- 导入: `from src.your_app import ...` -> `from src.my_project import ...`
|
|||
|
|
|
|||
|
|
### 2. 添加新功能
|
|||
|
|
|
|||
|
|
- **路由**: 在 `routes/` 创建新文件，定义蓝图，在 `__init__.py` 注册
|
|||
|
|
- **模型**: 在 `models/` 创建新文件，运行迁移
|
|||
|
|
- **服务**: 在 `services/` 创建业务逻辑
|
|||
|
|
- **工具**: 在 `utils/` 创建辅助函数
|
|||
|
|
|
|||
|
|
### 3. 环境配置
|
|||
|
|
|
|||
|
|
通过 `.env` 文件管理配置，不要提交到Git。
|
|||
|
|
|
|||
|
|
### 4. 数据库迁移
|
|||
|
|
|
|||
|
|
始终使用Flask-Migrate管理数据库变更：
|
|||
|
|
```bash
|
|||
|
|
flask db migrate -m "描述"
|
|||
|
|
flask db upgrade
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 最佳实践
|
|||
|
|
|
|||
|
|
1. **代码组织**: 按功能模块组织代码，保持单一职责
|
|||
|
|
2. **配置管理**: 所有配置通过环境变量，不要硬编码
|
|||
|
|
3. **错误处理**: 统一错误处理，返回标准格式
|
|||
|
|
4. **日志记录**: 重要操作记录日志
|
|||
|
|
5. **测试覆盖**: 关键功能编写测试
|
|||
|
|
6. **文档更新**: 及时更新文档，保持同步
|
|||
|
|
|