template/PROJECT_STRUCTURE.md

项目结构说明

目录结构

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管理数据库变更：

flask db migrate -m "描述"
flask db upgrade

最佳实践

1. 代码组织: 按功能模块组织代码，保持单一职责
2. 配置管理: 所有配置通过环境变量，不要硬编码
3. 错误处理: 统一错误处理，返回标准格式
4. 日志记录: 重要操作记录日志
5. 测试覆盖: 关键功能编写测试
6. 文档更新: 及时更新文档，保持同步