first commit
This commit is contained in:
258
README.md
Normal file
258
README.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 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)
|
||||
- 初始版本
|
||||
- 基础项目结构
|
||||
- 多环境配置支持
|
||||
- 依赖分类管理
|
||||
|
||||
Reference in New Issue
Block a user