# ScratchFlask

**Repository Path**: zypdominate/scratch-flask

## Basic Information

- **Project Name**: ScratchFlask
- **Description**: Flask Web 开发实战
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-10
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ScratchFlask

`ScratchFlask` 是一个面向教学与自学的 Flask 实践仓库，仓库内不是单一应用，而是一组可独立运行的示例集合。内容从最小 Flask 路由开始，逐步覆盖模板系统、表单与校验、数据库操作、关系建模、蓝图模块化组织，以及中型项目结构设计。

如果你正在学习 Flask，这个仓库可以作为“按主题拆分的代码地图”，每个目录都能单独启动并验证效果。

## 仓库定位

- 面向对象：有 Python 基础，准备系统学习 Flask 的开发者。
- 使用场景：课堂演示，章节练习，面试前复盘，小项目搭建参考。
- 组织方式：按“核心机制”“章节示例”“专题实战”“完整应用”四个层次分层。

## 目录结构

```text
ScratchFlask/
├── core_demos/                  # Flask 核心机制演示
├── demos/                       # 章节化入门示例
├── subjects/                    # 专题示例（Jinja2、校验、关系建模）
├── sayhello/                    # 包应用模式示例
├── simpleBlog/                  # 博客应用示例（蓝图组织）
├── md/                          # 辅助学习文档
└── requirements.txt             # 根依赖
```

模块：

1.  **[核心原理解析 (core_demos)](./core_demos/)**：从 WSGI 开始，透彻理解 Flask 的请求生命周期、上下文机制与蓝图。
2.  **[基础功能实战 (demos)](./demos/)**：通过 6 个章节的循序渐进，掌握路由、模板、表单、数据库集成与蓝图组织。
3.  **[标准项目结构 (sayhello)](./sayhello/)**：学习如何构建一个符合工业标准的、包含单元测试的 Flask 小型应用。
4.  **[进阶专题研究 (subjects)](./subjects/)**：深入探讨 SQLAlchemy 关系建模、复杂数据验证以及 Jinja2 的高级用法。
5.  **[全功能应用开发 (simpleBlog)](./simpleBlog/)**：分析并实践一个功能完备的博客系统，涵盖认证、后台管理与数据伪造等。

## 技术栈与依赖

- Python 3
- Flask 3.0.3
- Jinja2 3.1.4
- Flask-WTF 1.2.1
- WTForms 3.1.2
- Flask-SQLAlchemy 3.1.1
- SQLAlchemy 2.0.30
- Pytest 8.2.2

根目录 `requirements.txt` 已整理常用学习依赖，包含模板、校验、数据库、测试、代码质量工具。

## 环境准备

- Python 3.10 及以上
- pip 可用
- 建议使用虚拟环境，避免污染全局解释器
- Windows、macOS、Linux 均可运行

## 快速操作

一、创建并激活虚拟环境

```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
```

二、安装依赖

```bash
pip install -r requirements.txt
```

三、运行一个最小示例

```bash
cd demos/ch1_basic_routing
python app.py
```

四、浏览器访问地址

```text
http://127.0.0.1:5000/
```

## 模块说明

### `core_demos`

定位：聚焦 Flask 核心机制，适合理解“为什么能运行”。

面向已有一定使用经验的开发者，专注于“原理 → 机制 → 工程化”的深入剖析。

包含主题：
- WSGI 与 Flask 的关系
- 请求与响应对象
- 路由与 URL 反向构建
- 应用上下文与请求上下文
- 请求生命周期钩子
- 蓝图注册机制
- Jinja2 模板上下文
- 错误处理与日志

建议：按目录编号顺序学习，每次只运行一个 demo。

### `demos`

定位：章节化入门练习，偏向“怎么用”。

每个章节都是一个可独立运行的小型 Demo，涵盖了 Web 开发的基础设施。

章节内容：
- `ch1_basic_routing`：基础路由、动态参数、CLI 命令
- `ch2_request_response`：请求数据读取、响应构造、重定向
- `ch3_templates`：模板继承、过滤器、宏、静态资源
- `ch4_forms`：基础表单、Flask-WTF、文件上传
- `ch5_database`：SQLAlchemy 模型、CRUD、分页
- `ch6_blueprints`：蓝图拆分、模块化模板组织

### `subjects`

定位：专项训练，适合查漏补缺。

子目录说明：
- `subjects/jinja2_demos`：Jinja2 五个渐进式演示，覆盖基础语法到高级特性。
- `subjects/flask_validation_demos`：数据校验专题，包含表单校验、条件校验、文件校验、API 校验。
- `subjects/flask_relations_demos`：关系建模专题，包含博客、电商、学校三类关系场景。

专注于特定领域的技术难点：

- **Jinja2 进阶 (`jinja2_demos`)**: 宏的高级应用、模板继承的最优解。
- **数据验证 (`flask_validation_demos`)**: 复杂表单校验、自定义验证器以及 API 级别的验证。
- **关系建模 (`flask_relations_demos`)**: 涵盖一对多、多对多（纯中间表/带字段中间表）的完整实现。

### `sayhello`

定位：包应用模式示例，适合学习 `__init__.py` 组织方式。

能力范围：
- 自定义命令
- 表单与模型联动
- DebugToolbar 与页面调试
- SQLite 本地数据文件

### `simpleBlog`

定位：中型 Flask 应用示例，适合理解蓝图分层和可测试结构。

能力范围：
- `auth`、`blog`、`admin` 蓝图拆分
- 数据模型与后台管理页
- 单元测试样例
- 数据初始化与虚拟数据脚本

## 运行参考

### 通用模式

- 进入目标目录后，先看该目录内 `README.md`
- 按子项目要求初始化数据库
- 使用 `python app.py`、`python run.py` 或 `flask --app ... run` 启动

### `subjects/flask_validation_demos`

```bash
cd subjects/flask_validation_demos
python run.py
```

默认端口：
- `http://127.0.0.1:5002/`

可用命令：
- `flask --app run.py init-db`
- `flask --app run.py seed-db`
- `flask --app run.py reset-db`

### `subjects/flask_relations_demos`

```bash
cd subjects/flask_relations_demos
python run.py
```

默认端口：
- `http://127.0.0.1:5003/`

### `sayhello`

```bash
cd sayhello
flask --app sayhello forge
flask --app sayhello run
```

或直接运行：

```bash
python run.py
```

### `simpleBlog`

```bash
cd simpleBlog
flask --app simpleBlog forge
flask --app simpleBlog run
```

也可以使用：

```bash
python init_db.py
python forge.py
python run.py
```

## 数据与状态文件

仓库中部分示例已包含本地数据库文件，用于教学快速启动：

- `sayhello/data.db`
- `simpleBlog/data.db`
- `subjects/flask_validation_demos/instance/validation_demo.db`
- `subjects/flask_relations_demos/instance/relations_demo.db`
- `demos/ch5_database/app.db`

如果你希望从空状态开始，可删除对应数据库文件后重新执行初始化命令。

## 测试与代码质量

测试重点在 `simpleBlog/tests`。

可在仓库根目录执行：

```bash
pytest
```

若只运行 blog 示例测试：

```bash
pytest simpleBlog/tests
```

代码质量工具依赖已在根依赖中提供，可按需要补充本地检查流程。

## 推荐学习顺序

- 先跑通 `demos/ch1_basic_routing` 到 `demos/ch6_blueprints`，建立完整开发链路。
- 再看 `core_demos`，理解请求上下文、生命周期、蓝图机制等底层原理。
- 然后进入 `subjects` 做专题训练，强化模板、校验、关系建模。
- 最后阅读 `sayhello` 与 `simpleBlog`，对照真实项目结构进行复盘。

## 常见问题

### 依赖安装后仍报模块不存在

- 检查当前终端是否已激活正确虚拟环境。
- 检查 `python` 与 `pip` 是否指向同一解释器。

### 启动报端口占用

- 修改运行端口，或先关闭已占用进程。
- 可通过环境变量传入端口，或修改对应 `run.py` 中的端口配置。

### 出现 `no such table` 错误

- 说明数据库未初始化。
- 请在对应子项目目录执行初始化命令，或运行项目提供的初始化脚本。

## 维护说明

- 各子目录文档可能存在差异，以子目录内 `README.md` 为准。
- 根文档负责全局导航与统一入口，不替代各子项目细节说明。