template/README.md

Python项目模板

这是一个通用的Python项目模板，基于Flask框架的最佳实践，可以直接复制使用，快速启动新项目。

项目特性

• ✅ 标准化项目结构 - 清晰的目录组织，易于维护
• ✅ 多环境配置管理 - 支持development/production/testing/local环境
• ✅ 依赖分类管理 - 基础/开发/生产/测试依赖分离
• ✅ 应用工厂模式 - 灵活的Flask应用创建方式
• ✅ 数据库迁移支持 - 使用Flask-Migrate管理数据库版本
• ✅ 环境变量管理 - 使用.env文件管理敏感配置
• ✅ 完整的文档结构 - 包含API、开发、部署文档模板
• ✅ 测试框架集成 - pytest测试配置
• ✅ 日志系统 - 自动配置日志记录
• ✅ 跨域支持 - CORS配置

快速开始

1. 复制模板

# 复制整个template目录到你的新项目位置
cp -r template my_new_project
cd my_new_project

2. 初始化项目

# 创建虚拟环境
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. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑.env文件，填入你的配置
# 至少需要设置：
# - SECRET_KEY
# - DATABASE_URL
# - FLASK_ENV

4. 初始化数据库

# 初始化数据库迁移
flask db init

# 创建初始迁移
flask db migrate -m "Initial migration"

# 应用迁移
flask db upgrade

5. 运行项目

# 开发模式
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 环境变量来选择配置：

# 开发环境（默认）
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/ 创建工具函数

数据库迁移

# 创建迁移
flask db migrate -m "描述信息"

# 应用迁移
flask db upgrade

# 回滚迁移
flask db downgrade

运行测试

# 安装测试依赖
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: 测试框架和工具

安装方式：

# 开发环境
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: 运行环境

部署

开发环境

python run_dev.py

生产环境

# 使用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)

• 初始版本
• 基础项目结构
• 多环境配置支持
• 依赖分类管理