75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# 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` | 开发环境启动入口 | |