2. 视图、路由、响应
本章考察请求从浏览器到处理它的视图所经过的路径,以及该视图返回的响应。模板要到第 3 章才会介绍:在这里,视图直接返回文本或 JSON。
2.1. 示例 01:Django 应用的结构
第一个示例是尽可能小的 [Django] 应用。由 [django-admin startproject] 创建的项目包含六个文件,而由 [python manage.py startapp] 创建的应用还包含七个文件(见简介);在这里,我们只保留应用不可缺少的那些文件:
- [manage.py]:项目的命令行工具。它用于启动开发服务器并执行许多其他命令;
- [config]:一个 [Python] 包,即包含 [Python] 模块([.py] 文件)和一个 [__init__.py] 文件的文件夹。要从包中导入模块,请输入 [config.settings] (即 [config/settings.py] 文件);
- [config/settings.py]:应用的设置;
- [config/urls.py]:应用的路由,在这第一个示例中还包含它唯一的视图;
- [config/wsgi.py]:应用面向 Web 服务器的入口点;
- [config/__init__.py]:使 [config] 文件夹成为包的文件。它通常是空的;我们的文件只包含一行注释。
2.1.1. 入口点:config/wsgi.py
[Python] 为 Web 应用定义了一个标准:WSGI(Web Server Gateway Interface,读作“whiskey”)。它规定了 Web 服务器如何把请求转发给 [Python] 应用,以及如何接收响应。所有 [Python] Web 服务器([gunicorn]、[waitress]、[uWSGI]、[Django] 开发服务器……)都知道如何调用名为 WSGI 的应用,而所有 [Python] Web 框架([Django]、[Flask]……)都会生成这样一个应用。文件 [config/wsgi.py] 为我们的项目生成这个应用:
- 第 1 行:注释,从 [#] 开始直到行尾。所有示例文件都以一行注释开头,说明文件的名称和用途;
- 第 3 行:语句 [import] 导入一个模块:这里是 [os],它是 [Python] 标准库中的模块,提供对操作系统的访问,尤其是对进程环境变量的访问([os.environ]);
- 第 5 行:[from ... import ...] 导入模块中的名称:即函数 [get_wsgi_application] ,它来自模块 [django.core.wsgi]。模块的完整名称指明了它的位置:[django.core.wsgi] 是 [django] 包的 [core] 文件夹中的文件 [wsgi.py],该包安装在虚拟环境中(见简介)。这次导入之后,文件中就可以直接使用名称 [get_wsgi_application];
- 第 8 行:[Django] 通过环境变量 [DJANGO_SETTINGS_MODULE] 获取其设置,该变量包含配置模块的名称:[config.settings]。[os.environ] 的行为类似字典;它的方法 [setdefault] 为其赋值,除非它已经有值:在服务器启动之前设置的真正的环境变量具有优先权;
- 第 11 行:[get_wsgi_application()] 负责准备 [Django]:它读取设置、配置日志、加载项目的应用(示例 02),然后返回 WSGI 应用,存放在变量 [application] 中。Web 服务器要在文件中查找的正是这个变量。在 [Python] 中,变量不需要声明:它在第一次赋值时创建,可以保存任何类型的值。
WSGI 应用是一个对象,服务器针对收到的每个请求,带着请求的详细信息调用它;该对象返回响应。因此,整个应用就是一个把请求转换为响应的函数。在这中间,[Django] 创建请求对象([HttpRequest]),找到负责处理该请求的视图(路由),调用它,并取回它生成的响应对象([HttpResponse]),然后把响应传给服务器。
这个文件只在服务器启动时执行一次。这是与 [PHP] 的关键差异,读过 [Symfony] 课程的读者已经亲眼见过:在 [PHP] 中,应用会为每个请求重新构建,然后被丢弃;在 [Python] 中,它在启动时构建一次,然后一直驻留在内存中处理所有后续请求。配置、路由表、已导入的模块以及存放在模块变量中的对象——这一切都只构建一次,并由所有请求共享。这样很快,但需要小心:一个请求修改的数据会被后续请求看到,而且如果服务器同时处理多个请求(开发服务器就是这样做的,每个请求使用一个线程),两个请求就可能同时修改同一份数据。我们将在示例 06 中回到这一点,尤其是在数据作用域那一章。
[Python] 还有第二个更新的标准:ASGI(Asynchronous Server Gateway Interface,异步服务器网关接口),用于异步应用(例如 WebSocket)。[Django] 两种都能生成:[asgi.py] 文件由 [django-admin startproject] 创建,用于生成 ASGI 应用。我们只使用 WSGI。
2.1.2. 配置:config/settings.py
[Django] 的设置是 [config.settings] 模块中以大写字母书写的变量。它是一个标准的 [Python] 文件:你可以在其中计算值、读取环境变量并导入其他模块。[Django] 只要求少数几个设置;其余设置都有默认值,定义在 [django.conf.global_settings] 模块中,该模块属于 [Django] (超过 150 个设置)。命令 [python manage.py diffsettings] 会显示与默认值不同的设置:
- 第 3 行:[pathlib] 是处理文件路径的标准库模块。[Path] 对象表示一个路径;它在 [Windows] 和其他系统上的写法相同;
- 第 6 行:项目文件夹。[__file__] 是当前文件的路径([config/settings.py]);[resolve()] 使其成为绝对路径;[.parent] 指向包含它的文件夹([config]),而 [.parent.parent] 指向再上一级的文件夹:即 [01-structure] 文件夹。这个设置 [BASE_DIR] 并不是 [Django] 的设置:它是一个便利项,其他设置会用它来引用项目文件夹([BASE_DIR / "templates"],示例 13:运算符 [/] 用于拼接两个路径段);
- 第 10 行:调试模式。如果它被设置为 [True],未处理的异常会显示详细的错误页面(示例 03),并且开发服务器会自己提供静态文件(示例 15)。此模式仅用于开发:错误页面会暴露应用的源代码和配置;
- 第 13 行:应用的密钥:一个随机字符串,[Django] 用它对某些数据进行签名(签名 Cookie、防 CSRF 令牌、密码重置链接等)。这个设置是必需的:没有它,[Django] 将拒绝启动。每个示例都有自己的密钥。前缀 [django-insecure-] 是 [django-admin startproject] 所使用的:它提醒我们,这个硬编码在源代码中的密钥不得用于生产环境,生产环境中的密钥通过环境变量提供(案例研究);
- 第 17 行:应用被配置为可以服务的主机名(请求中的 [Host] 头)。这是针对谎报目标站点的请求的一种保护措施。在调试模式下,空列表等同于 [localhost]、[127.0.0.1] 和 [::1];在非调试模式下,它必须填写,否则 [python manage.py runserver] 将拒绝启动。在 [Python] 中,[[a, b]] 是一个列表;
- 第 20–21 行:应用的语言([en]:[Django] 中的日期、数字和消息均为英语;见示例 06)及其时区。字符串可以用双引号或单引号括起来;示例使用双引号;
- 第 24 行:包含应用路由的模块:[config.urls],即文件 [config/urls.py];
- 第 27 行:WSGI 应用,用它的完整路径指定:即 [application] 变量,来自 [config.wsgi] 模块。开发服务器启动的就是它。
2.1.3. 路由与视图:config/urls.py
- 第 3–4 行:导入 [HttpResponse] 类(即 HTTP 响应)和 [path] 函数(用于声明路由);
- 第 9–11 行:一个视图——接收请求并返回响应的函数。[def] 定义一个函数;它的函数体是冒号之后缩进的代码块。在 [Python] 中,缩进不只是格式问题:它决定了代码块的边界(而 [PHP] 和 [Java] 使用花括号)。参数 [request] 接收请求,即一个 [HttpRequest] 对象,由 [Django] 始终作为第一个参数传给视图(示例 05);按 [Django] 的约定,把它命名为 [request];
- 第 11 行:视图返回一个 [HttpResponse] 对象,它的第一个参数是响应体。在 [Python] 中,创建对象的方法是像调用函数一样调用它的类,不需要 [new] 关键字。这是 [Django] 的规则:视图总是返回一个 [HttpResponse] 对象(示例 03);
- 第 15–17 行:路由表。[Django] 在 [ROOT_URLCONF] 模块中查找名为 [urlpatterns] 的变量:一个路由列表。路由 [path("", home)] 把空路径(站点根,[/])与视图 [home] 关联起来。请注意,路由的路径不带前导斜杠:[Django] 会先从所请求的路径中去掉它,再与各路由比较。还请注意,函数本身([home],不带括号)被传给 [path],而不是它的结果:在 [Python] 中,函数和其他对象一样,可以存入变量或传给另一个函数。[Django] 稍后会为每个对 [/] 的请求调用它。列表最后一个元素后面允许带逗号,当各元素逐行书写时这是常见做法。
在真实项目中,视图绝不会写在路由文件里:它们会放在应用的 [views.py] 文件中(示例 02)。这里这样写是为了让示例保持简单。
2.1.4. manage.py 工具
[manage.py] 文件是一个 [Python] 脚本,它与 [Django] 一样做准备工作,就像 [config/wsgi.py] 那样,但目的是执行命令,而不是处理请求:
- 第 1 行:在 [Linux] 和 [macOS] 下,这一行使文件可以被直接执行([./manage.py]);在 [Windows] 下,则始终输入 [python manage.py];
- 第 10 行:配置模块,与 [config/wsgi.py] 中相同;
- 第 12–13 行:导入也可以在函数内部进行。[execute_from_command_line] 执行所请求的命令:[sys.argv] 是命令行参数列表([["manage.py", "runserver"]]);
- 第 16–17 行:[__name__] 在文件被直接执行时等于 ["__main__"] ([python manage.py]),在文件被导入时则等于模块名。这个条件出现在许多 [Python] 脚本中,它只在第一种情况下调用 [main] 函数。
[python manage.py help] 显示可用命令的列表:本示例中有二十五个,添加 [Django] 功能(静态文件、会话、身份验证等)后会更多。我们将用到其中几个:[runserver]、[check] (项目检查)、[shell](一个 [Python] 控制台,其中 [Django] 已准备就绪)、[makemessages] 和 [compilemessages] (翻译,示例 22)、[collectstatic] (静态文件,案例研究;由 [django.contrib.staticfiles] 应用添加)。[django-admin] (见附录)是同一个工具,但它不知道项目配置位于何处。
2.1.5. 执行
在打开到 [01-structure] 文件夹的终端窗口中(示例所用的虚拟环境已经激活,见简介),输入 [python manage.py runserver]。[Django] 显示:
命令 [runserver] 启动 [Django] 内置的开发服务器。它首先对项目执行系统检查:缺失或不一致的设置,或者写错的路由,会在这里产生错误或警告,此时还没有任何请求。然后它在本机的 8000 端口监听([127.0.0.1]、[localhost]):它只接受来自本机的请求,这适合开发([python manage.py runserver 0.0.0.0:8000] 会把它开放给网络上的其他机器)。使用 [Ctrl-C] 停止它。这个服务器仅用于开发,正如它的警告所说:在生产环境中,它将是一个 WSGI 服务器,例如 [gunicorn] 或 [waitress] (见案例研究)。
第一行表明服务器会监视项目文件([StatReloader]:它定期比较文件的修改日期)。由于应用常驻内存,对 [Python] 文件之类的修改不会被正在运行的应用检测到;因此,一旦文件发生变化,开发服务器就会自动重启。不必手动重启它,除非是新添加了一个尚未被任何地方导入的文件。
让我们用浏览器访问 URL [http://localhost:8000/] :

然后使用 [curl]。[-i] 选项还会显示响应的 HTTP 头:
响应的第一行是协议版本、状态码(200)及其标签([OK])。接下来是头:日期、服务器(来自 [Python] 标准库的 WSGI 服务器,开发服务器就建立在它之上)、内容类型,以及 [Connection: close](开发服务器在每次响应之后关闭连接)。一个空行把头与响应体分隔开。在本文档的后续部分,我们将不再列出 [Date]、[Server] 和 [Connection] 这几个头,因为它们不会变化。
头 [Content-Type: text/html; charset=utf-8] 表明响应是 HTML,其字符以 UTF-8 编码。这是 [Django] 对视图未指定类型的响应所做的选择:因此浏览器把该字符串解释为 HTML(这里没有标签,所以按原样显示)。示例 03 将展示如何指定其他类型。这个响应是最简的:没有 [Content-Length] 头,没有 Cookie,也没有安全头。这些都由 [Django] 的中间件添加(示例 03),而我们的应用没有中间件。
对于每个请求,服务器控制台都会显示一条日志:日期、请求详情(方法、路径、协议)、响应代码以及响应体的字节数:
让我们修改 [config/urls.py] 第 11 行的文本并保存文件:控制台会显示 [.../01-structure/config/urls.py changed, reloading.],随后是启动时的那些行。下一个请求就会收到新的文本。
2.2. 示例 02:路由
路由把 URL 与视图关联起来。把所有视图都直接写进路由文件会很快变得难以阅读;因此我们把它们组织成应用。[Django] 应用是一个 [Python] 包,它把与某一领域相关的一切归拢在一起:它的视图、路由,以及稍后的模板、表单和模型。项目是应用的集合。示例 02 有两个:
文件 [manage.py]、[config/__init__.py], 和 [config/wsgi.py] 与示例 01 中的相同:我们不再重复说明。文件 [config/settings.py] 总是以相同的设置开头(只有示例名称和密钥不同);我们只对每个示例新增的设置进行说明。下面是应用列表:
- 第 17–20 行:[INSTALLED_APPS] 设置列出项目的应用,用它们的包名标识。[Django] 在启动时按此顺序加载它们。对我们的示例来说,这个声明并非必需:[home] 和 [first] 的视图 是通过路由文件中的导入找到的。一旦应用包含模板(示例 13)、模板标签(示例 16)、翻译(示例 22)或 ORM 模型(示例 28),它就变得必不可少——因为 [Django] 只在已声明的应用中查找这些内容。[Django] 本身提供了若干应用([django.contrib.sessions]、[django.contrib.messages]、[django.contrib.staticfiles]、[django.contrib.admin]……),它们的声明方式相同。
2.2.1. home 应用的视图
- 第 4 行:导入 [Django] 的一个装饰器;
- 第 9–10 行:装饰器是一个包装另一个函数以修改其行为的函数。它写在函数定义上方,形式为 [@name] :把 [@require_GET] 写在 [def index] 之上,等价于在定义之后写 [index = require_GET(index)]。函数 [index] 被替换为一个函数,它首先检查请求的 HTTP 方法:如果不是 GET,它会自己返回 405 错误,而不调用 [index]。没有装饰器时,视图接受所有方法。[django.views.decorators.http] 模块还包含 [require_POST]、[require_safe] (GET 和 HEAD)以及 [require_http_methods(["GET", "POST"])]。请注意,[require_GET] 连 HEAD 方法的请求(与 GET 相同,只是没有响应体)也会拒绝:要接受它就必须使用 [require_safe]。按照惯例,[Python] 中的函数名或变量名用小写字母书写,单词之间用下划线分隔([require_GET] 是个例外),而类名的每个单词都以大写字母开头([HttpResponse]);
- 第 11–22 行:一个多行字符串,由三个引号界定(["""])。该视图返回 HTML,以 [text/html] 类型发送(见示例 01)。
因此视图 [index] 返回一个 HTML 页面,其中包含指向另一个应用中视图的链接:

2.2.2. first 应用的视图
- 第 9–11 行:函数形式的视图,与示例 01 相同;
- 第 16–21 行:视图也可以是继承自 [View] 类的类,该类来自 [Django]。在 [Python] 中,继承的写法是把父类放在类名后面的括号中。该类为它实现的每个 HTTP 方法提供一个方法,方法名是 HTTP 方法的小写形式:GET 对应 [get] ,POST 对应 [post] 。[Django] 调用与请求对应的方法;类中没有任何方法处理的 HTTP 方法会导致 405 错误。[Python] 方法总是把调用它的对象作为第一个参数接收——按惯例命名为 [self]——然后才是请求。这是在同一个 URL 上处理多种 HTTP 方法的最清晰的方式(函数则需要自己测试 [request.method] ;见示例 11)。[Django] 还提供通用视图——针对常见需求的现成类([TemplateView]、[ListView]、[FormView]……),本文档不使用它们:它们恰恰隐藏了我们想要展示的内容;
- 第 26–28 行:一个接收路由参数的视图,该参数 [id] 位于请求之后。该值已被转换为整数(见下文)。字符串 [f"Product no. {id}"] 是一个 f-string:写在花括号中的表达式会被替换为它们的值;
- 第 32–34 行:两个路由参数。[Django] 按名称把它们传给视图(命名参数):视图参数的顺序无关紧要。这里,[number] 写在 [id] 之前;
- 第 38–40 行:一个包含斜杠的路由参数。
2.2.3. 路由:config/urls.py 和 first/urls.py
还需要把各个 URL 与视图关联起来。主路由表,对应 [ROOT_URLCONF] 设置:
- 第 5 行:以不同的名称导入 [views] 模块,它来自 [home] 应用:[as home_views]。两个应用可能各有一个名为 [views] 的模块;重命名可以避免混淆;
- 第 9 行:站点根的路由。第三个参数 [name] 为该路由命名:这个名称将用于生成它的 URL(示例 04),而无需硬编码。[Python] 既接受按位置传递的参数,也接受按名称传递的参数([name="home"]):命名参数使调用更易读;
- 第 12 行:[include] 把一部分 URL 委托给另一个路由表:所有以 [first/] 开头的 URL 都被分配给 [first.urls] 模块中的路由,[Django] 只把路径的剩余部分传给它们。这样每个应用都把路由保存在自己的 [urls.py] 文件中,项目只决定把它们挂载在哪个前缀之下。前缀以斜杠结尾:这是 [Django] 采用的约定,应用的路由从不以斜杠开头。
- 第 10 行:[app_name] 为该文件的路由提供命名空间:对项目的其余部分而言,名为 [product] 的路由称为 [first:product]。因此两个应用可以各有一个名为 [index] 的路由而不冲突;
- 第 14 行:路径 [""] 指前缀本身:即 URL [/first/];
- 第 17 行:写成类的视图。[as_view()] 是 [View] 类的方法,它创建一个函数,[Django] 会为每个请求调用这个函数:该函数创建一个 [Action01] 对象,然后根据请求的 HTTP 方法调用它的 [get] 或 [post] 方法。每个请求都会创建一个新对象;
- 第 20 行:[<int:id>] 是一个路由参数:URL 的这一段可以取多个值。[id] 是参数的名称,它将被传给视图;[int] 是一个转换器,它只接受数字,并把一个整数传给视图:对于 URL [/first/products/17],视图的 [id] 参数就是整数 17。如果该段不是由数字组成,路由就不匹配。这就是数据绑定,下一章将详细讨论;
- 第 22 行:两个路由参数;
- 第 25 行:转换器 [path] 接受任何路径结尾,包括斜杠。[Django] 有五个转换器:[str] (默认转换器:[<name>] 等价于 [<str:name>];任何不含斜杠的非空文本)、[int] (数字)、[slug] (字母、数字、连字符和下划线,如 [my-article-01])、[uuid] (UUID 标识符)以及 [path]。示例 12 将展示如何编写“自定义”转换器,示例 22 将展示函数 [re_path],它用正则表达式描述路由。
对于每个请求,[Django] 按顺序遍历各路由,并在第一个与所请求路径匹配的路由处停止:当两个路由可能匹配同一路径时,路由的顺序很重要。
2.2.4. 执行
下面是对几个请求的响应:
要发送 POST 请求,请使用 [-X POST] 选项,它属于 [curl]:
POST 请求被原样接受。一旦应用拥有 [Django] 的防 CSRF 保护中间件(示例 18),情况就不再如此:该中间件会拒绝任何无法证明来自应用内表单的 POST 请求。视图不处理的 HTTP 方法会导致 405 错误([Method Not Allowed])。[Allow] 头指明所接受的方法:
响应没有响应体。除了类中定义的方法之外,[View] 类还接受 HEAD 方法(由 [get] 方法处理)和 OPTIONS 方法(返回所接受方法的列表)。服务器控制台会报告这次拒绝:
装饰器 [@require_GET] 会产生同样的错误:
没有任何路由处理的 URL 会导致 404 错误。对于不是数字的标识符也是如此:[int] 转换器使路由无法匹配 [/first/products/abc]。
在浏览器中,调试模式下:

[Django] 的错误页面说明没有路由与所请求的路径匹配,并按顺序列出应用中所有路由及其名称:这是检查路由的好方法([Django] 没有列出路由的命令)。请注意,[first] 应用中的路由确实都带有前缀 [first/],并且路径是在去掉前导斜杠之后进行比较的。第 6 章将展示如何用应用自定义的页面替换这个页面。另请注意,[Django] 区分 [/first/] 和 [/first]:后者(URL)没有路由,会返回 404 错误。[Django] 的一个中间件组件 [CommonMiddleware] (案例研究)解决了这个问题:当一个不带结尾斜杠的路径没有路由,而带结尾斜杠的同一路径有路由时,它会把浏览器重定向(示例 04)到第二个路径(这就是 [APPEND_SLASH] 设置,默认启用)。
2.3. 示例 03:视图的响应
视图返回什么,决定了 HTTP 响应是什么。示例 03 回顾了主要的几种情况:
应用 [responses] 的路由挂载在前缀 [responses/] 之下,挂载由文件 [config/urls.py] 完成;这些路由将每个 URL [/responses/xxx] 与一个视图关联:
我们来逐段说明这段代码:
- 第 5 行:[django.http] 模块中的响应类和异常类;
- 第 8 行:从同一应用内的模块导入一个类。[.viewmodels] 中的点指的是当前文件所在的包([responses]):这是相对导入;
- 第 12–14 行:[HttpResponse] 接受命名参数:[content_type] 在这里指定纯文本([text/plain]);浏览器不会解释其中的标签。[status] (状态码,默认为 200)和 [headers] (头字典)是另外两个参数;
- 第 18–20 行:同样的字符串,但不声明类型:[Django] 会以 [text/html] 类型发送它,浏览器会对它进行解释;
- 第 26–28 行:[JsonResponse] 是 [HttpResponse] 的子类:它把第一个参数转换为 JSON,并声明类型 [application/json]。转换由标准库中的 [json] 模块完成,该模块只识别 [Python] 的基本类型:字典、列表、字符串、数字、布尔值和 [None]。因此对象必须先转换为字典:这正是函数 [asdict] (第 3 行)对数据类所做的事,例如下面所示的 [Person]。该视图命名为 [as_json]:如果把它命名为 [json],那么一旦导入了 [json] 模块,它就会在这个文件中把该模块遮蔽;
- 第 32–34 行:一个用花括号括起来的 [Python] 字典,会变成一个 JSON 对象;
- 第 39–41 行:列表会变成 JSON 数组。默认情况下,[JsonResponse] 只接受字典:这是一项针对旧版浏览器中某个漏洞的老式防护措施,该漏洞允许第三方站点读取 JSON 数组。[safe=False] 参数取消了这一限制;
- 第 45–49 行:一个计算得出的列表。[sort] 方法对列表排序(它会修改列表本身)。[[n * 10 for n in numbers]] 是一个列表推导式:由值 [n * 10] 构成的列表,其中 [n] 取列表 [numbers] 中的每个元素;
- 第 53–55 行:参数 [status]:201([Created])取代 200;
- 第 59–61 行:代码 204([No Content])表示“没有内容可显示”:响应没有响应体;
- 第 65–67 行:一个“预期中的”错误:404 响应([Not Found]),响应体(JSON)由视图选择;
- 第 71–73 行:同样的错误,由异常引起。[Http404] 是 [Django] 的一个异常;语句 [raise] 抛出它,从而终止视图。[Django] 把它转换为 404 错误响应。这是因出错而终止视图的最常见方式,即使错误发生在视图所调用的函数的深处也是如此。[django.shortcuts] 模块提供了两个会抛出它的快捷函数:[get_object_or_404] 和 [get_list_or_404] (用于 ORM 模型,第 7 章)。[django.core.exceptions] 定义了产生其他错误代码的异常:[PermissionDenied] (403)、[BadRequest] (400)、[SuspiciousOperation] (400);
- 第 77–79 行:一个“意料之外的”错误——无人处理的异常——会导致 500 响应([Internal Server Error])。[RuntimeError] 是 [Python] 标准库中的一个异常类,无需导入即可使用;
- 第 84–86 行:需要避免的错误。[Django] 视图必须返回一个 [HttpResponse] 对象;这个视图成功生成了响应,却没有返回它。没有 [Python] 的 [return] 函数会返回值 [None],[Django] 会拒绝它(我们稍后会查看响应)。这与其他框架不同,例如 [Flask],它们自己会把字典或字符串转换为响应:[Django] 要求视图明确指定它返回哪一个响应。
[Person] 类:
- 第 3 行:标准库中的 [dataclasses] 模块;
- 第 9–13 行:一个数据类。形如 [last_name: str] 的行声明了属性及其类型(类型注解,[Python] 在运行时并不强制检查,但代码编辑器会检查)。装饰器 [@dataclass] 利用这些属性生成类的构造函数(方法 [__init__],由 [Person("Martin", "Jean", 42)] 调用)、比较方法([==])和文本表示([Person(last_name='Martin', first_name='Jean', age=42)])。使用 [frozen=True] 时,构造之后属性就不能再被修改:[Person] 对象 是不可变的。并不要求把这个类放在 [viewmodels.py] 模块中:这是本文档做出的选择,本文档把名称 [models.py] 保留给 [Django] 的 ORM 模型(第 7 章)。
还剩下文件 [config/middleware.py]:
默认情况下,[JsonResponse] 响应包含紧凑的单行 JSON,其中的非 ASCII 字符被写成转义序列:[é] 变成 [\u00e9],这是有效的 JSON,但可读性不佳。对于本课程的示例,我们希望得到可读的 JSON。与其在每个视图中都提出这一要求([json_dumps_params] 参数,它属于 [JsonResponse] ,可以做到这一点),不如借助 [Django] 中的一种集中机制来修改应用中的所有 JSON 响应:中间件。
中间件是从请求通向视图、再从视图通向响应的链条中的一环。[Django] 把 [MIDDLEWARE] 配置中的中间件组件像俄罗斯套娃一样串联起来:第一个接收请求并把它传给下一个,下一个再传给再下一个,依此类推,直到到达视图;视图的响应随后按相反的顺序沿链条返回。每个中间件组件都可以在请求进入时检查或修改请求,在响应离开时检查或修改响应,甚至可以不调用下一个组件而自己直接响应。[Django] 本身就是这样构建的:会话、防 CSRF 保护、消息和语言,全都是中间件组件。
- 第 11–13 行:中间件是一个类。[Django] 在应用启动时创建它的唯一一个实例,并把函数 [get_response]——即链条的其余部分(后续的中间件组件,再加上视图)——传给它的构造函数([__init__])。构造函数把它存放在对象的一个属性 [self.get_response] 中;
- 第 15–24 行:方法 [__call__] 使对象可以像函数一样被调用:[Django] 为每个请求调用它,并传入请求。在调用 [self.get_response(request)] 之前的代码在视图之前执行;在它之后的代码在视图之后执行:这里,中间件在视图之前什么也不做;
- 第 19–23 行:如果响应是 JSON 响应([isinstance] 函数检查对象的类),中间件就重新读取它的响应体([response.content],字节),将其解码([json.loads]),然后再重新编码([json.dumps]),并使用两个选项:[ensure_ascii=False] (非 ASCII 字符按原样写出)和 [indent=4] (带缩进的多行格式)。对 [response.content] 的赋值会替换响应体;
- 第 24 行:中间件返回响应,响应继续向上传播。
中间件还需要在文件 [config/settings.py] 中声明:
- 第 20–22 行:[MIDDLEWARE] 配置按请求经过的顺序列出应用的中间件组件,用其类的完整路径指定。随着示例的推进,我们会看到它逐步充实。示例 05 到示例 12 复用了这个中间件。
在浏览器中,可以看出 [text/plain] 和 [text/html] 的区别:


下面是其他视图的响应:
对象被转换成了 JSON 对象,每个属性对应一个字段。视图 [/responses/dictionary] 产生完全相同的响应。
异常响应是 [Django] 的错误页面,即示例 02 中的那个页面,只是用我们的消息取代了路由列表。即使客户端通过 [Accept: application/json] 头请求 JSON 响应([-H] 选项,属于 [curl]:[curl -i -H "Accept: application/json" http://localhost:8000/responses/abort]),响应仍然是 HTML 页面:[Django] 不会根据所请求的类型调整它的错误响应。希望以 JSON 格式返回错误的应用,要借助中间件自己生成(示例 08)。控制台会报告该错误:
接下来是未处理的异常。在调试模式下,浏览器会显示 [Django] 的错误页面:异常的类型和消息、当前视图、抛出异常的文件和行号,随后是调用栈(traceback),即出错时正在执行的函数列表,按从最早到最近的顺序排列:

再往下看,栈中的最后一个函数是我们的视图 [error],位于文件 [responses/views.py] 的第 79 行;它上面是调用它的 [Django] 函数。对每个函数,“Local vars”链接会显示它的局部变量的值;页面的其余部分显示请求(它的参数、Cookie 和头)以及应用的所有设置(名称暗示敏感信息的设置,例如 [SECRET_KEY],会用星号遮蔽)。出于所有这些原因,绝不能在他人可以访问的服务器上启用调试模式。该错误还会连同调用栈一起写入应用日志——在这里就是服务器控制台:
在没有调试模式时([DEBUG = False] 位于文件 [config/settings.py] 中,同时还要有 [ALLOWED_HOSTS = ["localhost"]],因为列表不能再为空),同样的请求会产生一个简短的错误页面,不会泄露任何关于代码的信息:
而 [/responses/abort] 的 404 错误也会变成一个简短的页面([Not Found]:“The requested resource was not found on this server.”),不带我们的消息。在调试模式之外,[Django] 也不再把调用栈写入控制台:如果指定了站点管理员(设置 [ADMINS]),它会通过电子邮件把调用栈发送给他们。案例研究将展示如何配置日志。第 6 章将展示如何显示应用专属的错误页面。
最后是忘记返回响应的那个视图:
控制台显示了异常消息:
这条消息很清楚:“The view did not return an object HttpResponse; it returned None.” 这是初学者常犯的错误:在有多个分支的视图中([if] / [else]),其中一个分支忘了写 [return]。
2.4. 示例 04:重定向
重定向是一种响应,它指示浏览器去获取另一个 URL:一个 3xx 代码,加上包含新地址的 [Location] 头。浏览器随即向该地址发送第二个请求。示例中的路由:
文件 [config/urls.py] 把应用 [redirects] 的路由挂载到站点根(空前缀)。文件 [redirects/urls.py] 中没有 [app_name] 这一行:它的路由没有命名空间,只是简单地命名为 [page]、[new]……视图如下:
- 第 4 行:[django.shortcuts] 模块包含一些快捷函数,它们把最常见的操作浓缩为一行:[redirect]、[render] (模板那一章)、[get_object_or_404]……;
- 第 9–11 行:[redirect] 向指定地址生成一个重定向响应([HttpResponsePermanentRedirect] 或 [HttpResponseRedirect] 对象,它们是 [HttpResponse] 的两个子类)。使用 [permanent=True] 时,代码为 301([Moved Permanently]):页面的地址已永久改变,浏览器(以及搜索引擎)可以记住新地址;
- 第 21–23 行:没有 [permanent=True] 时,[redirect] 生成状态码为 302 的临时重定向([Found])。地址是通过拼接文本片段计算出来的(运算符 [+] 拼接两个字符串),这会带来问题,我们稍后会看到;
- 第 28–30 行:[redirect] 也接受路由的名称(['page']),后面跟着它的参数([name=destination]):这时它会使用 [reverse] 函数(来自 [Django])自己生成地址,该函数执行反向路由过程(从路由名称及其参数得到 URL),并为 URL 正确地编码参数。如果 [page] 路由的路径日后被更改,指向它的重定向会自动更新。对于带有命名空间的应用中的路由,名称写作 [first:product] (示例 02);
- 第 40–41 行:重定向到另一个站点:地址按原样使用。[redirect] 首先检查该字符串是否是路由名称;如果不是,则含有斜杠或句点的字符串会被视为地址(否则就是错误)。
使用 [curl] 得到的响应(不带选项时,它不会跟随重定向):
头 [Location] 包含视图提供的地址,它是相对于站点的:浏览器会用当前页面的协议、主机和端口对它进行补全。响应没有响应体。[-L] 选项属于 [curl] ,它会像浏览器一样跟随重定向:
现在我们来比较这两个计算出的重定向,其目标中包含一个问号,在 URL 中编码为 [%3F] (未编码的 [?] 会开始 URL 的参数):
[Django] 在把路由参数传给视图之前先对它进行了解码:[destination] 等于 [a?b]。第一个视图把它原样放回 URL 中:[/page/a?b],浏览器会把它解释为路径 [/page/a] 后面跟着参数 [b]。第二个视图走命名路由,其参数会被重新编码为:[/page/a%3Fb]。跟随这些重定向:
只有第二个会通向正确的页面。因此有这样的规则:包含可变值的地址要根据其路由的名称来构造([redirect("page", name=...)]、[reverse("page", kwargs={"name": ...})],以及在模板中使用标签 [{% url %}]),绝不要通过拼接字符串来构造。在浏览器中你只会看到最终页面;地址栏显示的是新的 URL:

还存在另外两个重定向代码:303([See Other])和 307([Temporary Redirect]),它们要通过自己生成响应来获得:[HttpResponseRedirect(url, status=303)]。在 POST 请求之后,代码 302 和 303 会让浏览器向新地址发送 GET 请求,而 307(以及 308,即其永久版本)则会让浏览器重复 POST 请求。示例 20 将在 POST 之后使用重定向。
2.5. 示例 05:请求对象和响应对象
到目前为止,视图只使用了路由参数,并返回一行响应。视图还可以访问当前请求,并逐段构建它的响应。该应用名为 [http_app] (而不是 [http],后者是 [Symfony] 课程中的叫法:[http] 已经是 [Python] 标准库中一个包的名称,我们的包会把它覆盖);它的路由挂载在前缀 [http/] 之下:
- 第 11–20 行:视图的 [request] 参数(我们此前还没有用过它)是当前请求的 [HttpRequest] 对象。它的属性和方法提供了其中包含的全部信息:HTTP 方法([method])、路径([path])、完整 URL([build_absolute_uri()],它会补上协议、主机和端口)以及头([headers],一个键不区分大小写的字典:[headers.get("user-agent")] 会得到相同的结果)。[META] 属性是一个字典,包含 WSGI 服务器传来的所有变量:头(名称形如 [HTTP_USER_AGENT])、原始参数(URL 中位于 [?] 之后的部分,即 [QUERY_STRING])、客户端的 IP 地址([REMOTE_ADDR])……字典的 [get] 方法返回某个键的值,如果键不存在则返回 [None] ,而 [d["key"]] 则会抛出 [KeyError] 异常。这些参数将在下一章中逐个讲解;
- 第 24–28 行:响应先被创建,然后再填充内容:[HttpResponse] 对象可以当作头字典来处理。[response["X-Example"] = ...] 添加头 [X-Example] (按照惯例,应用专属的头通常以 [X-] 开头);[response.headers] 也可以访问这些头;
- 第 32–35 行:一次性构造的响应:响应体、状态码和头。函数调用可以跨越多行;在括号内,[Python] 会忽略换行;
- 第 40–49 行:分块发送的响应(流式传输)。[StreamingHttpResponse] 对象接收的不是字符串,而是一个迭代器:一个依次产生各个片段的对象。这里它是生成器函数的结果:生成器函数是包含语句 [yield] 的函数。调用 [chunks()] 并不会执行这个函数:它返回一个生成器,每请求一个片段,生成器就逐步执行该函数,从一个 [yield] 执行到下一个。这个函数定义在视图内部:这在 [Python] 中是允许的。服务器先发送状态码和头,然后每个片段一经 生成就立即发送。响应的长度事先并不知道。这对于一点一点生成的很长的响应很有用(例如大型 CSV 文件)。但是一旦第一个片段发出,状态码就无法更改:这里,函数在第一个片段之后抛出了异常。这就是要避免的错误:已经开始的响应无法再变成错误响应。
[ReadableJson] 中间件就是示例 03 中的那个。响应如下:
URL 两边的引号可以防止终端解释字符 [&]。在浏览器中,头 [User-Agent] 是浏览器自己的头。
一秒钟后,[curl] 停止:服务器已关闭连接。客户端收到了 200 状态码和一个被简单截断的响应体,无从得知发生了错误。[Django] 对此无能为力:抛出异常时,其视图早已完成工作(它已返回响应及其生成器),是服务器在请求下一个数据块时收到了该异常。只有服务器控制台会显示这一点,其调用栈始于 [Python] 的 WSGI 服务器,而不是 [Django]:
2.6. 示例 06:共享服务
视图本身不应包含应用逻辑,而应把这些逻辑委托给服务——即执行特定任务的对象(例如读取产品数据或计算购物车总额)。多个视图往往使用同一个服务。[Symfony]与 [Spring] 或 [ASP.NET Core] 一样,为此提供了服务容器,由它创建服务并自动提供给需要它们的对象:这就是依赖注入。[Django] 没有这样的机制。在 [Python] 中,模块只在首次导入时执行一次,此后所有导入它的代码得到的都是同一个模块:因此,存放在模块变量中的对象本来就已在整个应用中共享。模块起到了容器的作用。接下来要做的是组织代码,使视图依赖于契约而不是实现。示例 06 按领域(产品、客户)组织代码,也就是在 [Django] 中按应用组织:
2.6.1. 产品:products/viewmodels.py
- 第 7 行:一个不可变数据类(见示例 03)。不可变对象可以在代码的多个部分之间以及多次查询之间安全地共享;
- 第 9–12 行:属性及其类型。价格是整数,即以美分为单位的价格(150 表示 1.50 欧元)。浮点数,即 [float] 类型,以二进制表示,无法精确表示 0.1 或 3.2(在二进制中这些数有无限多位):对 [float] 类型的价格求和可能得到 5.500000000000001。而整数之和始终是精确的。[Python] 还提供了 [Decimal] 类型(模块 [decimal]),它以十进制进行精确计算:[Django] 的 ORM 正是用它来表示数据库中的十进制列。
2.6.2. 服务契约及其实现:products/services.py
- 第 3、10 行:服务契约,即它能做什么,而不规定怎么做。[Java] 或 [C#] 会用接口来定义它;[Python] 则用一个抽象类来定义,该类继承自 [ABC] 类(Abstract Base Class,抽象基类),位于 [abc] 模块中。不能用抽象类创建对象;
- 第 11–18 行:契约方法,用 [@abstractmethod] 标记:子类必须实现所有这些方法,否则同样无法创建该子类的对象。它们的方法体 [...] (即对象 [Ellipsis])什么也不做,它的存在只是因为 [Python] 函数必须有方法体。类型注解描述了契约:[find_all] 返回产品列表([list[Product]]);[find_by_id] 接受一个整数,返回一个产品,如果产品不存在则返回 [None] ([Product | None]);
- 第 22 行:实现类继承该契约;
- 第 23–30 行:构造函数。[self._products] 是对象的一个属性;前导下划线是 [Python] 中表示“私有”的约定:没有任何机制阻止其他模块使用它,但使用者知道不应该这样做。第 25 行在控制台显示一条消息,以便我们看到服务是何时创建的;
- 第 32–34 行:该方法返回产品列表的副本([list(...)] 创建一个新列表):调用方可以修改它而不影响服务的数据([Product] 对象本身并未被复制,但它们是不可变的);
- 第 36–38 行:[(p for p in self._products if p.id == id)] 是一个生成器表达式,类似于示例 03 中的列表推导式:它逐个生成标识符为 [id] 的产品。函数 [next] 返回生成的第一个元素,如果没有任何元素,则返回其第二个参数的值([None])。
2.6.3. 服务提供者:products/provider.py
视图不会自己创建服务:它们向一个函数(即提供者)请求服务,由该函数决定创建哪个实现,并确保只创建一个:
- 第 5 行:[django.conf.settings] 提供对应用设置的访问,这些设置来自 [config/settings.py] 文件并补充了默认值:[settings.DEBUG]、[settings.LANGUAGE_CODE]……应用中的每个模块都是这样读取其配置的;
- 第 6 行:[import_string] 导入以字符串形式给出完整路径的对象:[Django] 就是这样根据 [MIDDLEWARE] 配置找到中间件的;
- 第 14–18 行:提供者函数。它读取 [PRODUCTS_SERVICE] 配置中所选类的名称,加载该类,创建该类的一个对象([cls()]),并返回它。装饰器 [@cache] 来自标准库的 [functools] 模块,它缓存第一次调用的结果:后续调用直接返回同一个对象,而不再执行该函数。因此,服务只在第一次调用时创建一次,之后只要服务器在运行,就由所有视图和所有请求共享。这在其他地方被称为单例。它还是惰性的:只要没有视图请求它,它就不会被创建。注解
***[-> ProductsService]*** 指定了返回类型:是契约,而不是实现。
剩下的就是在文件 [config/settings.py] 中选择实现:
- 第 25 行:一个应用专属的设置。[Django] 允许在设置文件中使用任何大写命名的变量,并通过 [django.conf.settings] 使其可用。服务的实现仅在此处、也只在此处选择。若要切换到从数据库读取数据的实现,只需修改这一行:只了解契约的视图无需任何改动。这就是依赖注入的好处,而这里无需容器即可实现:应用的每个部分都依赖于契约,由唯一的一处位置决定实现。包 [products] 在配置 [products] 中也被称为 [INSTALLED_APPS] (第 15 行):[Django] 在启动时导入它。
2.6.4. 产品视图和客户视图
- 第 8 行:视图导入的是提供者,而不是 [InMemoryProductsService] 类;它并不知道产品存放在内存中;
- 第 12–16 行:视图把工作委托给服务。产品列表被转换为字典列表,进而成为 JSON 类型的数组(示例 03);
- 第 20–24 行:未知的产品返回 404 响应,并附带一条 JSON 格式的消息。路由中的 [<int:id>] 转换器(文件 [products/urls.py])确保 [id] 是整数。
- 第 7、12 行:第二个应用使用与产品应用相同的服务,它从 [products] 包中导入该服务。提供者向它返回的是同一个对象;
- 第 14 行:[sum] 对生成器表达式产生的元素求和;
- 第 15–18 行:[len] 返回列表中元素的个数。总额以欧分返回并格式化为欧元:来自 [number_format] 的 [django.utils.formats] 模块,按应用语言的惯例写出带两位小数的数字:英语使用句点作为小数分隔符。除法 [total / 100] 产生一个 [float],但这仅用于显示:实际计算是用整数完成的。示例 16 将演示一种好得多的金额格式化方式。
最后谈谈这个共享服务的生命周期。正如我们在示例 01 中看到的:在 [Python] 中,应用在两次请求之间一直保留在内存中。因此,该服务在整个应用中是唯一的:下一个请求会得到与上一个请求相同的对象,任何请求修改的数据对此后的所有请求都是可见的。对于只读取静态数据的服务(如这个服务),这是理想的:它只创建一次。对于数据会变化的服务(示例 20 中的任务列表),这很方便(数据在请求之间得以保留,无需文件或数据库),但必须注意两点:两个同时发生的请求可能同时修改数据,因此必须用锁加以保护;并且数据会在服务器关闭时(或在代码修改后重启时)丢失。这与 [PHP] 完全相反,在 PHP 中每个请求都有自己的服务,每次都会重新创建。
2.6.5. 执行
服务器控制台会在第一个调用该服务的请求时显示构造函数的消息,而且仅对该请求显示:
服务器控制台:
该服务只创建了一次,供三个请求和两个应用共同使用。如果修改了某个项目文件,服务器会重启,该消息会在下一个请求时再次出现。