# 第6章 · 如何使程序易于维护

对应教材第 6 章：配置抽离、应用工厂、蓝图拆分、命令行指令、用户认证。

本章解决一个很现实的问题：**代码一多就烂**。
两个项目分别对应两条主线 —— **结构**（怎么拆）和**身份**（怎么知道谁在用）。

| 项目 | 端口 | 一句话 |
|---|---|---|
| `ch6` | 5116 | 配置类 + 应用工厂 + 蓝图 + CLI 命令 |
| `ch6b` | 5117 | Flask-Login 登录 / 登出 / 权限保护 + 密码哈希 |

---

## 一、结构：`ch6/`

```bat
cd ch06\ch6
..\..\..\venv\Scripts\python.exe app.py
```

打开 <http://127.0.0.1:5116>。三个路由、两个蓝图、四套配置，全部串在一个工厂函数里。

### 目录

```
ch6/
├─ app.py               create_app() 工厂 + 注册蓝图 + 注册CLI
├─ config.py            BaseConfig / DevelopmentConfig / TestingConfig / ProductionConfig
├─ extensions.py        db / migrate / bootstrap 三个扩展对象（函数外创建，工厂里 init_app）
├─ models.py            User + Article（一对多），给第7章打底
├─ blueprints/
│  ├─ __init__.py
│  ├─ main.py           蓝图 main： / 和 /about
│  └─ auth.py           蓝图 auth： /auth/login
└─ templates/
   ├─ index.html  about.html  login.html
```

### 0. 扩展单例：为什么 db 要写在函数外面

教材第六章的 `database.py` 讲的就是这件事：**对象在函数外创建，以便在其他文件中引用**。

```python
# extensions.py
db = SQLAlchemy()          # 只有对象，还没绑定 app
migrate = Migrate()
bootstrap = Bootstrap5()
```

```python
# app.py 的工厂里
db.init_app(app)           # 绑定，且只绑一次
migrate.init_app(app, db)
bootstrap.init_app(app)
```

如果写成 `db = SQLAlchemy(app)` 放在工厂里面，`models.py` 就 `from ... import db` 不到（循环导入）。
所以：**对象在外面，绑定在工厂里**。这也是第 7 章博客能拆成多文件的前提。

### 1. 配置类：一套代码三种环境

`config.py` 里一个基类 + 三个子类，用字典做映射：

```python
configs = {
    'development': DevelopmentConfig,
    'testing':     TestingConfig,
    'production':  ProductionConfig,
    'default':     DevelopmentConfig,
}
```

工厂里按名字取：

```python
env = env or os.environ.get('FLASK_ENV', 'default')
app.config.from_object(configs[env])
```

切环境（**不改一行代码**）：

```bat
:: cmd
set FLASK_ENV=production
..\..\..\venv\Scripts\python.exe app.py
```

```powershell
# PowerShell
$env:FLASK_ENV="production"
..\..\..\venv\Scripts\python.exe app.py
```

刷新页面，底部提示条里的“当前环境”会从 `development` 变成 `production`。

**为什么生产环境必须关 DEBUG**：DEBUG 打开时，出错页面会把源码、变量、甚至数据库连接串全打印给访客。

### 2. 应用工厂：`create_app()`

```python
def create_app(env=None):
    app = Flask(__name__)
    app.config.from_object(configs[env])
    Bootstrap5(app)                    # 扩展在工厂里初始化
    app.register_blueprint(main_bp)
    app.register_blueprint(auth_bp, url_prefix='/auth')
    return app
```

好处：**想造几个造几个**。测试时 `create_app('testing')` 造一个内存库的，生产时再造一个连真库的，互不干扰。

扩展（`Bootstrap5`、`db`、`login_manager`）必须放在工厂**内部**初始化，否则第二次调用会重复注册报错。

### 3. 蓝图：路由按功能分文件

```python
bp = Blueprint('main', __name__)          # blueprints/main.py

@bp.route('/')
def index(): ...
```

```python
app.register_blueprint(main_bp)                        # 挂在 /
app.register_blueprint(auth_bp, url_prefix='/auth')    # 挂在 /auth 下
```

**关键变化**：`url_for` 要写全名 —— `url_for('main.index')`、`url_for('auth.login')`。
前面几章直接写 `url_for('index')` 就行，因为那时没有蓝图前缀。

### 4. 命令行指令：`flask --app app xxx`

教材用的是 `flask_script` 的 `@manager.command`，这个扩展已经废弃。现在用 Flask 内置的 CLI：

```python
@app.cli.command('stats')
def stats():
    ...
```

跑起来：

```bat
flask --app app routes            # 列出全部路由及所属蓝图
flask --app app config-show       # 打印当前环境配置
flask --app app stats             # 统计每个蓝图有几条路由
flask --app app hello --name 张三  # 带参数的自定义命令
flask --app app init-db           # 建表 + 造演示用户 admin/123456
flask --app app shell             # 进交互 Shell，直接敲 User.query
```

> 注意：`flask` 命令默认**关闭** DEBUG，这是 Flask 2.2 之后的行为，想开要加 `--debug`。
> 用 `python app.py` 跑则会按配置类里的 `DEBUG=True` 走。

`stats` 的实际输出能直接验证蓝图注册成功：

```
路由总数：5
  [auth] 1 条: /auth/login
  [main] 2 条: /, /about
```

### 5. Shell 上下文：进 shell 不用 import

```python
@app.shell_context_processor
def make_shell_context():
    return {'db': db, 'User': User, 'Article': Article}
```

```bat
flask --app app shell
>>> User.query.count()
1
```

教材第五章的 `manager.add_command("shell", Shell(make_context=make_shell_context))`，
在没了 `flask_script` 之后就是这 5 行装饰器——作用完全一样。

---

## 二、身份：`ch6b/`

```bat
cd ch06\ch6b
..\..\..\venv\Scripts\python.exe app.py
```

打开 <http://127.0.0.1:5117>，测试账号 **xie / 123456**（首次运行自动创建）。

| 地址 | 说明 |
|---|---|
| `/` | 首页，显示当前登录状态 |
| `/login` | 登录（用户名 + 密码） |
| `/member` | 会员页，**未登录会被自动跳回登录页** |
| `/logout` | 退出 |

### 五个关键点

```python
login_manager = LoginManager(app)
login_manager.login_view = 'login'          # ① 未登录访问受保护页跳这里
```

```python
class User(UserMixin, db.Model):            # ② UserMixin 白送 is_authenticated 等属性
    ...
```

```python
@login_manager.user_loader                  # ③ 按 id 装载用户（必写，否则登录态无法恢复）
def load_user(uid):
    return db.session.get(User, int(uid))
```

```python
@login_required                             # ④ 一行装饰器保护路由
def member(): ...
```

```python
u.set_password('123456')                    # ⑤ 只存哈希，绝不存明文
check_password_hash(u.password_hash, raw)   #    验证时比对哈希
```

**为什么不能存明文**：数据库一旦泄露（拖库），明文密码等于把所有用户的账号连同他们在其他网站的密码一起交出去。
哈希是单向的，加盐后同样的密码在不同用户身上哈希值也不同，彩虹表也失效。

`generate_password_hash` 每次运行结果都不一样，这是正常的（盐随机），所以**验证必须用 `check_password_hash`，不能用 `==` 比字符串**。

---

## 常见坑

| 现象 | 原因 | 解决 |
|---|---|---|
| `ImportError: cannot import name 'get_env' from 'flask.helpers'` | 在跑教材原版源码 | 用本套代码，见根目录 README |
| `ModuleNotFoundError: flask_script` | 同上 | 同上，已换成 `app.cli.command` |
| `url_for('index')` 报 `BuildError` | 有蓝图后必须写 `蓝图名.函数名` | 改成 `url_for('main.index')` |
| 登录成功但刷新又变回未登录 | 没写 `user_loader`，或 `SECRET_KEY` 每次启动都变 | 补 `user_loader`；`SECRET_KEY` 固定下来 |
| 未登录访问 `/member` 报 401 而不是跳转 | 没设 `login_view` | `login_manager.login_view = 'login'` |
| 密码对但登录失败 | 库里存的是明文，验证走了哈希 | 用 `set_password()` 重新写一次 |
| `flask` 命令报 `Could not locate a Flask application` | 不在项目目录 | `cd` 进 `ch6` 再执行，或 `--app 路径` |

---

## 练习

1. 在 `config.py` 里加一个 `StagingConfig`，然后 `set FLASK_ENV=staging` 跑起来。
2. 给 `ch6` 加第三个蓝图 `blog`，挂在 `/blog` 下，提供 `/blog/` 和 `/blog/list` 两条路由。
3. 给 `ch6b` 的 `/member` 加一个“仅管理员可见”的区域（提示：用户表加 `is_admin` 字段，路由里判断 `current_user.is_admin`）。
4. 用 `flask --app app stats` 观察：加完蓝图后路由总数和分组有什么变化。
