259 lines
6.4 KiB
Markdown
259 lines
6.4 KiB
Markdown
# Python项目模板
|
||
|
||
这是一个通用的Python项目模板，基于Flask框架的最佳实践，可以直接复制使用，快速启动新项目。
|
||
|
||
## 项目特性
|
||
|
||
- ✅ **标准化项目结构** - 清晰的目录组织，易于维护
|
||
- ✅ **多环境配置管理** - 支持development/production/testing/local环境
|
||
- ✅ **依赖分类管理** - 基础/开发/生产/测试依赖分离
|
||
- ✅ **应用工厂模式** - 灵活的Flask应用创建方式
|
||
- ✅ **数据库迁移支持** - 使用Flask-Migrate管理数据库版本
|
||
- ✅ **环境变量管理** - 使用.env文件管理敏感配置
|
||
- ✅ **完整的文档结构** - 包含API、开发、部署文档模板
|
||
- ✅ **测试框架集成** - pytest测试配置
|
||
- ✅ **日志系统** - 自动配置日志记录
|
||
- ✅ **跨域支持** - CORS配置
|
||
|
||
## 快速开始
|
||
|
||
### 1. 复制模板
|
||
|
||
```bash
|
||
# 复制整个template目录到你的新项目位置
|
||
cp -r template my_new_project
|
||
cd my_new_project
|
||
```
|
||
|
||
### 2. 初始化项目
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python -m venv .venv
|
||
|
||
# 激活虚拟环境
|
||
# Windows
|
||
.venv\Scripts\activate
|
||
# Linux/Mac
|
||
source .venv/bin/activate
|
||
|
||
# 安装依赖
|
||
pip install -r requirements/base.txt
|
||
pip install -r requirements/development.txt
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
|
||
```bash
|
||
# 复制环境变量模板
|
||
cp .env.example .env
|
||
|
||
# 编辑.env文件，填入你的配置
|
||
# 至少需要设置：
|
||
# - SECRET_KEY
|
||
# - DATABASE_URL
|
||
# - FLASK_ENV
|
||
```
|
||
|
||
### 4. 初始化数据库
|
||
|
||
```bash
|
||
# 初始化数据库迁移
|
||
flask db init
|
||
|
||
# 创建初始迁移
|
||
flask db migrate -m "Initial migration"
|
||
|
||
# 应用迁移
|
||
flask db upgrade
|
||
```
|
||
|
||
### 5. 运行项目
|
||
|
||
```bash
|
||
# 开发模式
|
||
python run_dev.py
|
||
|
||
# 或使用Flask命令
|
||
flask run
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
template/
|
||
├── src/ # 源代码目录
|
||
│ └── your_app/ # 主应用包（需要重命名）
|
||
│ ├── __init__.py # 应用工厂
|
||
│ ├── app.py # 应用配置
|
||
│ ├── models/ # 数据模型
|
||
│ ├── routes/ # 路由定义
|
||
│ ├── services/ # 业务逻辑
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── forms/ # 表单定义（可选）
|
||
│ ├── static/ # 静态资源
|
||
│ └── templates/ # 模板文件
|
||
├── config/ # 配置管理
|
||
│ ├── __init__.py # 配置选择器
|
||
│ ├── base.py # 基础配置
|
||
│ ├── development.py # 开发环境
|
||
│ ├── production.py # 生产环境
|
||
│ ├── testing.py # 测试环境
|
||
│ └── local.py # 本地环境
|
||
├── requirements/ # 依赖管理
|
||
│ ├── base.txt # 基础依赖
|
||
│ ├── development.txt # 开发依赖
|
||
│ ├── production.txt # 生产依赖
|
||
│ └── test.txt # 测试依赖
|
||
├── tests/ # 测试目录
|
||
│ ├── __init__.py
|
||
│ ├── conftest.py # pytest配置
|
||
│ └── test_*.py # 测试文件
|
||
├── migrations/ # 数据库迁移（自动生成）
|
||
├── logs/ # 日志目录（自动生成）
|
||
├── uploads/ # 上传文件目录（自动生成）
|
||
├── docs/ # 文档目录
|
||
│ ├── api/ # API文档
|
||
│ ├── development/ # 开发文档
|
||
│ └── deployment/ # 部署文档
|
||
├── scripts/ # 工具脚本
|
||
│ └── init_project.py # 项目初始化脚本
|
||
├── .env.example # 环境变量模板
|
||
├── .gitignore # Git忽略文件
|
||
├── run_dev.py # 开发服务器启动脚本
|
||
├── run_production.py # 生产环境启动脚本
|
||
└── README.md # 项目说明（本文件）
|
||
```
|
||
|
||
## 使用说明
|
||
|
||
### 重命名项目
|
||
|
||
1. 将 `src/your_app/` 目录重命名为你的应用名称
|
||
2. 更新 `src/your_app/__init__.py` 中的导入路径
|
||
3. 更新 `run_dev.py` 和 `run_production.py` 中的导入路径
|
||
4. 更新所有文档中的项目名称
|
||
|
||
### 配置环境
|
||
|
||
通过设置 `FLASK_ENV` 环境变量来选择配置：
|
||
|
||
```bash
|
||
# 开发环境（默认）
|
||
export FLASK_ENV=development
|
||
|
||
# 生产环境
|
||
export FLASK_ENV=production
|
||
|
||
# 测试环境
|
||
export FLASK_ENV=testing
|
||
|
||
# 本地环境
|
||
export FLASK_ENV=local
|
||
```
|
||
|
||
### 添加新功能
|
||
|
||
1. **添加路由**：在 `src/your_app/routes/` 创建新的路由文件
|
||
2. **添加模型**：在 `src/your_app/models/` 创建新的模型文件
|
||
3. **添加服务**：在 `src/your_app/services/` 创建业务逻辑
|
||
4. **添加工具**：在 `src/your_app/utils/` 创建工具函数
|
||
|
||
### 数据库迁移
|
||
|
||
```bash
|
||
# 创建迁移
|
||
flask db migrate -m "描述信息"
|
||
|
||
# 应用迁移
|
||
flask db upgrade
|
||
|
||
# 回滚迁移
|
||
flask db downgrade
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 安装测试依赖
|
||
pip install -r requirements/test.txt
|
||
|
||
# 运行所有测试
|
||
pytest
|
||
|
||
# 运行特定测试文件
|
||
pytest tests/test_example.py
|
||
|
||
# 生成覆盖率报告
|
||
pytest --cov=src tests/
|
||
```
|
||
|
||
## 依赖管理
|
||
|
||
依赖按用途分类管理：
|
||
|
||
- **base.txt**: 项目运行必需的基础依赖
|
||
- **development.txt**: 开发工具（调试器、代码检查等）
|
||
- **production.txt**: 生产环境依赖（WSGI服务器等）
|
||
- **test.txt**: 测试框架和工具
|
||
|
||
安装方式：
|
||
|
||
```bash
|
||
# 开发环境
|
||
pip install -r requirements/base.txt
|
||
pip install -r requirements/development.txt
|
||
|
||
# 生产环境
|
||
pip install -r requirements/base.txt
|
||
pip install -r requirements/production.txt
|
||
```
|
||
|
||
## 环境变量说明
|
||
|
||
所有配置通过环境变量管理，详见 `.env.example` 文件。
|
||
|
||
**必需的环境变量：**
|
||
- `SECRET_KEY`: Flask密钥
|
||
- `DATABASE_URL`: 数据库连接URL
|
||
- `FLASK_ENV`: 运行环境
|
||
|
||
## 部署
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
python run_dev.py
|
||
```
|
||
|
||
### 生产环境
|
||
|
||
```bash
|
||
# 使用Gunicorn
|
||
gunicorn -c gunicorn.conf.py "src.your_app:create_app()"
|
||
|
||
# 或使用uWSGI
|
||
uwsgi --ini uwsgi.ini
|
||
```
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork本项目
|
||
2. 创建功能分支
|
||
3. 提交更改
|
||
4. 推送到分支
|
||
5. 创建Pull Request
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0 (2025-01-XX)
|
||
- 初始版本
|
||
- 基础项目结构
|
||
- 多环境配置支持
|
||
- 依赖分类管理
|
||
|