Flask 教程：从入门到实战（华为云上机实操版）

Flask 教程：从入门到实战（华为云上机实操版）

环境 : 华为云 FlexusX ecs-60a4-0001 | Ubuntu 24.04.4 LTS | Python 3.12.3 | Flask 3.1.3

服务器 : 8vCPU / 16GiB / 可用区7 / 5Mbit/s BGP

特点: 全部代码在真实服务器上执行，输出为实机结果，非纸上谈兵

---

目录

篇章	章节	内容
入门篇	1-4	简介 → 安装 → 第一个应用 → 基本概念 → 项目结构
核心篇	5-10	路由 → 请求与响应 → 视图函数 → 模板渲染 → 静态文件 → Session与Cookie → 表单处理
进阶篇	11-16	数据库操作 → 蓝图 → 错误处理 → 中间件和扩展 → 配置管理 → 请求生命周期
实战篇	17-19	Flask Web 博客系统 → CLI命令与部署 → 测试

---

服务器架构图

+----------------------------------------------------------+
|              华为云 FlexusX ecs-60a4-0001                 |
|              (114.116.250.214)                            |
|                                                          |
|  +-------------------+     +-----------------------+     |
|  |  Ubuntu 24.04.4   |     |   Python 3.12.3       |     |
|  |  8vCPU / 16GiB    |---->|   pip 24.0            |     |
|  +-------------------+     +-----------------------+     |
|                                    |                     |
|                    +---------------+---------------+     |
|                    |                               |     |
|            +-------v-------+               +-------v--+  |
|            | Flask 3.1.3   |               | SQLite   |  |
|            | Werkzeug 3.1.8|               | (内置)   |  |
|            | Jinja2 3.1.6  |               +----------+  |
|            +-------+-------+                             |
|                    |                                     |
|        +-----------+-----------+-----------+             |
|        |           |           |           |             |
|   +----v---+ +-----v--+ +-----v--+ +-----v--+            |
|   |Flask-  | |Flask-  | |Flask-  | |Flask-  |            |
|   |SQLAlch | |Migrate | |Login   | |WTF     |            |
|   |3.1.1   | |4.1.0   | |0.6.3   | |1.3.0   |            |
|   +--------+ +--------+ +--------+ +--------+            |
|                                                          |
+----------------------------------------------------------+

---

入门篇

1. Flask 简介

Flask 是一个用 Python 编写的轻量级 Web 应用框架（Microframework）。它被称为"微框架"，因为它使用简单的核心，并通过扩展机制添加功能。

Flask 核心特性

特性	说明
轻量级	核心仅包含路由和模板引擎，不绑定 ORM、表单验证等
WSGI	基于 Werkzeug WSGI 工具库
模板	使用 Jinja2 模板引擎
路由	基于装饰器的 URL 路由系统
扩展	丰富的第三方扩展生态（SQLAlchemy、Login、WTF 等）
开发服务器	内置开发服务器和调试器
RESTful	天然适合构建 RESTful API

Flask vs Django 对比

对比项	Flask	Django
设计理念	微框架，灵活组合	全栈框架，开箱即用
ORM	无内置（常用 SQLAlchemy）	内置 Django ORM
模板	Jinja2	Django Template (类似 Jinja2)
表单	Flask-WTF (可选)	内置 Form
Admin	无内置（用 Flask-Admin）	内置 Admin 后台
认证	Flask-Login (可选)	内置 Auth 系统
路由	装饰器风格	URLconf 列表风格
学习曲线	平缓	较陡
适合场景	API/微服务/小型应用	内容管理/大型 Web 应用

Flask 技术栈

                    HTTP 请求
                       |
                       v
+--------------------------------------------------+
|              WSGI Server                          |
|  (Gunicorn / uWSGI / Werkzeug dev server)        |
+--------------------------------------------------+
                       |
                       v
+--------------------------------------------------+
|              Flask Application (app.py)          |
|                                                  |
|  +----------+   +----------+   +----------+     |
|  | Routing  |-->| View     |-->| Response |     |
|  | (Werkzeug)|  | Function |   | (Werkzeug)|    |
|  +----------+   +----------+   +----------+     |
|                       |                          |
|          +------------+------------+             |
|          |            |            |             |
|    +-----v---+  +-----v---+  +-----v----+       |
|    | Jinja2  |  |SQLAlchemy|  | Extensions|      |
|    | Template|  |  (ORM)   |  | (Login等) |      |
|    +---------+  +----------+  +-----------+      |
|                                                  |
+--------------------------------------------------+
                       |
                       v
                   HTTP 响应

---

2. Flask 安装

2.1 系统环境

$ python3 --version
Python 3.12.3

$ cat /etc/os-release | head -3
PRETTY_NAME="Ubuntu 24.04.4 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"

2.2 踩坑：Ubuntu 24.04 的 PEP 668 保护

Ubuntu 24.04 默认禁止直接使用 pip install 安装到系统 Python：

$ pip3 install flask
error: externally-managed-environment

× This environment is externally managed
╰─> See /usr/share/doc/python3.12/README.venv for more information.

解决方案（两种任选其一）：

方案	命令	适用场景
方案 A：--break-system-packages	pip3 install --break-system-packages flask	测试服务器/快速安装
方案 B：虚拟环境（推荐）	python3 -m venv venv && source venv/bin/activate	生产环境

2.3 踩坑：blinker 版本冲突

安装 Flask 时会遇到 blinker 冲突（Ubuntu 24.04 自带 blinker 1.7.0）：

ERROR: Cannot uninstall blinker 1.7.0, RECORD file not found.
Hint: The package was installed by debian.

解决方案 ：添加 --ignore-installed blinker

pip3 install --break-system-packages --ignore-installed blinker \
    flask flask-sqlalchemy flask-migrate flask-login flask-wtf

2.4 安装 email_validator（Flask-WTF 依赖）

pip3 install --break-system-packages email_validator

2.5 验证安装

$ python3 -c "
import importlib.metadata as meta
def ver(pkg):
    try: return meta.version(pkg)
    except: return 'unknown'

pkgs = ['flask','werkzeug','jinja2','flask-sqlalchemy','sqlalchemy',
        'flask-migrate','flask-login','flask-wtf','click','itsdangerous','blinker']
for p in pkgs:
    print(f'{p:25s} {ver(p)}')
"

Flask:                    3.1.3
Werkzeug:                 3.1.8
Jinja2:                   3.1.6
Flask-SQLAlchemy:         3.1.1
SQLAlchemy:               2.0.51
Flask-Migrate:            4.1.0
Flask-Login:              0.6.3
Flask-WTF:                1.3.0
Click:                    8.4.2
Itsdangerous:             2.2.0
Blinker:                  1.9.0

2.6 Flask 核心组件验证

modules = [
    'flask', 'flask.json', 'flask.testing', 'flask.templating',
    'flask.sessions', 'flask.wrappers', 'flask.blueprints',
    'flask.signals', 'flask.ctx', 'flask.config', 'flask.cli'
]
for mod in modules:
    __import__(mod)
    print(f"  [OK] {mod}")

实机输出：

  [OK] flask
  [OK] flask.json
  [OK] flask.testing
  [OK] flask.templating
  [OK] flask.sessions
  [OK] flask.wrappers
  [OK] flask.blueprints
  [OK] flask.signals
  [OK] flask.ctx
  [OK] flask.config
  [OK] flask.cli

---

3. Flask 第一个应用

3.1 最小 Flask 应用

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return 'Hello, Flask!'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=True)

3.2 使用 test_client 测试

在生产环境中我们使用 test_client() 模拟请求，无需启动真实服务器：

with app.test_client() as client:
    resp = client.get('/')
    print(f"GET / -> Status: {resp.status_code}")
    print(f"Response: {resp.data.decode()}")
    print(f"Headers: {dict(resp.headers)}")

实机输出：

GET / -> Status: 200
Response: Hello, Flask!
Headers: {'Content-Type': 'text/html; charset=utf-8', 'Content-Length': '13'}

3.3 启动开发服务器

# 方式 1: python 直接运行
python3 app.py

# 方式 2: flask CLI
export FLASK_APP=app.py
flask run --host=0.0.0.0 --port=5000 --debug

 * Serving Flask app 'app'
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5000
 * Running on http://192.168.0.238:5000

---

4. Flask 基本概念

4.1 Flask 应用对象属性

app = Flask(__name__)
app.config['DEBUG'] = True
app.config['SECRET_KEY'] = 'my-secret-key-12345'
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024  # 16MB

实机输出：

app.name: flask_batch1
app.import_name: __main__
app.root_path: /tmp
app.debug: False
app.testing: False
app.secret_key: None
app.url_map:
Map([<Rule '/static/<filename>' (OPTIONS, GET, HEAD) -> static>,
 <Rule '/' (OPTIONS, GET, HEAD) -> hello>])

配置项示例：

DEBUG: True
SECRET_KEY: my-secret-key-12345
MAX_CONTENT_LENGTH: 16777216

4.2 Flask 默认配置项

配置项	默认值	说明
DEBUG	False	调试模式（自动重载 + 错误页面）
TESTING	False	测试模式（异常直接抛出）
SECRET_KEY	None	Session 加密密钥（生产必须设置）
PERMANENT_SESSION_LIFETIME	31 days	Session 持久化过期时间
MAX_CONTENT_LENGTH	None	请求体最大字节数
PREFERRED_URL_SCHEME	http	URL 生成的默认协议
MAX_COOKIE_SIZE	4093	Cookie 最大大小
TEMPLATES_AUTO_RELOAD	None	模板自动重载
JSON_AS_ASCII	True	JSON 输出是否为 ASCII

---

5. Flask 项目结构

5.1 标准项目结构

flask_project/
├── app/                    # 应用包
│   ├── __init__.py        # 应用工厂
│   ├── views.py           # 视图函数
│   ├── models.py          # 数据模型
│   ├── api/               # API 蓝图
│   ├── static/            # 静态文件
│   │   ├── css/
│   │   │   └── style.css
│   │   └── js/
│   │       └── main.js
│   └── templates/         # Jinja2 模板
│       └── base.html
├── migrations/             # 数据库迁移
├── tests/                  # 测试
├── config.py               # 配置文件
├── run.py                  # 启动脚本
└── requirements.txt        # 依赖清单

5.2 关键文件内容

app/init.py：

from flask import Flask

app = Flask(__name__)

from app import views

config.py：

DEBUG = True
SECRET_KEY = 'dev-secret-key'
SQLALCHEMY_DATABASE_URI = 'sqlite:///app.db'
SQLALCHEMY_TRACK_MODIFICATIONS = False

run.py：

from app import app

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=True)

requirements.txt：

flask
flask-sqlalchemy
flask-migrate

---

核心篇

6. Flask 路由

6.1 基本路由

@app.route('/')
def index():
    return 'Index Page'

@app.route('/user/<username>')
def show_user(username):
    return f'User: {username}'

6.2 路由变量类型（转换器）

转换器	类名	说明	示例
string	UnicodeConverter	默认，不包含斜杠	/user/<username>
int	IntegerConverter	正整数	/post/<int:post_id>
float	FloatConverter	正浮点数	/price/<float:price>
path	PathConverter	包含斜杠的路径	/path/<path:subpath>
uuid	UUIDConverter	UUID 字符串	/item/<uuid:uid>
any	AnyConverter	匹配多个固定值	/<any(about,help):page>

6.3 多规则路由

@app.route('/hello')
@app.route('/hi')
def hello_both():
    return 'Hello or Hi!'

6.4 HTTP 方法

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        return 'POST: Login submitted'
    return 'GET: Login form'

6.5 url_for URL 构建

@app.route('/url-demo')
def url_demo():
    user_url = url_for('show_user', username='alice')
    post_url = url_for('show_post', post_id=42)
    index_url = url_for('index')
    return f'urls: user={user_url}, post={post_url}, index={index_url}'

6.6 实机测试结果

  GET  /                    -> 200 Index Page
  GET  /user/alice          -> 200 User: alice
  GET  /post/42             -> 200 Post ID: 42 (type=int)
  GET  /path/a/b/c          -> 200 Subpath: a/b/c
  GET  /hello               -> 200 Hello or Hi!
  GET  /hi                  -> 200 Hello or Hi!
  GET  /login               -> 200 GET: Login form
  POST /login               -> 200 POST: Login submitted
  GET  /url-demo            -> 200 urls: user=/user/alice, post=/post/42, index=/

6.7 URL Map

  /static/<path:filename>        GET        -> static
  /                              GET        -> index
  /user/<username>               GET        -> show_user
  /post/<int:post_id>            GET        -> show_post
  /path/<path:subpath>           GET        -> show_path
  /uuid/<uuid:uid>               GET        -> show_uuid
  /hi                            GET        -> hello_both
  /hello                         GET        -> hello_both
  /login                         GET,POST   -> login
  /url-demo                      GET        -> url_demo

---

7. Flask 请求与响应

7.1 Request 对象

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/req-demo')
def req_demo():
    info = {
        'method': request.method,        # GET/POST/PUT/DELETE
        'url': request.url,              # 完整 URL
        'base_url': request.base_url,    # 不含 query string
        'path': request.path,            # 路径部分
        'args': dict(request.args),      # URL 查询参数
        'remote_addr': request.remote_addr,  # 客户端 IP
        'host': request.host,            # 主机名
        'is_secure': request.is_secure,  # 是否 HTTPS
    }
    return jsonify(info)

实机输出：

{
  "args": {},
  "base_url": "http://localhost/req-demo",
  "headers.User-Agent": "TestClient/1.0",
  "host": "localhost",
  "is_secure": false,
  "method": "GET",
  "path": "/req-demo",
  "remote_addr": "127.0.0.1",
  "url": "http://localhost/req-demo"
}

7.2 获取请求参数

# URL 查询参数 (?name=Alice&age=25)
@app.route('/req-args')
def req_args():
    name = request.args.get('name', 'Guest')         # 带默认值
    age = request.args.get('age', type=int, default=0)  # 类型转换
    return f'name={name}, age={age} (type={type(age).__name__})'

# POST JSON
@app.route('/req-data', methods=['POST'])
def req_data():
    if request.is_json:
        data = request.get_json()
        return jsonify({'received_json': data})
    else:
        data = request.form.to_dict()
        return jsonify({'received_form': data})

实机输出：

GET /req-args?name=Alice&age=25 -> 200
Body: name=Alice, age=25 (type=int)

POST /req-data (JSON) -> 200
Body: {"received_json":{"key":"value","num":42}}

POST /req-data (Form) -> 200
Body: {"content_type":"application/x-www-form-urlencoded",
       "received_form":{"password":"secret","username":"bob"}}

7.3 Response 对象

from flask import make_response

@app.route('/resp-custom')
def resp_custom():
    resp = make_response('Custom Response', 201)
    resp.headers['X-Custom-Header'] = 'Flask-Tutorial'
    resp.headers['Content-Type'] = 'text/plain'
    resp.set_cookie('custom_cookie', 'value123', max_age=3600)
    return resp

实机输出：

GET /resp-custom -> 201
Headers: X-Custom-Header=Flask-Tutorial
Cookie: custom_cookie=value123; Expires=...; Max-Age=3600; Path=/
Body: Custom Response

7.4 JSON 响应

@app.route('/resp-json')
def resp_json():
    data = {'status': 'success', 'data': [1, 2, 3], 'count': 3}
    return jsonify(data)  # 自动设置 Content-Type: application/json

GET /resp-json -> 200
Content-Type: application/json
Body: {"count":3,"data":[1,2,3],"status":"success"}

7.5 重定向与错误

@app.route('/resp-redirect')
def resp_redirect():
    return redirect(url_for('resp_json'))  # 302 重定向

@app.route('/resp-error/<int:code>')
def resp_error(code):
    abort(code)  # 触发 HTTP 错误

GET /resp-redirect -> 302 (Location: /resp-json)
GET /resp-error/404 -> 404
GET /resp-error/500 -> 500

7.6 Request 对象属性总表

属性	类型	说明
request.method	str	HTTP 方法 (GET/POST/PUT/DELETE)
request.url	str	完整 URL
request.base_url	str	URL（不含 query string）
request.path	str	URL 路径部分
request.args	ImmutableMultiDict	URL 查询参数
request.form	ImmutableMultiDict	POST 表单数据
request.json / request.get_json()	dict	JSON 请求体
request.data	bytes	原始请求体
request.files	MultiDict	上传文件
request.headers	EnvironHeaders	请求头
request.cookies	dict	Cookie 字典
request.remote_addr	str	客户端 IP
request.host	str	主机名
request.content_type	str	Content-Type 头
request.content_length	int	Content-Length 头
request.is_json	bool	是否 JSON 请求
request.is_secure	bool	是否 HTTPS

---

8. Flask 视图函数

8.1 返回值类型

Flask 视图函数支持多种返回值类型：

返回类型	Flask 处理	状态码
str	直接作为响应体	200
dict / list	自动转 JSON	200
tuple(str, int)	(响应体, 状态码)	自定义
tuple(str, int, dict)	(响应体, 状态码, 头部)	自定义
Response 对象	直接返回	自定义
generator	流式响应	200

@app.route('/str')
def return_str():
    return 'Plain String'              # -> 200

@app.route('/dict')
def return_dict():
    return {'key': 'value', 'num': 42}  # -> 200 JSON

@app.route('/tuple')
def return_tuple():
    return 'Tuple Response', 201, {'X-Header': 'Value'}  # -> 201

@app.route('/list')
def return_list():
    return ['item1', 'item2', 'item3']  # -> 200 JSON

实机输出：

  GET  /               -> 200 Home Page
  GET  /str            -> 200 Plain String
  GET  /dict           -> 200 {"key":"value","num":42}
  GET  /tuple          -> 201 Tuple Response
  GET  /list           -> 200 ["item1","item2","item3"]

8.2 基于类的视图

View（通用类视图）

from flask.views import View

class HelloWorldView(View):
    def dispatch_request(self):
        return 'Hello from Class-Based View!'

app.add_url_rule('/cbv', view_func=HelloWorldView.as_view('helloworld'))

MethodView（RESTful 风格）

from flask.views import MethodView

class UserAPI(MethodView):
    def get(self):
        return jsonify({'action': 'GET', 'message': 'List users'})

    def post(self):
        return jsonify({'action': 'POST', 'message': 'Create user'})

app.add_url_rule('/api/users', view_func=UserAPI.as_view('users'))

实机输出：

  GET  /cbv            -> 200 Hello from Class-Based View!
  GET  /api/users      -> 200 {"action":"GET","message":"List users"}
  POST /api/users      -> 200 {"action":"POST","message":"Create user"}

---

9. Flask 模板渲染

9.1 Jinja2 基础语法

from jinja2 import Template

# 变量替换
tpl = Template('Hello {{ name }}!')
tpl.render(name='Flask')  # -> 'Hello Flask!'

# for 循环
tpl2 = Template('{% for item in items %}{{ item }} {% endfor %}')
tpl2.render(items=['a', 'b', 'c'])  # -> 'a b c '

# if/elif/else
tpl3 = Template('{% if score >= 90 %}A{% elif score >= 80 %}B{% else %}C{% endif %}')
tpl3.render(score=90)  # -> 'A'
tpl3.render(score=85)  # -> 'B'
tpl3.render(score=60)  # -> 'C'

9.2 render_template_string

from flask import render_template_string

@app.route('/tpl/<name>')
def tpl_demo(name):
    return render_template_string(
        '<h1>Hello {{ name|upper }}!</h1>\n'
        '<p>Length: {{ name|length }}</p>\n'
        '<p>Reversed: {{ name|reverse }}</p>',
        name=name
    )

# 自定义过滤器
@app.template_filter('reverse')
def reverse_filter(s):
    return s[::-1]

实机输出：

<h1>Hello FLASK!</h1>
<p>Length: 5</p>
<p>Reversed: ksalF</p>

9.3 循环与 loop 对象

@app.route('/tpl-loop')
def tpl_loop():
    return render_template_string(
        '<ul>\n'
        '{% for item in items %}\n'
        '  <li>{{ loop.index }}: {{ item }}</li>\n'
        '{% endfor %}\n'
        '</ul>',
        items=['Python', 'Flask', 'Jinja2', 'Werkzeug']
    )

实机输出：

<ul>
  <li>1: Python</li>
  <li>2: Flask</li>
  <li>3: Jinja2</li>
  <li>4: Werkzeug</li>
</ul>

9.4 macro 宏

@app.route('/tpl-macro')
def tpl_macro():
    return render_template_string(
        '{% macro greet(name, greeting="Hello") %}\n'
        '{{ greeting }}, {{ name }}!\n'
        '{% endmacro %}\n'
        '{{ greet("Alice") }}{{ greet("Bob", "Hi") }}'
    )

实机输出：

Hello, Alice!
Hi, Bob!

9.5 模板继承

from jinja2 import Environment, DictLoader

base_tpl = '''<html><head>
<title>{% block title %}Default{% endblock %}</title>
</head><body>{% block content %}{% endblock %}</body></html>'''

child_tpl = '''{% extends 'base.html' %}
{% block title %}Child Page{% endblock %}
{% block content %}<h1>Content from Child</h1>{% endblock %}'''

env = Environment(loader=DictLoader({'base.html': base_tpl, 'child.html': child_tpl}))
result = env.get_template('child.html').render()

实机输出：

<html><head><title>Child Page</title></head>
<body><h1>Content from Child</h1></body></html>

9.6 Jinja2 内置过滤器（54 个）

序号	过滤器	说明
1	abs	绝对值
2	capitalize	首字母大写
3	default / d	默认值
4	escape / e	HTML 转义
5	filesizeformat	文件大小格式化
6	first / last	第一个/最后一个元素
7	float / int	类型转换
8	join	列表拼接为字符串
9	length / count	长度
10	lower / upper	大小写转换
11	replace	字符串替换
12	reverse	反转
13	round	四舍五入
14	safe	标记为安全（不转义）
15	sort	排序
16	striptags	去除 HTML 标签
17	title	每个单词首字母大写
18	trim	去除首尾空白
19	truncate	截断
20	tojson	转 JSON
21	unique	去重
22	wordcount	单词数
...	...	共 54 个

---

10. Flask 静态文件

10.1 默认静态文件配置

app = Flask(__name__)
# 默认: static_folder='static', static_url_path='/static'

10.2 自定义静态文件目录

app = Flask(__name__,
    static_folder='/path/to/static',
    static_url_path='/static'
)

10.3 实机测试

# 创建静态文件
with open('/tmp/flask_static/style.css', 'w') as f:
    f.write('body { color: #333; }\nh1 { color: #0066cc; }')
with open('/tmp/flask_static/app.js', 'w') as f:
    f.write('console.log("Flask static file");')

实机输出：

GET /static/style.css -> 200
Content-Type: text/css; charset=utf-8
Body: body { color: #333; }
h1 { color: #0066cc; }

GET /static/app.js -> 200
Content-Type: text/javascript; charset=utf-8
Body: console.log("Flask static file");

GET /static/nonexistent.js -> 404

10.4 模板中引用静态文件

<link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
<script src="{{ url_for('static', filename='js/main.js') }}"></script>
<img src="{{ url_for('static', filename='images/logo.png') }}">

---

11. Flask Session 与 Cookie

11.1 Session 操作

from flask import session

app = Flask(__name__)
app.secret_key = 'session-test-key-12345'  # Session 必须设置 secret_key

@app.route('/set-session/<value>')
def set_session(value):
    session['data'] = value
    session['count'] = session.get('count', 0) + 1
    return f'Session set: data={value}, count={session["count"]}'

@app.route('/get-session')
def get_session():
    return jsonify({
        'data': session.get('data', '(empty)'),
        'count': session.get('count', 0),
        'all_keys': list(session.keys()),
    })

@app.route('/clear-session')
def clear_session():
    session.clear()
    return 'Session cleared'

实机输出：

--- Session 测试 ---
  Set session -> Session set: data=hello, count=1
  Get session -> {"all_keys":["count","data"],"count":1,"data":"hello"}

  Set session again -> Session set: data=world, count=2
  Get session -> {"all_keys":["count","data"],"count":2,"data":"world"}

  Clear session -> Session cleared
  Get session after clear -> {"all_keys":[],"count":0,"data":"(empty)"}

11.2 Cookie 操作

from flask import make_response

@app.route('/set-cookie')
def set_cookie():
    resp = make_response('Cookie set')
    resp.set_cookie('user', 'alice', max_age=3600, httponly=True, samesite='Lax')
    resp.set_cookie('theme', 'dark', max_age=86400)
    return resp

@app.route('/get-cookie')
def get_cookie():
    return jsonify({
        'user': request.cookies.get('user', '(none)'),
        'theme': request.cookies.get('theme', '(none)'),
        'all_cookies': dict(request.cookies),
    })

@app.route('/del-cookie')
def del_cookie():
    resp = make_response('Cookie deleted')
    resp.delete_cookie('user')
    return resp

实机输出：

--- Cookie 测试 ---
  Set cookie -> 200
  Set-Cookie headers:
    user=alice; Expires=...; Max-Age=3600; HttpOnly; Path=/; SameSite=Lax
    theme=dark; Expires=...; Max-Age=86400; Path=/

  Get cookie -> {"all_cookies":{"theme":"dark","user":"alice"},
                 "theme":"dark","user":"alice"}

  Delete cookie -> Cookie deleted
  Get cookie after delete -> {"all_cookies":{"theme":"dark"},
                               "theme":"dark","user":"(none)"}

11.3 set_cookie 参数说明

参数	类型	说明
key	str	Cookie 名称
value	str	Cookie 值
max_age	int	过期时间（秒）
expires	datetime	过期时间点
path	str	有效路径（默认 /）
domain	str	有效域名
secure	bool	仅 HTTPS 传输
httponly	bool	禁止 JavaScript 访问
samesite	str	跨站策略（Lax/Strict/None）

---

12. Flask 表单处理

12.1 安装依赖

pip3 install --break-system-packages flask-wtf email_validator

12.2 定义表单

from flask_wtf import FlaskForm
from wtforms import (StringField, IntegerField, PasswordField,
                     SubmitField, SelectField, BooleanField, TextAreaField)
from wtforms.validators import DataRequired, Length, Email, NumberRange, EqualTo

class RegistrationForm(FlaskForm):
    username = StringField('用户名', validators=[DataRequired(), Length(min=3, max=20)])
    email = StringField('邮箱', validators=[DataRequired(), Email()])
    password = PasswordField('密码', validators=[DataRequired(), Length(min=6)])
    confirm = PasswordField('确认密码', validators=[DataRequired(), EqualTo('password')])
    age = IntegerField('年龄', validators=[NumberRange(min=1, max=150)])
    gender = SelectField('性别', choices=[('M', '男'), ('F', '女'), ('O', '其他')])
    agree = BooleanField('同意条款', validators=[DataRequired()])
    bio = TextAreaField('简介')
    submit = SubmitField('注册')

12.3 表单验证成功

@app7.route('/register', methods=['GET', 'POST'])
def register():
    form = RegistrationForm()
    if form.validate_on_submit():
        return jsonify({
            'status': 'success',
            'data': {
                'username': form.username.data,
                'email': form.email.data,
                'age': form.age.data,
                'gender': form.gender.data,
                'bio': form.bio.data,
            }
        })
    else:
        return jsonify({
            'status': 'error',
            'errors': {field: [str(e) for e in errors]
                      for field, errors in form.errors.items()}
        }), 400

实机输出（验证成功）：

{
  "status": "success",
  "data": {
    "age": 25,
    "bio": "Hello, I am Alice",
    "email": "alice@example.com",
    "gender": "F",
    "username": "alice"
  }
}

12.4 表单验证失败

实机输出（验证失败）：

Status: 400
    age: ['Number must be between 1 and 150.']
    agree: ['This field is required.']
    confirm: ['Field must be equal to password.']
    email: ['Invalid email address.']
    password: ['Field must be at least 6 characters long.']
    username: ['Field must be between 3 and 20 characters long.']

12.5 WTForms 字段类型

字段类型	说明	HTML 控件
StringField	文本输入	<input type="text">
PasswordField	密码输入	<input type="password">
IntegerField	整数输入	<input type="number">
FloatField	浮点输入	<input type="number">
BooleanField	复选框	<input type="checkbox">
SelectField	下拉选择	<select>
TextAreaField	多行文本	<textarea>
SubmitField	提交按钮	<input type="submit">
FileField	文件上传	<input type="file">
DateField	日期	<input type="date">
HiddenField	隐藏字段	<input type="hidden">

12.6 WTForms 验证器

验证器	说明
DataRequired	必填
Length(min, max)	长度范围
Email()	邮箱格式（需 email_validator）
NumberRange(min, max)	数值范围
EqualTo(field)	等于另一字段
URL()	URL 格式
Regexp(pattern)	正则匹配
Optional()	可选（空值跳过验证）
InputRequired	输入必填（与 DataRequired 不同）
AnyOf(values)	值在列表中
NoneOf(values)	值不在列表中

---

进阶篇

13. Flask 数据库操作

13.1 SQLAlchemy 配置

from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///blog.db'
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
db = SQLAlchemy(app)

13.2 定义模型

class User(db.Model):
    __tablename__ = 'users'
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    age = db.Column(db.Integer, default=0)
    created_at = db.Column(db.DateTime, server_default=db.func.now())

    # 一对多关系
    posts = db.relationship('Post', backref='author', lazy=True)

class Post(db.Model):
    __tablename__ = 'posts'
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(200), nullable=False)
    content = db.Column(db.Text, default='')
    user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=False)

13.3 常用列类型

类型	Python 类型	SQL 类型	说明
Integer	int	INTEGER	整数
String(n)	str	VARCHAR(n)	定长字符串
Text	str	TEXT	长文本
Float	float	FLOAT	浮点数
Boolean	bool	BOOLEAN	布尔
DateTime	datetime	DATETIME	日期时间
Date	date	DATE	日期
Time	time	TIME	时间
Numeric	Decimal	NUMERIC	高精度小数
LargeBinary	bytes	BLOB	二进制
JSON	dict/list	JSON	JSON 数据

13.4 常用列参数

参数	说明
primary_key=True	主键
unique=True	唯一约束
nullable=False	不允许 NULL
default=value	默认值
server_default=text	数据库默认值
index=True	创建索引
onupdate=func	更新时触发

13.5 CRUD 操作

Create（插入）

# 单条插入
user1 = User(username='alice', email='alice@example.com', age=25)
db.session.add(user1)
db.session.commit()

# 批量插入
users = [User(username=f'user{i}', email=f'user{i}@test.com', age=20+i) for i in range(4, 11)]
db.session.add_all(users)
db.session.commit()

实机输出：

插入 3 个用户: alice(1), bob(2), charlie(3)
批量插入 7 个用户: user4~user10

Read（查询）

# 查询所有
all_users = User.query.all()

# 按主键查询（SQLAlchemy 2.0 推荐用 db.session.get）
u1 = db.session.get(User, 1)

# filter_by (简单等值查询)
alice = User.query.filter_by(username='alice').first()

# filter (更灵活的条件查询)
adults = User.query.filter(User.age >= 25).all()

# 排序 + 限制
top3 = User.query.order_by(User.age.desc()).limit(3).all()

# like 查询
users = User.query.filter(User.username.like('user%')).all()

# in_ 查询
users = User.query.filter(User.username.in_(['alice', 'bob'])).all()

实机输出：

User.query.all(): 10 条记录
filter(User.age >= 25): 9 条
  1: alice (age=25)
  2: bob (age=30)
  3: charlie (age=28)
  ...
order_by(age.desc()).limit(3):
  2: bob (age=30)
  10: user10 (age=30)
  9: user9 (age=29)

count: 10, avg_age: 27.2, max_age: 30, min_age: 24
filter(username.like('user%')): 7 条
filter(username.in_(['alice','bob','charlie'])): 3 条

聚合查询

from sqlalchemy import func

count = db.session.query(func.count(User.id)).scalar()
avg_age = db.session.query(func.avg(User.age)).scalar()
max_age = db.session.query(func.max(User.age)).scalar()
min_age = db.session.query(func.min(User.age)).scalar()

count: 10, avg_age: 27.2, max_age: 30, min_age: 24

Update（更新）

# 单条更新
alice = User.query.filter_by(username='alice').first()
alice.age = 26
alice.email = 'alice_new@example.com'
db.session.commit()

# 批量更新
updated = User.query.filter(User.age < 25).update({'age': 25})
db.session.commit()

更新前: alice age=25
更新后: alice age=26 email=alice_new@example.com
批量更新 age<25 -> 25: 影响 1 行

Delete（删除）

charlie = User.query.filter_by(username='charlie').first()
db.session.delete(charlie)
db.session.commit()

删除: <User charlie>
删除后剩余: 9 条

13.6 关联查询

# 一对多：通过 relationship 访问
alice = db.session.get(User, 1)
for p in alice.posts:
    print(f"[{p.id}] {p.title}")

# JOIN 查询
results = db.session.query(User.username, Post.title).join(Post).all()

实机输出：

alice 的文章:
  [1] Flask Tutorial
  [2] Python Tips
bob 的文章:
  [3] Web Dev

JOIN 查询 (User.username, Post.title):
  alice: Flask Tutorial
  alice: Python Tips
  bob: Web Dev

13.7 分页

page = User.query.paginate(page=1, per_page=5, error_out=False)

print(f"第1页: {len(page.items)} 条")
print(f"总页数: {page.pages}, 总记录: {page.total}")
print(f"has_next: {page.has_next}, has_prev: {page.has_prev}")

实机输出：

第1页 (每页5条): 5 条
  1: alice
  2: bob
  4: user4
  5: user5
  6: user6
总页数: 2, 总记录: 9
has_next: True, has_prev: False

第2页: 4 条
  7: user7
  8: user8
  9: user9
  10: user10

13.8 查询方法速查表

方法	说明	返回
.all()	返回所有结果	list
.first()	返回第一条	Model / None
.get(id)	按主键查询（已弃用，用 db.session.get）	Model / None
.one()	返回唯一一条（无结果抛异常）	Model
.one_or_none()	返回唯一一条或 None	Model / None
.count()	计数	int
.filter(*conditions)	条件过滤	Query
.filter_by(**kwargs)	等值过滤	Query
.order_by(column)	排序	Query
.limit(n)	限制数量	Query
.offset(n)	跳过数量	Query
.paginate(page, per_page)	分页	Pagination
.join(Target)	表连接	Query
.distinct()	去重	Query
.group_by(column)	分组	Query
.having(condition)	分组后过滤	Query

---

14. Flask 蓝图（Blueprint）

14.1 蓝图概念

蓝图（Blueprint）用于将 Flask 应用拆分为多个模块，适合大型应用的组织。

Flask App (主应用)
  |
  +-- Blueprint: api (URL前缀 /api)
  |     |-- /api/users
  |     |-- /api/posts
  |     +-- /api/health
  |
  +-- Blueprint: admin (URL前缀 /admin)
  |     |-- /admin/
  |     |-- /admin/users
  |     +-- /admin/settings
  |
  +-- Blueprint: auth (URL前缀 /auth)
        |-- /auth/login
        +-- /auth/register

14.2 创建和注册蓝图

from flask import Blueprint, jsonify

# 创建蓝图
api_bp = Blueprint('api', __name__, url_prefix='/api')
admin_bp = Blueprint('admin', __name__, url_prefix='/admin')

@api_bp.route('/users')
def api_users():
    return jsonify({'users': ['alice', 'bob', 'charlie']})

@api_bp.route('/health')
def health():
    return jsonify({'status': 'ok', 'service': 'api'})

@admin_bp.route('/')
def admin_index():
    return 'Admin Dashboard'

# 注册蓝图到应用
app = Flask(__name__)
app.register_blueprint(api_bp)
app.register_blueprint(admin_bp)

14.3 实机测试

--- API 蓝图 ---
  GET /api/users -> 200 {"users":["alice","bob","charlie"]}
  GET /api/posts -> 200 {"posts":[{"id":1,"title":"Hello"},{"id":2,"title":"World"}]}
  GET /api/health -> 200 {"service":"api","status":"ok"}

--- Admin 蓝图 ---
  GET /admin/ -> 200 Admin Dashboard
  GET /admin/users -> 200 Admin: User Management
  GET /admin/settings -> 200 Admin: Settings

14.4 蓝图 URL Map

  /api/users                GET      -> api.api_users
  /api/posts                GET      -> api.api_posts
  /api/health               GET      -> api.health
  /admin/                   GET      -> admin.admin_index
  /admin/users              GET      -> admin.admin_users
  /admin/settings           GET      -> admin.admin_settings

14.5 蓝图参数

参数	说明
name	蓝图名称（用于 url_for 前缀）
import_name	导入名（通常用 __name__）
url_prefix	URL 前缀
subdomain	子域名
template_folder	模板目录
static_folder	静态文件目录
url_defaults	默认 URL 值

---

15. Flask 错误处理

15.1 自定义错误页面

@app.errorhandler(404)
def not_found(error):
    return jsonify({'error': 'Not Found', 'code': 404,
                    'message': 'The requested URL was not found.'}), 404

@app.errorhandler(500)
def server_error(error):
    return jsonify({'error': 'Internal Server Error', 'code': 500,
                    'message': 'Something went wrong.'}), 500

@app.errorhandler(403)
def forbidden(error):
    return jsonify({'error': 'Forbidden', 'code': 403,
                    'message': 'You do not have permission.'}), 403

15.2 自定义异常

class APIError(Exception):
    def __init__(self, message, status_code=400, payload=None):
        super().__init__()
        self.message = message
        self.status_code = status_code
        self.payload = payload

    def to_dict(self):
        rv = dict(self.payload or ())
        rv['error'] = self.message
        rv['code'] = self.status_code
        return rv

@app.errorhandler(APIError)
def handle_api_error(error):
    response = jsonify(error.to_dict())
    response.status_code = error.status_code
    return response

@app.route('/users/<int:user_id>')
def get_user(user_id):
    if user_id < 1:
        raise APIError('user_id must be positive', status_code=400)
    if user_id > 100:
        raise APIError('User not found', status_code=404)
    return jsonify({'user_id': user_id, 'name': f'User{user_id}'})

15.3 实机测试

  GET /trigger-404              -> 404 {"code":404,"error":"Not Found",...}
  GET /trigger-403              -> 403 {"code":403,"error":"Forbidden",...}
  GET /trigger-api-error        -> 422 {"code":422,"error":"Invalid parameter..."}
  GET /users/0                  -> 400 {"code":400,"error":"user_id must be positive"}
  GET /users/200                -> 404 {"code":404,"error":"User not found"}
  GET /users/5                  -> 200 {"name":"User5","user_id":5}
  GET /nonexistent              -> 404 {"code":404,"error":"Not Found",...}

15.4 常用 HTTP 错误码

状态码	名称	说明
400	Bad Request	请求参数错误
401	Unauthorized	未认证
403	Forbidden	无权限
404	Not Found	资源不存在
405	Method Not Allowed	方法不允许
409	Conflict	冲突
422	Unprocessable Entity	验证失败
429	Too Many Requests	请求过多
500	Internal Server Error	服务器内部错误
502	Bad Gateway	网关错误
503	Service Unavailable	服务不可用

---

16. Flask 中间件和扩展

16.1 请求钩子

Flask 提供了 4 种请求钩子（类似中间件）：

钩子	执行时机	用途
before_request	每次请求前	认证检查、初始化变量
before_first_request	第一个请求前（Flask 3.x 已移除）	初始化操作
after_request	每次请求后（无异常时）	添加响应头、记录日志
teardown_request	请求结束（无论是否异常）	清理资源
teardown_appcontext	应用上下文结束	清理应用级资源

import time
from flask import g

@app.before_request
def before_req():
    g.start_time = time.time()
    g.request_id = f'req-{int(time.time() * 1000)}'

@app.after_request
def after_req(response):
    duration = time.time() - g.start_time
    response.headers['X-Response-Time'] = f'{duration:.4f}s'
    response.headers['X-Request-ID'] = g.request_id
    return response

@app.teardown_request
def teardown_req(exception):
    if exception:
        print(f"  [teardown_request] exception={exception}")

16.2 实机输出

--- 请求 1: GET / ---
  [before_request] request_id=req-1782540092480, path=/
  [after_request] status=200, time=0.0000s
  [teardown_request] clean up
  Response: 200 Home with middleware
  X-Response-Time: 0.0000s
  X-Request-ID: req-1782540092480

--- 请求 2: GET /slow ---
  [before_request] request_id=req-1782540092481, path=/slow
  [after_request] status=200, time=0.1001s
  [teardown_request] clean up
  Response: 200 Slow response
  X-Response-Time: 0.1001s

16.3 WSGI 中间件

class TimingMiddleware:
    def __init__(self, app):
        self.app = app

    def __call__(self, environ, start_response):
        start = time.time()

        def custom_start_response(status, headers, exc_info=None):
            duration = time.time() - start
            headers.append(('X-Timing', f'{duration:.6f}'))
            return start_response(status, headers, exc_info)

        return self.app(environ, custom_start_response)

app.wsgi_app = TimingMiddleware(app.wsgi_app)

GET / -> 200
X-Timing header: 0.000085

16.4 常用 Flask 扩展

扩展	说明	安装状态
Flask-SQLAlchemy	数据库 ORM	已安装
Flask-Migrate	数据库迁移	已安装
Flask-Login	用户认证	已安装
Flask-WTF	表单处理	已安装
Flask-Mail	邮件发送	未安装
Flask-Caching	缓存	未安装
Flask-RESTful	REST API	未安装
Flask-CORS	跨域资源共享	未安装
Flask-Limiter	速率限制	未安装
Flask-Admin	后台管理	未安装

---

17. Flask 配置管理

17.1 配置方式对比

方式	命令	适用场景
直接配置	app.config['KEY'] = value	简单场景
from_object	app.config.from_object(ConfigClass)	多环境配置
from_pyfile	app.config.from_pyfile('config.py')	独立配置文件
from_envvar	app.config.from_envvar('APP_SETTINGS')	环境变量指定文件
from_mapping	app.config.from_mapping(...)	字典配置
from_json	app.config.from_json('config.json')	JSON 配置

17.2 多环境配置

class DevelopmentConfig:
    DEBUG = True
    SECRET_KEY = 'dev-secret'
    DATABASE_URI = 'sqlite:///dev.db'
    TESTING = False

class ProductionConfig:
    DEBUG = False
    SECRET_KEY = 'prod-secret-key-xxx'
    DATABASE_URI = 'postgresql://user:pass@localhost/prod'
    TESTING = False

class TestingConfig:
    DEBUG = False
    SECRET_KEY = 'test-secret'
    DATABASE_URI = 'sqlite:///:memory:'
    TESTING = True

# 根据环境变量选择配置
config_map = {
    'development': DevelopmentConfig,
    'production': ProductionConfig,
    'testing': TestingConfig,
}

env = os.environ.get('FLASK_ENV', 'development')
app.config.from_object(config_map[env])

实机输出：

[Development]
  DEBUG: True
  SECRET_KEY: dev-secret
  DATABASE_URI: sqlite:///dev.db
  TESTING: False

[Production]
  DEBUG: False
  SECRET_KEY: prod-secret-key-xxx
  DATABASE_URI: postgresql://user:pass@localhost/prod

[Testing]
  DEBUG: False
  TESTING: True
  DATABASE_URI: sqlite:///:memory:

17.3 from_mapping（字典配置）

app.config.from_mapping(
    CUSTOM_KEY='custom-value',
    API_VERSION='v1',
    MAX_ITEMS=100,
)

17.4 from_pyfile（文件配置）

# config.py
DEBUG = False
SECRET_KEY = "from-file-key"
DB_HOST = "localhost"
DB_PORT = 5432

# 加载
app.config.from_pyfile('config.py')

---

18. Flask 请求生命周期

18.1 生命周期流程图

  Client Request
       |
       v
  +-------------------+
  | WSGI Server       |  (Gunicorn / uWSGI / Werkzeug)
  +-------------------+
       |
       v
  +-------------------+
  | Flask.wsgi_app()  |  进入 Flask 应用
  +-------------------+
       |
       v
  +-------------------+
  | RequestContext    |  创建请求上下文
  +-------------------+
       |
       v
  +-------------------+
  | before_request    |  1. 请求前钩子 (可多个)
  +-------------------+
       |
       v
  +-------------------+
  | URL Routing       |  2. URL 匹配 -> 视图函数
  +-------------------+
       |
       v
  +-------------------+
  | View Function     |  3. 执行视图函数
  +-------------------+
       |
       v
  +-------------------+
  | Response Object   |  4. 构建响应
  +-------------------+
       |
       v
  +-------------------+
  | after_request     |  5. 响应后钩子 (可多个)
  +-------------------+
       |
       v
  +-------------------+
  | teardown_request  |  6. 请求结束清理
  +-------------------+
       |
       v
  +-------------------+
  |teardown_appcontext| 7. 应用上下文清理
  +-------------------+
       |
       v
  Client Response

18.2 实机验证

lifecycle_log = []

@app.before_request
def lifecycle_before():
    lifecycle_log.append(f'1. before_request: {request.method} {request.path}')

@app.url_value_preprocessor
def lifecycle_url_value(endpoint, values):
    lifecycle_log.append(f'2. url_value_preprocessor: endpoint={endpoint}')

@app.route('/')
def lifecycle_home():
    lifecycle_log.append('3. view_function: processing request')
    return 'OK'

@app.after_request
def lifecycle_after(response):
    lifecycle_log.append(f'4. after_request: status={response.status_code}')
    return response

@app.teardown_request
def lifecycle_teardown(exception):
    lifecycle_log.append(f'5. teardown_request: exception={exception}')

@app.teardown_appcontext
def lifecycle_teardown_ctx(exception):
    lifecycle_log.append(f'6. teardown_appcontext: exception={exception}')

实机输出：

请求生命周期执行顺序:
  2. url_value_preprocessor: endpoint=lifecycle_home
  1. before_request: GET /
  3. view_function: processing request
  4. after_request: status=200
  5. teardown_request: exception=None
  6. teardown_appcontext: exception=None

---

实战篇

19. 实战项目：Flask Web 博客系统

19.1 项目架构

+--------------------------------------------------+
|              Flask Blog System                    |
|                                                  |
|  +-------------------+                           |
|  |    Routes         |                           |
|  |  / (首页)         |                           |
|  |  /posts (列表)    |                           |
|  |  /post/<id> (详情)|                           |
|  |  /login (登录)    |                           |
|  |  /register (注册) |                           |
|  |  /post/new (写文章)|                           |
|  |  /favorites (收藏)|                           |
|  |  /admin (后台)    |                           |
|  +-------------------+                           |
|          |                                       |
|  +-------v-------+       +-------------------+  |
|  |   Models      |       |   Forms           |  |
|  |  User         |       |  RegistrationForm |  |
|  |  Post         |       |  LoginForm        |  |
|  |  favorites    |       |  PostForm         |  |
|  |  (M2M关联)    |       |                   |  |
|  +-------+-------+       +-------------------+  |
|          |                                       |
|  +-------v-------+       +-------------------+  |
|  |  SQLAlchemy   |       |  Flask-Login      |  |
|  |  (SQLite)     |       |  (用户认证)        |  |
|  +---------------+       +-------------------+  |
|                                                  |
|  +-------------------+   +-------------------+  |
|  | Jinja2 Templates  |   | Flask-WTF         |  |
|  | base.html         |   | (CSRF保护)        |  |
|  | index.html        |   |                   |  |
|  | posts.html        |   |                   |  |
|  | post_detail.html  |   |                   |  |
|  | login.html        |   |                   |  |
|  | admin.html        |   |                   |  |
|  +-------------------+   +-------------------+  |
+--------------------------------------------------+

19.2 数据模型

# 用户收藏关联表（多对多）
favorites = db.Table('favorites',
    db.Column('user_id', db.Integer, db.ForeignKey('users.id'), primary_key=True),
    db.Column('post_id', db.Integer, db.ForeignKey('posts.id'), primary_key=True)
)

class User(UserMixin, db.Model):
    __tablename__ = 'users'
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    password = db.Column(db.String(200), nullable=False)
    is_admin = db.Column(db.Boolean, default=False)
    created_at = db.Column(db.DateTime, server_default=db.func.now())

    posts = db.relationship('Post', backref='author', lazy=True)
    favorite_posts = db.relationship('Post', secondary=favorites, backref='favorited_by')

class Post(db.Model):
    __tablename__ = 'posts'
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(200), nullable=False)
    content = db.Column(db.Text, nullable=False)
    category = db.Column(db.String(50), default='未分类')
    views = db.Column(db.Integer, default=0)
    is_published = db.Column(db.Boolean, default=True)
    user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=False)
    created_at = db.Column(db.DateTime, server_default=db.func.now())
    updated_at = db.Column(db.DateTime, server_default=db.func.now(), onupdate=db.func.now())

19.3 表单定义

class RegistrationForm(FlaskForm):
    username = StringField('用户名', validators=[DataRequired(), Length(min=3, max=20)])
    email = StringField('邮箱', validators=[DataRequired(), Email()])
    password = PasswordField('密码', validators=[DataRequired(), Length(min=6)])
    confirm = PasswordField('确认密码', validators=[DataRequired(), EqualTo('password')])
    submit = SubmitField('注册')

class LoginForm(FlaskForm):
    username = StringField('用户名', validators=[DataRequired()])
    password = PasswordField('密码', validators=[DataRequired()])
    remember = BooleanField('记住我')
    submit = SubmitField('登录')

class PostForm(FlaskForm):
    title = StringField('标题', validators=[DataRequired(), Length(max=200)])
    content = TextAreaField('内容', validators=[DataRequired()])
    category = StringField('分类', validators=[DataRequired()])
    submit = SubmitField('发布')

19.4 视图函数

# 首页
@app.route('/')
def index():
    total_posts = Post.query.count()
    total_users = User.query.count()
    latest_posts = Post.query.filter_by(is_published=True)\
        .order_by(Post.created_at.desc()).limit(3).all()
    return render_template_string(INDEX_TEMPLATE,
        total_posts=total_posts, total_users=total_users,
        latest_posts=latest_posts)

# 文章列表（分页 + 搜索 + 分类过滤）
@app.route('/posts')
def posts_list():
    page = request.args.get('page', 1, type=int)
    per_page = app.config['POSTS_PER_PAGE']
    query = request.args.get('q', '')
    selected_category = request.args.get('category', '')

    q = Post.query.filter_by(is_published=True)
    if query:
        q = q.filter(Post.title.contains(query) | Post.content.contains(query))
    if selected_category:
        q = q.filter_by(category=selected_category)

    pagination = q.order_by(Post.created_at.desc())\
        .paginate(page=page, per_page=per_page, error_out=False)
    categories = [c[0] for c in db.session.query(Post.category).distinct().all()]

    return render_template_string(POSTS_LIST_TEMPLATE,
        posts=pagination.items, pagination=pagination,
        total=pagination.total, query=query,
        categories=categories, selected_category=selected_category)

# 文章详情（自动增加浏览量）
@app.route('/post/<int:post_id>')
def post_detail(post_id):
    post = db.session.get(Post, post_id) or abort(404)
    post.views += 1
    db.session.commit()
    return render_template_string(POST_DETAIL_TEMPLATE, post=post)

# 用户登录
@app.route('/login', methods=['GET', 'POST'])
def login():
    form = LoginForm()
    if form.validate_on_submit():
        user = User.query.filter_by(username=form.username.data).first()
        if user and user.password == form.password.data:
            login_user(user, remember=form.remember.data)
            flash('登录成功！')
            return redirect(url_for('index'))
        flash('用户名或密码错误')
    return render_template_string(LOGIN_TEMPLATE, form=form)

# 写文章（需登录）
@app.route('/post/new', methods=['GET', 'POST'])
@login_required
def create_post():
    form = PostForm()
    if form.validate_on_submit():
        post = Post(
            title=form.title.data,
            content=form.content.data,
            category=form.category.data,
            author=current_user
        )
        db.session.add(post)
        db.session.commit()
        flash('文章发布成功！')
        return redirect(url_for('post_detail', post_id=post.id))
    return render_template_string(CREATE_POST_TEMPLATE, form=form)

# 收藏/取消收藏
@app.route('/post/<int:post_id>/favorite', methods=['POST'])
@login_required
def toggle_favorite(post_id):
    post = db.session.get(Post, post_id) or abort(404)
    if post in current_user.favorite_posts:
        current_user.favorite_posts.remove(post)
        flash('已取消收藏')
    else:
        current_user.favorite_posts.append(post)
        flash('已添加收藏')
    db.session.commit()
    return redirect(url_for('post_detail', post_id=post_id))

# 管理员后台
@app.route('/admin')
@login_required
def admin_dashboard():
    if not current_user.is_admin:
        abort(403)
    stats = {
        'users': User.query.count(),
        'posts': Post.query.count(),
        'published': Post.query.filter_by(is_published=True).count(),
        'total_views': db.session.query(db.func.sum(Post.views)).scalar() or 0,
    }
    return render_template_string(ADMIN_TEMPLATE, stats=stats,
        users=User.query.all(), all_posts=Post.query.all())

19.5 路由表

Endpoint	Methods	URL	说明	权限
index	GET	/	首页	公开
posts_list	GET	/posts	文章列表（搜索+分页）	公开
post_detail	GET	/post/<id>	文章详情	公开
login	GET,POST	/login	登录	公开
register	GET,POST	/register	注册	公开
logout	GET	/logout	退出	登录
create_post	GET,POST	/post/new	写文章	登录
toggle_favorite	POST	/post/<id>/favorite	收藏/取消	登录
favorites_list	GET	/favorites	我的收藏	登录
admin_dashboard	GET	/admin	后台管理	管理员

19.6 功能测试结果

首页

GET / -> 200
包含 'Flask Blog 首页': True
包含 '总文章数: 9': True
包含 '最新文章': True

文章列表（分页）

GET /posts -> 200
'共 9 篇文章': True
'第 1 / 3 页': True

GET /posts?page=2 -> 200
'第 2 / 3 页': True

关键词搜索

GET /posts?q=Flask -> 200
包含 Flask 相关: True

GET /posts?category=数据库 -> 200
'SQLAlchemy' in html: True

文章详情

GET /post/1 -> 200
'Flask 入门指南' in html: True
'作者: alice' in html: True
再次访问 /post/1 -> 200 (浏览量+1)

用户注册

POST /register -> 302 (redirect to /login)

用户登录

POST /login (alice) -> 302 (redirect to /)
首页显示 '退出 (alice)': True

写文章

GET /post/new (已登录) -> 200
POST /post/new -> 302 (redirect)

收藏功能

POST /post/1/favorite -> 302 (收藏)
GET /favorites -> 200
'Flask 入门指南' in favorites: True

POST /post/1/favorite again -> 302 (取消收藏)
'暂无收藏': True

未登录访问限制

GET /post/new (未登录) -> 302 (redirect to login)
GET /favorites (未登录) -> 302 (redirect to login)

管理员后台

GET /admin (admin) -> 200
'后台管理' in html: True
'总用户数: 4' in html: True
'总文章数: 10' in html: True

GET /admin (普通用户) -> 403 (Forbidden)

404 错误

GET /post/999 -> 404

---

20. Flask CLI 命令与部署

20.1 Flask CLI 命令

命令	说明
flask run	启动开发服务器
flask run --host=0.0.0.0	监听所有网络接口
flask run --port=8080	指定端口
flask run --debug	调试模式（自动重载）
flask routes	列出所有路由
flask shell	进入交互式 Python Shell
flask db init	初始化数据库迁移
flask db migrate	生成迁移脚本
flask db upgrade	执行迁移
flask db downgrade	回滚迁移
flask --app myapp run	指定应用

20.2 Flask-Migrate 数据库迁移

# 1. 首次初始化
flask db init
# 创建 migrations/ 目录结构:
# migrations/
#   versions/       # 迁移脚本
#   alembic.ini     # Alembic 配置
#   env.py          # 环境配置
#   script.py.mako  # 迁移脚本模板

# 2. 修改模型后生成迁移
flask db migrate -m "add user table"

# 3. 应用迁移到数据库
flask db upgrade

# 4. 回滚到上一版本
flask db downgrade

# 5. 查看迁移历史
flask db history

# 6. 查看当前版本
flask db current

20.3 部署方式

方式 1：开发服务器（不推荐生产）

flask run --host=0.0.0.0 --port=5000 --debug

方式 2：Gunicorn（推荐）

pip install gunicorn

# 基本启动
gunicorn -w 4 -b 0.0.0.0:5000 "app:app"

# 生产级配置
gunicorn -w 4 \
  -b 0.0.0.0:5000 \
  --timeout 120 \
  --access-logfile - \
  --error-logfile - \
  "app:app"

参数	说明
-w 4	4 个 worker 进程
-b 0.0.0.0:5000	绑定地址和端口
--timeout 120	请求超时时间（秒）
--access-logfile -	输出访问日志到 stdout
--error-logfile -	输出错误日志到 stderr
--workers	worker 数量（建议 2*CPU+1）
--threads	每个 worker 的线程数
--preload	预加载应用（节省内存）

方式 3：uWSGI

pip install uwsgi
uwsgi --http :5000 --wsgi-file app.py --callable app --processes 4

方式 4：Docker 部署

# Dockerfile
FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 5000

CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5000", "app:app"]

# 构建镜像
docker build -t flask-blog .

# 运行容器
docker run -d -p 5000:5000 --name blog flask-blog

# 查看日志
docker logs -f blog

# 进入容器
docker exec -it blog bash

方式 5：Nginx + Gunicorn 反向代理

# /etc/nginx/sites-enabled/flask_blog
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 静态文件直接由 Nginx 处理
    location /static {
        alias /app/static;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # 上传文件大小限制
    client_max_body_size 16M;
}

# 启动 Gunicorn
gunicorn -w 4 -b 127.0.0.1:5000 "app:app" --daemon

# 重载 Nginx
nginx -s reload

20.4 生产部署架构图

                    Internet
                       |
                       v
              +----------------+
              |   Load Balancer|  (华为云 ELB / Nginx)
              +----------------+
                       |
          +------------+------------+
          |            |            |
    +-----v---+  +-----v---+  +-----v---+
    | Nginx 1 |  | Nginx 2 |  | Nginx 3 |
    +-----+---+  +-----+---+  +-----+---+
          |            |            |
          +------------+------------+
                       |
          +------------+------------+
          |            |            |
    +-----v---+  +-----v---+  +-----v---+
    |Gunicorn |  |Gunicorn |  |Gunicorn |
    |Worker 1 |  |Worker 2 |  |Worker 3 |
    | (Flask) |  | (Flask) |  | (Flask) |
    +---------+  +---------+  +---------+
          |            |            |
          +------------+------------+
                       |
              +----------------+
              |   Database     |  (PostgreSQL / MySQL)
              +----------------+
                       |
              +----------------+
              |    Redis       |  (缓存 / Session)
              +----------------+

---

21. Flask 测试

21.1 测试框架

import unittest

class BlogTestCase(unittest.TestCase):
    def setUp(self):
        app.config['TESTING'] = True
        app.config['WTF_CSRF_ENABLED'] = False
        self.client = app.test_client()

        with app.app_context():
            db.create_all()
            # 创建测试数据
            user = User(username='testuser', email='test@test.com', password='test123')
            admin = User(username='testadmin', email='admin@test.com',
                        password='admin123', is_admin=True)
            db.session.add_all([user, admin])
            post = Post(title='Test Post', content='Test content',
                       category='Test', author=user)
            db.session.add(post)
            db.session.commit()

    def tearDown(self):
        with app.app_context():
            db.session.remove()
            db.drop_all()

    def test_index(self):
        resp = self.client.get('/')
        self.assertEqual(resp.status_code, 200)

    def test_post_not_found(self):
        resp = self.client.get('/post/999')
        self.assertEqual(resp.status_code, 404)

    def test_login_required(self):
        resp = self.client.get('/post/new')
        self.assertEqual(resp.status_code, 302)
        self.assertIn('/login', resp.headers.get('Location', ''))

    def test_admin_access_denied(self):
        self.client.post('/login', data={'username': 'testuser', 'password': 'test123'})
        resp = self.client.get('/admin')
        self.assertEqual(resp.status_code, 403)

    def test_admin_access_granted(self):
        self.client.post('/login', data={'username': 'testadmin', 'password': 'admin123'})
        resp = self.client.get('/admin')
        self.assertEqual(resp.status_code, 200)

21.2 测试结果

test_admin_access_denied ... ok
test_admin_access_granted ... ok
test_index ... ok
test_login ... ok
test_login_required ... ok
test_post_detail ... ok
test_post_not_found ... ok
test_posts_list ... ok
test_search ... ok

----------------------------------------------------------------------
Ran 9 tests in 0.238s

OK

测试结果: 9 个测试, 0 失败, 0 错误
测试状态: 全部通过 ✓

21.3 pytest 风格测试

import pytest

@pytest.fixture
def client():
    app.config['TESTING'] = True
    with app.test_client() as client:
        with app.app_context():
            db.create_all()
        yield client
        with app.app_context():
            db.drop_all()

def test_index(client):
    resp = client.get('/')
    assert resp.status_code == 200

def test_post_not_found(client):
    resp = client.get('/post/999')
    assert resp.status_code == 404

---

踩坑记录

踩坑 1：Ubuntu 24.04 PEP 668 保护

现象：

error: externally-managed-environment
× This environment is externally managed

解决：

pip3 install --break-system-packages flask
# 或使用虚拟环境
python3 -m venv venv && source venv/bin/activate

踩坑 2：blinker 版本冲突

现象：

ERROR: Cannot uninstall blinker 1.7.0, RECORD file not found.
Hint: The package was installed by debian.

解决：

pip3 install --break-system-packages --ignore-installed blinker flask

踩坑 3：email_validator 缺失

现象：

Exception: Install 'email_validator' for email validation support.

解决：

pip3 install --break-system-packages email_validator

踩坑 4：SQLAlchemy 2.0 Query.get() 弃用

现象：

LegacyAPIWarning: The Query.get() method is considered legacy as of
the 1.x series of SQLAlchemy and becomes a legacy construct in 2.0.
The method is now available as Session.get()

解决：

# 旧（弃用）
user = User.query.get(1)

# 新（推荐）
user = db.session.get(User, 1)

踩坑 5：Flask 3.x 移除 before_first_request

现象 ：before_first_request 在 Flask 3.x 中不再存在

替代方案：

# 方式 1: 使用 before_request + 标志位
_initialized = False

@app.before_request
def init_once():
    global _initialized
    if not _initialized:
        # 初始化逻辑
        _initialized = True

# 方式 2: 在 create_app() 中直接初始化
def create_app():
    app = Flask(__name__)
    # 初始化逻辑
    return app

踩坑 6：Flask __version__ 属性弃用

现象：

DeprecationWarning: The '__version__' attribute is deprecated and will
be removed in Flask 3.2. Use feature detection or
'importlib.metadata.version("flask")' instead.

解决：

import importlib.metadata as meta
version = meta.version('flask')

踩坑 7：Werkzeug 3.x 转换器名称变更

现象：

ImportError: cannot import name 'StringConverter' from 'werkzeug.routing'

解决：

# 旧: from werkzeug.routing import StringConverter
# 新: from werkzeug.routing import UnicodeConverter

---

附录 A：Flask 应用对象 API 速查

属性/方法	说明
app.config	配置字典
app.url_map	URL 映射表
app.debug	调试模式
app.testing	测试模式
app.secret_key	密钥
app.static_folder	静态文件目录
app.template_folder	模板目录
app.logger	日志器
app.test_client()	测试客户端
app.app_context()	应用上下文
app.request_context()	请求上下文
app.run()	启动服务器
app.route()	路由装饰器
app.errorhandler()	错误处理器
app.before_request	请求前钩子
app.after_request	请求后钩子
app.register_blueprint()	注册蓝图
app.shell_context_processor	Shell 上下文

附录 B：requirements.txt

flask==3.1.3
flask-sqlalchemy==3.1.1
flask-migrate==4.1.0
flask-login==0.6.3
flask-wtf==1.3.0
email_validator==2.3.0
gunicorn==23.0.0

附录 C：版本信息

组件	版本
Python	3.12.3
Flask	3.1.3
Werkzeug	3.1.8
Jinja2	3.1.6
Flask-SQLAlchemy	3.1.1
SQLAlchemy	2.0.51
Flask-Migrate	4.1.0
Flask-Login	0.6.3
Flask-WTF	1.3.0
Click	8.4.2
Itsdangerous	2.2.0
Blinker	1.9.0
WTForms	3.2.2
email_validator	2.3.0
OS	Ubuntu 24.04.4 LTS
Kernel	Linux ecs-60a4-0001

---

全文完

所有代码均在华为云 FlexusX ecs-60a4-0001（Ubuntu 24.04 / Python 3.12.3 / Flask 3.1.3）上真实执行验证。

9 个单元测试全部通过，功能覆盖完整。