首次提交

README.md

@@ -1,19 +1,75 @@
 # flask_example
 
-flask框架和连接数据库模板
+> 基于 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
 ```
-my_flask_app/
+
+## 📡 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      # 应用工厂 & 扩展初始化
-│   ├── config.py        # 配置文件
-│   ├── models/          # 数据模型
-│   │   ├── __init__.py
-│   │   └── user.py
-│   └── routes/          # 蓝图/路由
-│       ├── __init__.py
-│       └── user.py
-├── migrations/          # 数据库迁移文件 (Flask-Migrate)
-├── .env                 # 环境变量（不要提交到Git）
-├── requirements.txt
-└── run.py               # 启动入口
-```
+│   ├── __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` | 开发环境启动入口 |