# flask_example

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

## 🚀 快速开始

```bash
# 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` | 开发环境启动入口 |