flask_example/README.md

flask_example

基于 Flask 3.x + SQLAlchemy 2.0 的生产级项目模板
内置应用工厂、数据库迁移、安全配置和 CRUD 示例

🚀 快速开始

# 1. 克隆项目
git clone <your-repo-url> && cd flask-db-template

# 2. 创建虚拟环境并安装依赖
python -m venv venv
source venv/bin/activate        # macOS/Linux
# venv\Scripts\activate         # Windows
pip install -r requirements.txt

# 3. 配置环境变量（⚠️ 必须执行）
cp .env.example .env
# 编辑 .env，至少修改 SECRET_KEY 和 DATABASE_URL

# 4. 初始化数据库
flask db init                   # 首次执行，生成 migrations/ 目录
flask db migrate -m "init"     # 生成迁移脚本
flask db upgrade                # 应用迁移到数据库

# 5. 启动开发服务器
python run.py

📡 API 接口

方法	路径	说明	请求体
POST	/api/users	创建用户	{"username":"test","email":"t@example.com"}
GET	/api/users?page=1&per_page=20	分页查询用户	-

⚠️ 安全须知

• 永远不要将 .env 提交到 Git（已在 .gitignore 中排除）
• 生产部署使用 Gunicorn：gunicorn -w 4 -b 0.0.0.0:8000 "run:app"
• 修改模型后必须执行 flask db migrate + flask db upgrade
• debug=True 仅限开发环境，生产环境开启会导致源码泄露

📂 项目结构说明

flask-db-template/
├── app/
│   ├── __init__.py          # 应用工厂：创建Flask实例并初始化扩展
│   ├── config.py            # 配置管理：集中管理所有环境变量和数据库配置
│   ├── models/
│   │   ├── __init__.py      # 模型统一导出：确保迁移工具能发现所有表
│   │   └── user.py          # 用户模型：定义数据表结构和序列化方法
│   └── routes/
│       ├── __init__.py      # 蓝图统一导出
│       └── user.py          # 用户API：包含完整的CRUD和异常处理
├── migrations/              # 数据库迁移目录（由flask db init生成）
│   └── .gitkeep             # Git空目录占位符
├── .env.example             # 环境变量模板（不含真实密码，可安全提交）
├── .gitignore               # Git忽略规则（防止敏感文件和缓存被提交）
├── README.md                # 项目文档
├── requirements.txt         # Python依赖清单（锁定版本保证环境一致）
└── run.py                   # 启动入口：开发环境启动脚本

文件/目录	作用
app/__init__.py	应用工厂，创建 Flask 实例并初始化扩展
app/config.py	集中配置管理，从环境变量读取敏感信息
app/models/	SQLAlchemy 数据模型定义
app/routes/	Blueprint 路由模块，按资源拆分
migrations/	Alembic 数据库迁移脚本
.env.example	环境变量模板（安全提交到 Git）
run.py	开发环境启动入口