template/README.md

# 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)
- 初始版本
- 基础项目结构
- 多环境配置支持
- 依赖分类管理