Skip to content

7. 请求的生命周期

从请求到达到响应发出之间,[Flask] 要经历几个步骤,应用程序可以在每一步进行干预。其中有几个我们已经遇到过:路径变量转换器(示例 02 和 12)、[before_request] 函数(示例 16、22 和 23)以及错误处理器(示例 08 和 12)。本章把它们整合到一个示例中,该示例在每个步骤向控制台输出一条消息,以便你观察它们的顺序:

Image

  • 1 和 8. WSGI 中间件。[WSGI] (*Web Server Gateway Interface*)是把用 [Python] 编写的 Web 服务器与应用程序连接起来的标准。从服务器的角度看,[Flask] 应用程序只是一个可调用对象,它接收请求的描述并生成响应。中间件 是类似的一种对象,它包裹在应用程序外面:它在请求到达 [Flask] 之前拦截请求,并在之后拦截响应。它相当于 [Java] 的 Servlet 过滤器;
  • 2. 路由。[Flask] 查找与 URL 对应的路由,路由转换器转换路径变量;
  • 3 和 4. [before_request] 函数,按其注册的顺序执行。如果其中任何一个返回了响应(或抛出了异常),处理就在此停止:不会调用动作。我们就在这里验证用户是否已登录(下一章);
  • 5. 动作,以及它所生成的视图;
  • 6. [after_request] 函数接收响应,可以修改它(添加头部或 Cookie),并且必须返回它。它们按注册顺序的相反顺序执行;
  • 7. [teardown_request] 函数,它们总是在最后执行,即使异常中断了处理。它们不能再修改响应;其用途是释放资源(例如关闭数据库连接);
  • x. 错误处理器 ([errorhandler]):由 [before_request] 函数、动作或视图抛出的异常,会被交给为其类注册的处理器,由它生成错误响应。然后,这个响应会像普通响应一样经过 [after_request] 函数。

它们相当于 [Spring MVC] 的拦截器和 [ASP.NET Core MVC] 的动作过滤器。函数 [before_request]、[after_request]、和 [teardown_request] 通常被称为钩子。

7.1. 示例 24:处理请求所涉及的步骤

24-lifecycle/
├── app.py
├── controllers/
│   └── calc.py
├── filters/
│   ├── errors.py
│   ├── hooks.py
│   ├── integer.py
│   ├── logger.py
│   └── marks.py
└── templates/
    ├── calc/
    │   └── result.html
    ├── error.html
    └── layout.html

该应用程序只有一个动作,用于计算整数的平方:[/square/7]。根据 URL 的不同,它会成功,或以各种方式失败。

7.1.1. WSGI 中间件:filters/logger.py

# filters/logger.py:一个 WSGI 中间件。WSGI 是连接
# Python Web 服务器与应用的标准:应用是一个可调用对象
# app(environ, start_response)。中间件就是这样一个对象,它包装
# 应用:在 Flask 之前看到每个请求经过,在 Flask 之后看到响应
class LoggerMiddleware:

    def __init__(self, application):
        self.application = application  # 被包装的应用(Flask)

    def __call__(self, environ, start_response):
        # environ:描述请求的字典(方法、路径……)
        request = environ["REQUEST_METHOD"] + " " + environ["PATH_INFO"]
        if environ.get("QUERY_STRING"):
            request += "?" + environ["QUERY_STRING"]
        print()
        print("---", request)
        print("1. middleware (before)")
        status = []

        # start_response:Flask 通过它宣告响应的状态码和
        # 头部;我们包装它,以便在途中记下状态码
        def spy_start_response(status_line, headers, exc_info=None):
            status.append(status_line)
            return start_response(status_line, headers, exc_info)

        # 其余的一切:Flask、动作、视图
        response = self.application(environ, spy_start_response)
        print(f"8. middleware (after: code {status[0] if status else '?'})")
        return response
  • 第 7 行:中间件接收它所包裹的应用程序;
  • 第 10 行:特殊方法 [__call__] 使对象成为可调用的:[middleware(environ, start_response)] 执行的就是这个方法。这是 [WSGI] 规定的签名:[environ] 是描述请求的字典(方法在 [REQUEST_METHOD] 中,路径在 [PATH_INFO] 中,参数在 [QUERY_STRING] 中,还有头部等);[start_response] 是服务器提供的函数,应用程序调用它来报告响应码和头部;
  • 第 12–17 行:中间件显示请求。这是第 1 条消息:此时 [Flask] 中还没有发生任何事情;
  • 第 22–24 行:为了确定响应码,中间件向应用程序传入它自己的一个函数——代替 [start_response]——该函数在响应码经过时记录下来,然后调用真正的函数。这是一个内部函数 (定义在另一个函数之内):它可以访问包含它的函数的变量,这里是列表 [status];
  • 第 27 行:对被包裹应用程序的调用:其余的处理都发生在这次调用之中;
  • 第 28 行:第 8 条消息,在 [Flask] 处理完毕时输出。

中间件组件工作在 [WSGI] 层面:它不知道 [request]、[g] 或 [Flask] 的路由。它用于适用于所有请求的处理,而不论是哪个应用程序:日志记录、压缩、处理代理等。[Werkzeug] 提供了其中的一些,例如 [ProxyFix],当应用程序位于代理服务器之后时,它会修正客户端的地址(案例研究在讨论客户端 IP 地址时会谈到这一点)。

7.1.2. 转换器:filters/integer.py

# filters/integer.py:路径变量 <integer:n>,转换为整数,如果
# 不是整数则为 None(此时由动作来决定)
from werkzeug.routing import BaseConverter


class IntegerConverter(BaseConverter):
    # 任意一段路径(不含斜杠)
    regex = r"[^/]+"

    def to_python(self, value: str) -> int | None:
        print(f'2. conversion of the parameter (received value: "{value}")')
        try:
            return int(value)
        except ValueError:
            return None

一个转换器(示例 12),它接受路径的任意一段([[^/]+]:一个或多个不是 [/] 的字符),并对其整体进行转换,如果它不是有效的路径段,则转换为 [None] 。与 [<int:n>] 不同(对于 [/square/abc],它会返回 404 页面),这里由动作来决定结果。它显示第 2 条消息。

7.1.3. 标记的动作:filters/marks.py

[before_request] 函数会在所有动作之前运行。通常,某个处理只适用于特定的动作。指定这些动作的简单方法是对它们进行标记:

# filters/marks.py:两个标记动作的装饰器,不改变
# 动作的执行:它们给动作添加一个属性,filters/hooks.py 中的
# 函数会查找该属性


def block(action):
    action.block = True
    return action


def timing(action):
    action.timing = True
    return action

这两个装饰器不会改变动作本身:它们只是给动作添加一个属性(在 [Python] 中,函数是对象,可以为其添加属性),而动作保持不变。[before_request] 函数将在请求所指向的动作上查找这些标记。

7.1.4. 钩子:filters/hooks.py

# filters/hooks.py:在每个动作之前和之后执行的函数
import time

from flask import abort, current_app, g, request


# 将处理当前请求的动作(没有路由匹配时为 None)。
# request.endpoint:动作的名称("calc.square");view_functions:
# 应用的 名称 -> 函数 字典
def targeted_action():
    return current_app.view_functions.get(request.endpoint)


# 目标动作上是否带有 [name] 标记(见 marks.py)?
def marked(name: str) -> bool:
    return getattr(targeted_action(), name, False)


def register(app):

    # before_request:在动作之前。如果函数返回响应(或抛出
    # 异常),处理就此停止:动作不会被调用
    @app.before_request
    def block():
        if marked("block"):
            print(f"3. before_request Block (targeted action: {request.endpoint})")
            if "block" in request.args:
                abort(403)  # 一个 403 错误响应(拒绝访问)

    @app.before_request
    def timing_start():
        if marked("timing"):
            print("4. before_request Timing (before)")
            # 开始时间,存放在 g 中(请求作用域)
            g.start = time.perf_counter()

    # after_request:在动作(以及它构建的视图)之后,带着
    # 响应,函数可以修改它;必须将其返回
    @app.after_request
    def timing_after(response):
        if marked("timing"):
            print(f"6. after_request Timing (code {response.status_code})")
        return response

    # teardown_request:在最后,总是被调用,带有可能出现的
    # (未处理的)异常;它不能再改变响应
    @app.teardown_request
    def timing_end(exception):
        if "start" in g:
            ms = round((time.perf_counter() - g.start) * 1000)
            outcome = "" if exception is None else f", exception {type(exception).__name__}"
            print(f"7. teardown_request Timing (end, {ms} ms{outcome})")
  • 第 10–11 行:处理请求的动作。路由匹配之后,[request.endpoint] 包含所选路由的名称([calc.square]:蓝图名称、一个点、函数名称);[current_app.view_functions] 是将每个名称映射到对应函数的字典。如果没有路由匹配,[request.endpoint] 会被设置为 [None],函数返回 [None];
  • 第 15–16 行:标志是否已设置?[getattr(object, name, default)] 返回给定名称的属性,如果该属性不存在(或对象为 [None]),则返回默认值;
  • 第 19 行:回调函数由 [app.py] 调用的一个函数注册;
  • 第 24–28 行:第一个钩子,消息 3:对于标记为 [block] 的动作,URL 的 [?block] 参数会引发 403 错误(*Forbidden*,拒绝访问):[abort] 抛出一个异常,从而中断处理;
  • 第 31–35 行:第二个钩子,消息 4:对于标记为 [timing] 的动作,起始时间存储在 [g] 中。[time.perf_counter()] 是专门用于测量时长的高精度时钟;
  • 第 39–43 行:消息 6。该函数接收响应,并且必须将其返回(可以先做修改)。[response.status_code] 是响应状态码;
  • 第 47–52 行:消息 7,包含自钩子 4 以来经过的时间。["start" in g] 测试用于验证计时是否已经开始。如果存在尚未处理的、中断了处理的异常,该函数会接收到这个异常,否则接收到 [None]。

7.1.5. 错误处理:filters/errors.py

# filters/errors.py:应用的错误处理器
from flask import render_template
from werkzeug.exceptions import HTTPException


def register(app):

    # 给定类型的 "预期外" 异常:ValueError 及其子类
    @app.errorhandler(ValueError)
    def value_error(e: ValueError):
        print(f"x. errorhandler ValueError ({e})")
        # 不使用默认的错误页面,而是使用我们的 [error] 视图,状态码为 500
        return render_template("error.html", code=500), 500

    # HTTP 错误(abort(400)、abort(403)、未知页面 -> 404 等):
    # HTTPException 是 Werkzeug 所有 HTTP 异常的父类
    @app.errorhandler(HTTPException)
    def http_error(e: HTTPException):
        print(f"e. errorhandler HTTPException (code {e.code})")
        return render_template("error.html", code=e.code), e.code
  • 第 9–13 行:针对 [ValueError] 类(及其子类)的异常处理器:这是一个“意外”错误,被转换为状态码为 500(*Internal Server Error*)的“自定义”错误页面。异常消息显示在控制台中,而不显示在页面上:它可能包含与用户无关的内部细节;
  • 第 17–20 行:针对所有 HTTP 错误的处理器。[abort(400)]、[abort(403)]、指向不存在路由的 URL(404)、被禁止的方法(405):这些情况都会抛出 [HTTPException] 的某个子类的异常([BadRequest]、[Forbidden]、[NotFound]……),该异常在 [code] 属性中携带其状态码。因此,这个单一的处理器就用我们自己的页面取代了 [Werkzeug] 的所有英文错误页面。

对于一个异常,[Flask] 会选择为与其最接近的类所注册的处理器。你也可以为某个特定的状态码注册处理器:[@app.errorhandler(404)]。没有处理器的异常会变成 500 错误:在调试模式下,这是调试页面(示例 03);在非调试模式下,则是标准的 500 错误页面,或为状态码 500 注册的处理器所生成的页面。

7.1.6. 控制器和错误页面

# controllers/calc.py:由两个装饰器标记的动作
from flask import Blueprint, abort, render_template

from filters.marks import block, timing

calc = Blueprint("calc", __name__)


@calc.get("/square/<integer:n>")
@block
@timing
def square(n: int | None):
    print(f"5. action square({n})")
    if n is None:
        abort(400)  # 一个 400 错误:参见 filters/errors.py
    if n == 13:
        raise ValueError("13 brings bad luck")  # 一个"意外"错误
    return render_template("calc/result.html", n=n, square=n * n)
  • 第 9–11 行:该路由使用 [integer] 转换器;该动作带有两个装饰器。这里顺序同样重要(示例 12):装饰器自下而上应用,路由装饰器必须最后应用(即最先书写),才能注册被装饰的函数;
  • 第 15 行:参数不是整数:400 错误;
  • 第 17 行:数字 13 会引发“意外”错误;
  • 第 18 行:正常情况。
{% extends "layout.html" %}
{# 错误页面;其模型:错误码 #}

{% block content %}
  <div class="alert alert-danger">
    <h1 class="h4">Error {{ code }}</h1>
    <p class="mb-0">
      {% if code == 400 %}Bad request.
      {% elif code == 403 %}Access denied.
      {% elif code == 404 %}Page not found.
      {% else %}Internal server error.
      {% endif %}
    </p>
  </div>
{% endblock %}

错误页面接收错误代码并显示相应的消息。

7.1.7. 配置:app.py

# app.py:示例 24 的应用
from pathlib import Path

from flask import Blueprint, Flask

from controllers.calc import calc
from filters import hooks, errors
from filters.integer import IntegerConverter
from filters.logger import LoggerMiddleware

BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    # <integer:...> 变量的转换器
    app.url_map.converters["integer"] = IntegerConverter
    app.register_blueprint(calc)
    # 在每个动作之前和之后执行的函数,按
    # 注册的顺序
    hooks.register(app)
    # 错误处理器
    errors.register(app)
    # WSGI 中间件:它包装整个 Flask 应用
    app.wsgi_app = LoggerMiddleware(app.wsgi_app)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • 第 21 行:转换器;
  • 第 25–27 行:回调函数和错误处理器;
  • 第 29 行:中间件。[app.wsgi_app] 是服务器调用 [Flask] 应用程序所用的方法;它被中间件取代,而中间件会调用旧的方法。我们包装的是 [app.wsgi_app] 而不是 [app] 本身,这样变量 [app] 仍然是 [Flask] 对象,保留它的各个方法([run]、[route]……)。

7.1.8. 执行

正常情况,[/square/7]:

Image

服务器控制台按顺序显示这八个步骤:

--- GET /square/7
1. middleware (before)
2. conversion of the parameter (received value: "7")
3. before_request Block (targeted action: calc.square)
4. before_request Timing (before)
5. action square(7)
6. after_request Timing (code 200)
7. teardown_request Timing (end, 1 ms)
8. middleware (after: code 200 OK)
127.0.0.1 - - [26/Sep/2026 15:39:00] "GET /square/7 HTTP/1.1" 200 -

最后一行是 [Werkzeug] 开发服务器的日志条目,在响应发送之后写入。被阻止的访问,[/square/7?block]:

Image

1
2
3
4
5
6
7
--- GET /square/7?block
1. middleware (before)
2. conversion of the parameter (received value: "7")
3. before_request Block (targeted action: calc.square)
e. errorhandler HTTPException (code 403)
6. after_request Timing (code 403)
8. middleware (after: code 403 FORBIDDEN)

第一次调用引发了异常:第二次调用和该动作都没有执行。由处理器生成的错误响应会经过 [after_request];[teardown_request] 被调用了,但没有显示任何内容,因为操作并未开始。参数不是整数,[/square/abc]:

Image

--- GET /square/abc
1. middleware (before)
2. conversion of the parameter (received value: "abc")
3. before_request Block (targeted action: calc.square)
4. before_request Timing (before)
5. action square(None)
e. errorhandler HTTPException (code 400)
6. after_request Timing (code 400)
7. teardown_request Timing (end, 0 ms)
8. middleware (after: code 400 BAD REQUEST)

这一次,动作被调用了——[None]——并且它引发了 400 错误。“意外”错误,[/square/13]:

Image

--- GET /square/13
1. middleware (before)
2. conversion of the parameter (received value: "13")
3. before_request Block (targeted action: calc.square)
4. before_request Timing (before)
5. action square(13)
x. errorhandler ValueError (13 brings bad luck)
6. after_request Timing (code 500)
7. teardown_request Timing (end, 0 ms)
8. middleware (after: code 500 INTERNAL SERVER ERROR)

该异常由其处理器处理:用户看到的是“自定义”错误页面,而不是调试页面,即使调试模式已启用。最后,不对应任何路由的 URL,[/unknown]:

1
2
3
4
--- GET /unknown
1. middleware (before)
e. errorhandler HTTPException (code 404)
8. middleware (after: code 404 NOT FOUND)

路由失败:没有路由、没有转换器、没有动作。回调函数已经执行,但由于找不到目标动作,因此没有显示任何内容。404 页面是我们自己的:

curl -i http://localhost:5000/unknown
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 375
...
  <div class="alert alert-danger">
    <h1 class="h4">Error 404</h1>
    <p class="mb-0">
Page not found.
    </p>
  </div>
...

我们来抓住要点。[before_request] 函数是放置许多动作共有的检查(用户是否已登录?他是否有权限访问该动作?)的合适位置:下一章将用它们来实现身份验证。错误处理器确保无论发生什么错误,用户都不会看到技术性页面:案例研究为每种类型的错误都准备了一个处理器。