Django-入门指南-全-

Django 入门指南（全）

原文：Beginning Django

协议：CC BY-NC-SA 4.0

一、Django 框架介绍

Django 框架始于 2003 年，是由美国堪萨斯州劳伦斯的《世界日报》的 Adrian Holovaty 和 Simon Willison 完成的一个项目。2005 年，Holovaty 和 Willison 发布了该框架的第一个公开版本，并以比利时-法国吉他手坦哥·雷恩哈特的名字命名。

快进到 2017 年——Django 框架现在在 Django 软件基金会(DSF)的指导下运行，框架核心有超过 1000 个贡献者，有超过 15 个发布版本，有超过 3000 个专门设计用于 Django 框架的包。 ¹

Django 框架仍然忠实于它的起源，即模型-视图-控制器(MVC)服务器端框架，设计用于操作关系数据库。尽管如此，Django 仍然通过第三方包紧跟大多数 web 开发趋势，与非关系数据库(NoSQL)、实时互联网通信和现代 JavaScript 实践等技术一起运行。所有这些都说明了一点，Django 框架现在是许多组织选择的 web 开发框架，包括照片共享网站 Instagram ² 和 Pinterest³；公共广播系统⁴；美国国家地理⁵；而借助这本书，你的组织！

在这一章中，你将学习 Django 框架设计原则，这是理解日常使用 Django 框架的关键。接下来，您将学习如何以各种方式安装 Django:作为 tar.gz 文件，使用 pip，使用 git，以及使用 virtualenv。

一旦安装了 Django 框架，您将学习如何启动一个 Django 项目，以及如何用关系数据库来设置它。接下来，您将了解 Django 框架中的核心构件——URL、模板和应用——以及它们如何相互协作来设置内容。最后，您将学习如何设置 Django 管理站点，这是一个基于 web 的界面，用于访问连接到 Django 项目的关系数据库。

Django 框架设计原则

如果你在 web 开发领域工作了足够长的时间，你最终会得出这样的结论:你可以用任何 web 框架和编程语言产生相同的结果。但是，虽然您实际上可以产生相同的结果，但是差异很大的是您创建解决方案所花费的时间:创建原型的时间、添加新功能的时间、进行测试的时间、进行调试的时间、部署到规模的时间等等。

从这个意义上来说，Django 框架使用了一套设计原则，与许多其他 web 框架相比，它产生了最有生产力的 web 开发过程之一。注意，我并不是说 Django 是银弹(例如，最好的原型，最具伸缩性)；我是说，最终，Django 框架包含了一组设计原则和权衡，使其成为构建大多数大中型 web 应用所需特性的最有效的框架之一。

现在，虽然你可能认为我有偏见——毕竟我正在写一本关于这个主题的书——我将首先列出这些设计原则，这样你可以更好地理解是什么赋予了 Django 框架这种优势。

不重复自己(干)的原则

重复可能有助于强调一个观点，但是对于 web 开发来说，这只会导致额外的耗时工作。事实上，web 开发的本质是跨多个交互层(例如，HTML 模板、业务逻辑方法和数据库)进行操作，这本身就是重复的。

Django 框架确实试图强迫你不要重复自己，所以让我们看看 Django 是如何强制不要重复自己的，以及为什么这是一件好事。

假设您想要构建一个 coffeehouse 应用来发布关于商店的信息，并为客户提供一个联系表单。你需要做的第一件事是确定商店和联系表格需要什么样的信息。图 1-1 展示了每个实体的两个 Django 模型的实体模型。

图 1-1。

Django models for store and contact entities

请注意图 1-1 中的 Django 模型每个都有不同的字段名称和数据类型来限制值。例如，语句name = models.CharField(max_length=30)告诉 Django 商店名称应该最多包含 30 个字符，而语句email = models.EmailField()告诉 Django 联系人实体应该包含有效的电子邮件值。如果咖啡馆像大多数 web 应用一样，您通常会为商店和联系人实体做以下事情:

创建关系数据库表来保存实体信息。
创建业务逻辑以确保实体符合需求。
创建 HTML 表单以允许为实体提交数据。
创建允许管理用户访问数据库中实体的界面。
创建 REST 服务来公开移动应用版本的实体。

完成这最后一个任务列表的关键是，您可能会在数据库定义语言(DDL)、HTML 表单、业务验证逻辑和 URL 等方面重复许多类似的信息(例如名称、值限制),这一过程不仅耗时，而且容易出错。

基于像models.CharField(max_length=30)这样的语句，您可以生成一个 HTML 表单输入，一个 DDL 语句，并自动验证信息只包含 30 个字符，这不是更容易吗？这正是 Django 的干设计原则所做的。

图 1-2 展示了与图 1-1 相同的 Django 模型，以及您可以从相同的模型中生成的各种构造，而无需重复。

图 1-2。

Django models create separate constructs based on DRY principle

正如您在图 1-2 中看到的，代表 Django 模型的实体能够生成向公众展示的 HTML 表单、管理实体的管理界面、实施实体值的验证逻辑，以及生成代表实体的数据库表的 DDL。

虽然现在讨论从 Django 模型生成这种结构的实际技术还为时过早，但不用说，这比在 HTML 表单、DDL、验证逻辑和其他位置跟踪同一事物(例如，姓名、电子邮件)的多个引用要简单得多。

从这个意义上说，Django 真正帮助你在一个地方定义事物，而不必在其他地方重复它们。注意，总是有可能重复自己来获得定制的行为，但是在默认情况下，Django 在几乎所有你用它做的事情中都执行 DRY 原则。

显性比隐性好

Django 使用的编程语言 Python 有一个类似咒语的声明，称为“Python 的禅”，被定义为该语言的 Python 增强建议(PEP)的一部分，特别是 PEP 20。PEP 20 中的一个声明是“显式比隐式更好”,并且 Django 是基于 Python 的，这个原则也被牢记在心。

显式导致 web 应用容易被更多的人理解和维护。对于最初没有编写 web 应用的人来说，添加新功能或理解 web 应用背后的逻辑可能已经够难了，但是如果您加入了具有隐式行为的 mix 构造，用户在试图弄清楚隐式地做了什么时只会面临更大的挫折。Explicit 确实需要更多的输入工作，但是当您将它与您可能面临的调试或解决问题的潜在努力相比较时，这是非常值得的。

让我们快速看一下 Django 在一个跨不同 MVC 框架使用的通用 web 开发结构中的显式性:一个视图方法。视图方法充当 MVC 框架中的 C(controller ),负责处理传入的请求，应用业务逻辑，然后用适当的响应路由请求。

为了更好地理解这种明确性，我将给出一个 Django 视图方法和一个等价的 Ruby on Rails 视图方法，这两个方法执行相同的逻辑，即通过给定的 id 获取存储并将响应路由到模板。以下代码片段是 Ruby on Rails 版本；请注意带有#的行，它们是注释，表示正在发生的事情。

class StoresController < ApplicationController
  def show
    # Automatic access to params, a ruby hash with request parameters and view parameters
    @store = Store.find(params[:id])
    # Instance variables like @store are automatically passed on to view template
    # Automatically uses template views/stores/show.html.erb
  end
end

尽管非常简洁，但请注意访问数据、将数据传递给模板和分配模板的过程中的所有隐式行为。下面的代码片段是一个等价的 Django 视图方法。

# Explicit request variable contains request parameters
# Other view parameters must be explicitly passed to views
def detail(request, store_id):
    store = Store.objects.get(id=store_id)
    # Instance variables must be explicitly passed on to a view template
    # Explicit template must be assigned
    return render(request, 'stores/detail.html', {'store': store})

请注意，在最后这段代码中，没有猜测输入参数来自哪里，它们被显式声明为 view 方法中的参数。此外，值被显式传递给模板，并且模板也被显式声明，因此逻辑对新来者来说更加友好。

Ruby on Rails 视图方法的隐含性通常被称为“魔力”,甚至被许多人认为是一种特性。之所以称之为‘魔法’，是因为某些行为是在幕后提供的。然而，除非你对框架和应用了如指掌，否则很难确定为什么会发生某些事情，这使得修复或更新变得更加困难。因此，尽管“魔术”可能在开始时为您节省几分钟或几个小时的开发时间，但它最终会花费您几个小时或几天的维护时间。

所以就像在 Python 中一样，Django 框架总是偏爱显式方法而不是隐式技术。

需要指出的是，显式不等于冗长或多余。虽然与隐式驱动的 web 框架(例如 Rails)相比，您最终肯定会在 Django 中键入更多的代码，但正如在前面的 DRY principle 部分中所描述的那样，Django 框架尽力避免在 web 应用中引入不必要的代码。

最后，显式也不意味着没有默认值。Django 框架尽可能使用合理的缺省值，只是在不明显的地方不使用缺省值。本质上，Django 框架使用默认值，但是避免使用会产生“神奇”结果的默认值。

松散耦合架构

Django 框架是一个 MVC 框架，跨多个层运行(例如，HTML 模板、业务逻辑方法和数据库)。然而，Django 非常注意维护跨这些层运行的所有组件的松散耦合架构。

松散耦合意味着组成 Django 应用的各个部分之间没有严格的依赖关系。例如，在 Django 中，直接从 HTML 模板提供内容是完全有效的，不需要使用业务逻辑或建立数据库。就像在 Django 中一样，放弃使用 HTML 模板并直接从业务逻辑方法返回原始数据也是完全有效的(例如，对于 REST 服务)。

本章后面的“设置内容:理解 URL、模板和应用”一节将更详细地举例说明 Django 的松散耦合架构是如何工作的。

安装 Django

安装 Django 框架有多种方法。你可以从 Django 的主站点 ⁷ 下载 Django，然后像安装普通的 Python 应用一样安装它。您也可以通过操作系统(OS)包管理工具下载并安装 Django，比如 Linux 发行版上提供的apt-get。

另一个选择是通过 Python 包管理器pip下载安装 Django。还有一种方法是直接在 github 上安装 Django。⁸Django 安装选项列表及其优缺点如表 1-1 所示。

表 1-1。

Django installation options - Pros and Cons

| 方法 | 赞成的意见 | 骗局 | | --- | --- | --- | | 使用`pip` Python 包管理器下载/安装。(推荐选项) | 允许在虚拟 Python 环境中安装。依赖关系是自动处理的。 | 最新版本可能不可用。 | | 从主站点下载为`tar.gz`文件。 | 最容易获得最新的 Django 稳定版本。 | 需要手动下载和安装。需要额外管理 Django 依赖项(如果不使用 pip)。 | | 从 Git 下载。 | 访问最新的 Django 特性。 | 可能包含 bug。需要额外管理 Django 依赖项(如果不使用 pip)。 | | 从操作系统软件包管理器下载/安装(`apt-get`)。 | 易于安装。依赖关系是自动处理的。 | 最新版本可能不可用。安装在全球 Python 环境中。 |

正如表 1-1 中所强调的，安装 Django 的推荐选项是使用 Python pip包管理器，因为它提供了最大的灵活性。接下来，我将描述使用这种方法安装 Django 的每个步骤，更重要的是如何启动并运行pip。

一旦我完成了这些步骤，我还将描述从一个tar.gz文件和从 git——使用pip——安装 Django 的步骤，如果您想尝试最新的 Django 特性，这可能会很有帮助。

安装 Python(先决条件)

由于 Django 是基于 Python 构建的，所以首先需要安装 Python 来运行 Django。最新的 Django 长期版本(LTS)是 1.11 版，这也是本书的重点。Django 1.11 要求您要么拥有 Python 2.7.x 版本，要么拥有 Python 3.4 或更高版本(3.5 或 3.6)。

如果这是你第一次使用 Python，注意 Python 2 和 Python 3 有很大的不同是很重要的。虽然 Python 3 确实是未来，但要知道，自 2008 年第一个 Python 3 版本问世以来，未来就一直在酝酿之中，Python 2 一直顽固不化，直到 2016 年 12 月 Python 2.7.13 才问世。

那么 Django 应该用 Python 2 还是 Python 3 呢？就 Django 的核心而言，它兼容两者，因此您可以轻松地在 Python 2 和 Python 3 之间切换。当涉及到第三方 Python 包和您计划自己编写的 Django Python 代码时，事情变得有点棘手。

虽然许多第三方 Python 包已经升级到可以在 Python 3 上运行，但这个过程一直很缓慢。正如我已经指出的，Python 3 的开发已经进行了将近 10 年，所以请注意，如果您选择 Python 3 路线，您可能会遇到无法与 Python 3 兼容的第三方 Python 包。

当涉及到您自己的 Django 应用代码时，理想的选择是让您的代码兼容 Python 2 和 Python 3——就像 Django 的核心一样——这并不难，我将在整本书中使用这种技术。侧栏包含更多关于编写 Python 2 和 Python 3 兼容代码的细节。

现在，如果你想坚持使用 Python 2，请注意 Django 1.11 将是最后一个支持 Python 2 的 Django 版本——计划支持到 2020 年 4 月左右——所以如果你最终升级到比 Django 1.11 更高的版本，你还需要将所有应用代码升级到 Python 3——这就是为什么我推荐 Python 2 和 Python 3 双重兼容技术。如果你想坚持使用 Python 3，那是未来的趋势，只是要注意，如前所述，一些第三方包可能无法与 Python 3 兼容。

Django Compatibility With Python 2 and Python 3

Django 使用 6 个 ^{9 个} 来运行 Python 2 和 Python 3 兼容的逻辑。Six 是一组实用程序，涵盖了 Python 2 和 Python 3 之间的差异，允许相同的逻辑在 Python 2 和 Python 3 中同等地运行。Django 框架的内部——很少需要检查或修改——已经使用了这种技术。

但是，如果您计划编写与 Python 2 和 Python 3 都兼容的 Django 应用代码，那么您需要对如何编写代码有更多的了解。Django 发布了自己的关于各种语法和技术的指南，您需要遵循这些指南来使 Django 应用代码与 Python 2 和 Python 3、 ¹⁰ 技术一起工作，这些技术也在整本书中使用。

如果您使用 Unix/Linux 操作系统，Python 很可能安装在您的系统上。如果您在 Unix/Linux 终端上键入which python，它会返回一个响应(例如/usr/bin/python)，这表示 Python 可执行文件的位置，如果没有响应，则表示 Python 可执行文件在系统上不可用。

如果您的系统上没有 Python，并且您使用的是 Debian 或 Ubuntu Linux 发行版，那么您可以使用 OS package manager apt-get 通过键入:apt-get install python来安装 Python。如果您的 Unix/Linux 发行版不是 Debian 或 Ubuntu，并且您需要安装 Python，请查阅您的 Unix/Linux 文档以获得可用的 Python 包，或者从 http://python.org/download/ 下载 Python 源代码来进行安装。

如果你有一个运行在 Windows 操作系统或 macOS 上的系统，Python 安装程序可以从 http://python.org/download/ 下载。

无论您的系统是什么操作系统，一旦您完成 Python 安装，请确保 Python 安装正确，并且可以从系统的任何地方访问。打开一个终端并键入python，您应该会进入一个 Python 交互式会话，如清单 1-1 所示。

[user@∼]$ python
Python 2.7.12 (default, Nov 19 2016, 06:48:10)
[GCC 5.4.0 20160609] on linux2
Type "help", "copyright", "credits" or "license" for more information.
Listing 1-1.Python interactive session

如果您无法进入 Python 交互式会话，请查看 Python 安装过程，因为您将无法继续以下部分。

更新或安装 pip 软件包管理器(先决条件)

为了使 Python 包的安装和管理更容易，Python 使用了一个名为 pip 的包管理器。如果您使用的是 Python 2.7.9(或更高版本的 2.x 分支)或 Python 3.4(或更高版本的 3.x 分支)，默认情况下会安装 pip。现在让我们在您的系统上升级 pip，如清单 1-2 所示，如果您的系统上没有 pip，我将简要说明如何获得它。

[user@∼]$ pip install --upgrade pip
Collecting pip
  Downloading pip-9.0.1-py2.py3-none-any.whl (1.3MB)
Installing collected packages: pip
  Found existing installation: pip 8.1.1
Successfully installed pip-9.0.1
Listing 1-2.Update pip package manager

正如您在清单 1-2 中看到的，为了更新 pip，您调用带有参数install --upgrade pip的pip可执行文件。在执行时，pip 通过提供的名称搜索一个包——在本例中是 pip 本身——下载它，并在已经安装的情况下执行升级。如果您系统上的安装输出类似于清单 1-2 中的输出——没有任何错误——您已经成功更新了 pip。

如果您看到一个错误，如程序“pip”当前未安装或 pip 未找到，这意味着您的 Python 安装没有配备 pip。在这种情况下，您需要通过下载 https://bootstrap.pypa.io/get-pip.py 来安装 pip 可执行文件，然后使用命令python get-pip.py执行下载的文件。一旦安装了pip可执行文件，运行清单 1-2 中的 pip 更新程序。

有了系统上的 pip，您就可以进入下一步了。

安装 virtualenv(可选先决条件)

Virtualenv 对于开发 Django 应用并不重要，但是我强烈建议您使用它，因为它允许您在单个系统上创建虚拟 Python 环境。通过使用虚拟 Python 环境，应用可以在独立于其他 Python 应用的“沙箱”中运行。最初，virtualenv 似乎没有什么好处，但它对于将开发环境复制到生产环境以及避免不同应用之间可能出现的版本冲突等任务来说，可能会有巨大的帮助。

没有 virtualenv，您仍然可以使用 pip 继续安装 Django 和任何其他 Python 包，但问题是所有包都安装在全局 Python 安装下。最初这看起来很方便，因为在全局 Python 安装中只需要安装一次包。但是如果你思考下面的一些问题，就没那么方便了。

如果在你的第一个项目之后发布了一个新的 Django 版本，而你想开始第二个项目，会发生什么？您是升级第一个项目以便在新的 Django 版本上运行，还是启动第二个项目，就好像新的 Django 版本不存在一样？第一个选项需要额外的工作，而第二个选项需要您在过时的 Django 版本上进行开发。通过使用虚拟 Python 环境，可以避免这个问题，因为每个项目都可以独立运行自己的 Django 版本。

如果您考虑到任何 Python 包的潜在版本冲突，您就会明白为什么我推荐您使用 virtualenv。许多 Python 包都有特定的版本依赖关系(例如，包 A 依赖于包 B 版本 2.3 和包 C 版本 1.5)。如果您用特定的交叉依赖版本更新一个新的包，如果您使用的是全局 Python 安装，那么中断 Python 安装是非常容易的。使用 virtualenv，您可以拥有多个 Python 安装，而不会相互干扰。

既然我已经解释了 virtualenv 的好处，让我们用 pip 安装virtualenv可执行文件，如清单 1-3 所示。

[user@∼]$  pip install virtualenv
Downloading/unpacking virtualenv
  Downloading virtualenv-15.1.0.tar.gz (1.8Mb): 1.8Mb downloaded
  Running setup.py egg_info for package virtualenv
  Installing collected packages: virtualenv
  Running setup.py install for virtualenv
  Installing virtualenv script to /usr/local/bin
  Installing virtualenv-2.7 script to /usr/local/bin
Successfully installed virtualenv
Cleaning up...
Listing 1-3.Install virtualenv

with pip

如清单 1-3 所示，pip自动下载并安装所请求的包。类似于pip可执行文件，还安装了一个virtualenv可执行文件，可以从系统的任何地方访问。virtualenv可执行文件允许您创建虚拟 Python 环境。清单 1-4 展示了如何用virtualenv创建一个虚拟的 Python 环境。

[user@∼]$ virtualenv --python=python3 mydjangosandbox
Already using interpreter /usr/bin/python3
Using base prefix '/usr'
New python executable in /mydjangosandbox/bin/python3
Also creating executable in /mydjangosandbox/bin/python
Installing setuptools, pkg_resources, pip, wheel...done.
Listing 1-4.Create virtual Python environment

with virtualenv

virtualenv可执行文件接受几个参数。清单 1-4 中的任务利用了--python标志，它告诉 virtualenv 基于python3可执行文件创建一个虚拟 Python，从而创建一个 Python 3 虚拟环境。当一个操作系统上有多个 Python 版本(例如 Python 2 和 Python 3)并且需要指定创建 virtualenv 的 Python 版本时，这是一个常见的选项。可以省略--python标志；请注意，这样做 virtualenv 是用默认的操作系统python可执行文件创建的。

默认情况下，virtualenv 会创建一个原始的虚拟 Python 环境，就像您最初进行 Python 全局安装时的环境一样。在 virtualenv 参数之后，您只需要为虚拟 Python 环境的名称指定一个参数，在清单 1-4 的情况下是mydjangosandbox。在执行时，virtualenv 创建一个包含虚拟 Python 环境的目录，其内容如清单 1-5 所示。

+<virtual_environment_name>
|
|
+---+-<bin>
|   |
|   +-activate
|   +-easy_install
|   +-pip
|   +-python
    +-python-config
|   +-wheel
|
+---+-<include>
|
+---+-<lib>
|
+---+-<local>
†

|
+---+-<share>
Listing 1-5.Virtual Python environment directory structure

Tip

取决于用于创建 virtualenv 的 Python 版本，bin 目录可以包含同一命令的多个别名或版本(例如，除了python、python2.7和python3；除了activate、activate.csh、activate_this.py。

Note

本地文件夹仅包含在 Python 2 virtualenv 中，并链接到虚拟目录的顶级目录以模拟 Python 安装。

如清单 1-5 所示，虚拟 Python 环境的目录结构类似于全局 Python 安装。bin目录包含虚拟环境的可执行文件，include目录链接到全局 Python 安装头文件，lib目录是全局 Python 安装库的副本，也是安装虚拟环境的包的地方，share目录用于放置共享的 Python 包。

虚拟环境最重要的部分是bin目录下的可执行文件。如果您使用这些可执行文件中的任何一个，比如pip、easy_install、python,或wheel,，它们将在虚拟 Python 环境的上下文中执行。例如，bin文件夹下的pip为虚拟环境安装软件包。类似地，在bin文件夹下的python可执行文件上运行的应用只能加载安装在虚拟 Python 环境中的包。这就是我之前提到的“沙盒”行为。

尽管访问不同的虚拟 Python 环境和可执行文件是一个强大的特性，但是对于多个虚拟 Python 环境和全局 Python 安装本身的可执行文件使用不同的pip和python可执行文件，会由于长的访问路径和相对路径而变得混乱。

出于这个原因，virtualenv 有一个加载虚拟环境的机制，这样，如果您从系统上的任何地方执行pip、python,或任何其他可执行文件，就会使用来自所选虚拟环境的可执行文件(而不是默认的全局 Python 安装可执行文件)。这是通过bin目录中的activate可执行文件实现的，清单 1-6 展示了这个过程。

[user@∼]$ source ./bin/activate
[(mydjangosandbox)user@∼] $
# NOTE: source is a Unix/Linux specific command, for other OS just execute activate
Listing 1-6.
Activate

virtual Python environment

请注意清单 1-6 中调用activate可执行文件后，命令提示符如何在括号中添加虚拟环境名称。这意味着虚拟 Python 环境mydjangosandbox的bin目录下的可执行文件将优先于全局 Python 安装中的文件使用。要退出一个虚拟 Python 环境，只需键入deactivate就可以回到使用全局 Python 安装可执行文件。

正如您现在所了解的，virtualenv 透明地工作，允许您维护不同的 python 安装，每个安装都有自己的一组可执行文件，如主 Python 解释器和 pip 包管理器。您只需要在虚拟环境之间切换，以便在适当的虚拟环境中安装和运行 Python 应用。

Note

在以后的章节中，我不会提到 virtualenv(例如mydjangosandbox)，因为它与 Django 没有直接关系。虽然我建议您使用 virtualenv，但是如果您希望继续使用全局 Python 安装python和pip可执行文件来处理任何事情，或者如果您希望让虚拟 Python 环境拥有自己的可执行文件以使 Python 应用管理更容易，我会让您自己决定。因此，当你在书中看到 Python 可执行文件时，假设它们是全局的或者来自 virtualenv，无论你使用哪个。

安装 Django

一旦您的系统上运行了所有以前的工具，实际的 Django 安装就非常简单了。清单 1-7 展示了如何使用 pip 安装 Django。

[user@∼]$ pip install Django==1.11
Downloading/unpacking Django==1.11
Collecting Django==1.11
  Downloading Django-1.11-py2.py3-none-any.whl (6.9MB)
    100% |███████████████████| 6.9MB 95kB/s
Collecting pytz (from Django==1.11)
  Downloading pytz-2017.2-py2.py3-none-any.whl (484kB)
    100% |███████████████████| 491kB 735kB/s
Installing collected packages: pytz, Django
Successfully installed Django-1.11 pytz-2017.2
Listing 1-7.Install Django with pip

清单 1-7 中的pip install任务使用Django==1.11语法告诉 pip 下载并安装 Django 1.11 版本。使用同样的语法，您可以安装任何特定的 Django 版本。如果您不指定软件包版本，pip 会下载并安装指定软件包的最新可用版本。

有时 Django 版本可能需要几天才能通过 pip 获得，在这种情况下，您会收到一个错误。在这种情况下，您可以直接从 Django 主网站 https://www.djangoproject.com/download/ 下载该版本。一旦下载了 tar.gz 格式的发布文件，就可以使用 pip 进行安装，如清单 1-8 所示。

[user@∼]$ pip install /home/Downloads/Django-1.11.tar.gz
Processing /home/Downloads/Django-1.11.tar.gz
Collecting pytz (from Django==1.11)
  Using cached pytz-2017.2-py2.py3-none-any.whl
Building wheels for collected packages: Django
  Running setup.py bdist_wheel for Django ... done
  Stored in directory: /home/ubuntu/.cache/pip/wheels/56/bf/24/f44162e115f4fe0cfeb4b0ae99b570fb55a741a8d090c9894d
Successfully built Django
Installing collected packages: pytz, Django
Successfully installed Django-1.11 pytz-2017.2
Listing 1-8.Install Django from local tar.gz file with pip

请注意清单 1-8 中 pip 如何能够直接从本地文件系统上的压缩文件安装 Python 包。

从 Git 安装 Django

如果您想使用 Django 中最新的功能，那么您需要从它的 Git 存储库中安装 Django。Git 存储库包含对 Django 的最新更改。尽管 Django Git 版本可能会不稳定，但这是使用最新的 Django 特性进行开发或获取尚未在公开发行版中提供的问题的 bug 修复的唯一方法。

Note

您需要安装 Git 来执行以下任务。你可以在 http://git-scm.com/ 下载几个操作系统的 Git

就像前面的 pip 安装示例一样，pip 非常灵活，可以从 Git 安装 Django。在 Git 中使用 pip 有两种选择。您可以提供远程 Django Git 存储库，在这种情况下，pip 在本地克隆存储库，并在安装后丢弃它，如清单 1-9 所示。或者您可以在本地克隆 Django Git 存储库——稍后您可以在这里进行修改——然后运行 pip 进行安装，如清单 1-10 所示。

[user@∼]$ pip install git+https://github.com/django/django.git
Collecting git+https://github.com/django/django.git
  Cloning https://github.com/django/django.git to ./pip-31j_bcqa-build

Requirement already satisfied: pytz in /python/mydjangosandbox/lib/python3.5/site-packages (from Django==2.0.dev20170408112615)
Installing collected packages: Django
      Successfully uninstalled Django-1.11
  Running setup.py install for Django ... done
Successfully installed Django-2.0.dev20170408112615

Listing 1-9.Install Django from remote Git with pip

[user@∼]$ git clone https://github.com/django/django.git
Cloning into django...
remote: Counting objects: 388550, done.
remote: Compressing objects: 100% (19/19), done.
remote: Total 388550 (delta 5), reused 0 (delta 0), pack-reused 388531
Receiving objects: 100% (388550/388550), 158.63 MiB | 968.00 KiB/s, done.
Resolving deltas: 100% (281856/281856), done.
Checking connectivity... done.

# Assuming Django Git download made to /home/Downloads/django/
[user@∼]$ pip install /home/Downloads/django/
Processing /home/Downloads/django
Collecting pytz (from Django==2.0.dev20170408112615)
  Using cached pytz-2017.2-py2.py3-none-any.whl
Installing collected packages: pytz, Django
  Running setup.py install for Django ... done
Successfully installed Django-2.0.dev20170408112615 pytz-2017.2

Listing 1-10.Download Django from Git and install locally with pip

注意在清单 1-9 中，下载远程 Git 存储库的语法是git+后跟远程 Git 位置。在本例中， https://github.com/django/django.git 表示 Django Git 存储库。在清单 1-10 中，Django Git 存储库首先被本地克隆，然后用本地 Git 存储库目录的参数执行pip。

启动 Django 项目

要启动 Django 项目，您必须使用 Django 附带的django-admin可执行文件或django-admin.py脚本。在你安装 Django 之后，这个可执行文件和脚本应该可以从你系统上的任何目录中访问(例如，安装在一个 virtualenv 的/usr/bin/、/usr/local/bin/或/bin/目录下)。请注意，可执行文件和脚本提供了相同的功能；因此，今后我将交替使用django-admin这一术语。

django-admin提供了各种子命令，您将在 Django 项目的日常工作中广泛使用这些命令。但是您将首先使用的是startproject子命令，因为它创建了 Django 项目的初始结构。startproject子命令接收一个参数来表示项目的名称，如下面的代码片段所示。

#Create a project called coffeehouse
django-admin startproject coffeehouse
#Create a project called sportstats
django-admin startproject sportstats

Django 项目名称可以由数字、字母或下划线组成。项目名称不能以数字开头，只能以字母或下划线开头。此外，项目名称中不允许出现特殊字符和空格，这主要是因为 Django 项目名称是目录和 Python 包的命名约定。

在执行django-admin startproject <project_name>时，会创建一个名为<project_name>的目录，其中包含默认的 Django 项目结构。清单 1-11 显示了 Django 项目的默认结构。

+<BASE_DIR_project_name>
|
+----manage.py
|
+---+-<PROJECT_DIR_project_name>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
Listing 1-11.Django project structure

如果您检查目录布局，您会注意到有两个目录带有<project_name>值。我将顶层 Django 项目目录称为BASE_DIR，它包括manage.py文件和基于项目名称的其他子目录。我将把第二级子目录——包括__init__.py、settings.py、urls.py和wsgi.py文件——称为PROJECT_DIR。接下来，我将描述清单 1-11 中每个文件的用途。

manage.py。-运行项目特定任务。正如django-admin用于执行系统范围的 Django 任务一样，manage.py用于执行项目特定的任务。
__init__.py。- Python 文件，允许从 Python 包所在的目录中导入 Python 包。注意__init__.py不是 Django 特有的，它是一个在几乎所有 Python 应用中使用的通用文件。
settings.py。-包含 Django 项目的配置设置。
urls.py。-包含 Django 项目的 URL 模式。
wsgi.py。-包含 Django 项目的 WSGI 配置属性。WSGI 是在生产环境中部署 Django 应用的推荐方法(例如，面向公众)。开发 Django 应用不需要设置 WSGI。

Tip

给项目的BASE_DIR重新命名。在一个 Django 项目中有两个同名的嵌套目录会导致混淆，尤其是在处理 Python 包导入问题时。为了避免麻烦，我建议您将BASE_DIR重命名为不同于项目名称的名称(例如，重命名、大写或缩短名称，使其不同于PROJECT_DIR)。

Caution

不要重命名PROJECT_DIR。PROJECT_DIR名称被硬编码到一些项目文件中(例如settings.py和wsgi.py，所以不要更改它的名称。如果你需要重命名PROJECT_DIR，用一个新名字创建另一个项目更简单。

现在您已经熟悉了默认的 Django 项目结构，让我们在浏览器中查看默认的 Django 项目。所有 Django 项目都有一个内置的 web 服务器，当项目文件发生变化时，它可以在浏览器中观察应用。放在 Django 项目的BASE_DIR中——这里是manage.py文件——运行命令python manage.py runserver,如清单 1-12 所示。

[user@coffeehouse ∼]$ python manage.py runserver
Performing system checks...

System check identified no issues (0 silenced).

You have 13 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.

May 23, 2017 - 22:41:20
Django version 1.11, using settings 'coffeehouse.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Listing 1-12.Start Django development web server

provided by manage.py

如清单 1-12 所示，命令python manage.py runserver在http://127.0.0.1:8000/上启动一个开发 web 服务器——这是您系统上的本地地址。暂时不要担心'unapplied migration(s)'的消息，我将在接下来关于为 Django 项目建立数据库的章节中解决这个问题。接下来，如果你打开一个浏览器并指向地址http://127.0.0.1:8000/，你应该会看到 Django 项目的默认主页，如图 1-3 所示。

图 1-3。

Default home page for a Django project

有时更改 Django 开发 web 服务器的默认地址和端口很方便。这可能是因为默认端口正被另一个服务占用，或者需要将 web 服务器绑定到非本地地址，以便远程计算机上的某个人可以查看开发服务器。这很容易通过将端口或完整地址:端口字符串附加到python manage.py runserver命令来实现，如列表 1-13 中的各种示例所示。

# Run the development server on the local address and port 4345 (http://127.0.0.1:4345/)
python manage.py runserver 4345
# Run the dev server on the 96.126.104.88 address and port 80 (http://96.126.104.88/)
python manage.py runserver 96.126.104.88:80
# Run the dev server on the 192.168.0.2 address and port 8888 (http://192.168.0.2:8888/)
python manage.py runserver 192.168.0.2:8888
Listing 1-13.Start Django development web server on different address and port

为 Django 项目建立数据库

“开箱即用”状态下的 Django 被设置为与 SQLite 通信——一个包含在 Python 发行版中的轻量级关系数据库。所以默认情况下，Django 会自动为您的项目创建一个 SQLite 数据库。

除了 SQLite，Django 还支持其他流行的数据库，包括 PostgreSQL、MySQL 和 Oracle。连接到数据库的 Django 配置是在 Django 项目的settting.py文件中的DATABASES变量中完成的。

如果您打开 Django 项目的settings.py文件，您会注意到DATABASES变量有一个默认的 Python 字典，其值如清单 1-14 所示。

# Build paths inside the project like this: os.path.join(BASE_DIR, ...)
import os
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
    }
}

Listing 1-14.Default Django DATABASES dictionary

Tip

如果您想要最快的数据库设置，请使用 SQLite。

数据库设置本身可能很耗时。如果您想要最快的设置来为 Django 启用一个数据库，请保持之前的配置不变。SQLite 不需要额外的凭证或 Python 包来建立 Django 数据库连接。请注意，SQLite 数据库是一个平面文件，Django 基于NAME变量值创建 SQLite 数据库。在清单 1-14 的情况下，在 Django 项目的BASE_DIR下，作为一个名为db.sqlite3的平面文件。

Note

如果使用 SQLite，可以跳到本节的最后一步“测试 Django 数据库连接并构建 Django 基表”

Django DATABASES变量定义了键值对。每个键代表一个数据库引用名，值是一个带有数据库连接参数的 Python 字典。在清单 1-14 中，您可以观察到default数据库引用。default引用名用于表示在 Django 项目中声明的任何数据库相关操作都将针对该连接执行。这意味着，除非另有说明，所有数据库 CRUD(创建-读取-更新-删除)操作都是针对用default键定义的数据库进行的。

在这种情况下，默认数据库的数据库连接参数是键ENGINE和NAME，它们分别代表数据库引擎(即品牌)和数据库实例的名称。

Django 数据库连接最重要的参数是ENGINE值。与数据库相关联的 Django 应用逻辑是平台中立的，这意味着无论选择什么样的数据库，您总是以相同的方式编写数据库 CRUD 操作。然而，对不同数据库进行的 CRUD 操作之间存在微小的差异，这一点需要加以考虑。

Django 通过支持不同的后端或引擎来解决这个问题。因此，根据您计划用于 Django 应用的数据库品牌，ENGINE值必须是表 1-2 中所示的值之一。

表 1-2。

Django ENGINE value for different databases

| 数据库ˌ资料库 | Django `ENGINE`值 | | --- | --- | | 关系型数据库 | `django.db.backends.mysql` | | 神谕 | `django.db.backends.oracle` | | 一种数据库系统 | `django.db.backends.postgresql_psycopg2` | | 数据库 | `django.db.backends.sqlite3` |

Django 数据库连接参数NAME用于标识一个数据库实例，其值的约定可能因数据库品牌而异。例如，对于 SQLite 来说,NAME表示平面文件的位置，而对于 MySQL 来说，它表示实例的逻辑名称。

Django 数据库连接参数的完整设置在表 1-3 中描述。

表 1-3。

Django database connection parameters based on database brand

| Django 连接参数 | 缺省值 | 笔记 | | --- | --- | --- | | `ATOMIC_REQUESTS` | `False` | 对每个查看请求强制执行(或不执行)一个事务。默认情况下设置为 False，因为为每个视图打开一个事务会有额外的开销。对性能的影响取决于应用的查询模式以及数据库处理锁定的能力。 | | `AUTOCOMMIT` | `True` | 默认情况下设置为 True，因为否则将需要显式事务来执行提交。 | | `CONN_MAX_AGE` | `0` | 数据库连接的生存期(秒)。默认为 0，在每个请求结束时关闭数据库连接。对于无限制的持久连接，请使用 None。 | | `ENGINE` | `''`(空字符串) | 要使用的数据库后端。数值选项见表 1-2 。 | | `HOST` | `''`(空字符串) | 定义数据库主机，其中空字符串表示本地主机。对于 MySQL:如果该值以正斜杠('/')开头，MySQL 将通过 Unix 套接字连接到指定的套接字(例如，" HOST": '/var/run/mysql ')。如果该值不以正斜杠开头，则该值被假定为主机。对于 PostgreSQL:默认情况下(')，通过 UNIX 域套接字(pg_hba.conf 中的' local '行)连接到数据库。如果 UNIX 域套接字不在标准位置，请使用 postgresql.conf 中 unix_socket_directory 的相同值。如果要通过 TCP 套接字进行连接，请将 host 设置为“localhost”或“127 . 0 . 0 . 1”(pg _ HBA . conf 中的“HOST”行)。在 Windows 上，您应该始终定义主机，因为 UNIX 域套接字不可用。 | | `NAME` | `''`(空字符串) | 要使用的数据库的名称。对于 SQLite，它是数据库文件的完整路径。指定路径时，请始终使用正斜杠，即使在 Windows 上也是如此(例如，C:/www/STORE/db.sqlite3)。 | | `OPTIONS` | `{}`(空字典) | 连接到数据库时使用的额外参数。可用参数因数据库后端而异，请查阅后端模块自己的文档。有关后端模块的列表，请参见表 1-2 。 | | `PASSWORD` | `''`(空字符串) | 连接到数据库时使用的密码。不用于 SQLite。 | | `PORT` | `''`(空字符串) | 连接到数据库时使用的端口。空字符串表示默认端口。不用于 SQLite。 | | `USER` | `''`(空字符串) | 连接到数据库时使用的用户名。不用于 SQLite。 |

安装 Python 数据库包

除了配置 Django 连接到数据库，您还需要安装必要的 Python 包来与您的数据库品牌通信——唯一的例外是 SQLite，它包含在 Python 发行版中。

每个数据库依赖于不同的软件包，但是使用 pip 软件包管理器，安装过程非常简单。如果您的系统上没有 pip 可执行文件，请参阅本章前面的“安装 Django”一节中的“安装 pip”小节。

表 1-4 中列举了 Django 支持的每个数据库的 Python 包。此外，表 1-4 还包括安装每个包的 pip 命令。

表 1-4。

Python packages for different databases

| 数据库ˌ资料库 | Python 包 | pip 安装语法 | | --- | --- | --- | | 一种数据库系统 | `psycopg2` | `pip install psycopg2` | | 关系型数据库 | `mysql-python` | `pip install mysql-python` | | 神谕 | `cx_Oracle` | `pip install cx_Oracle` | | 数据库 | 包含在 Python 2.5+中 | 不适用的 |

Database Development Libraries

如果您在尝试安装表 1-4 中的一个 Python 数据库包时收到错误，请确保您的系统上安装了数据库开发库。数据库开发库是构建连接到数据库的软件所必需的。

数据库开发库与 Python 或 Django 无关，因此您需要咨询数据库供应商或操作系统文档(例如，在 Debian Linux 或 Ubuntu Linux 系统上，您可以使用以下 apt-get 任务安装 MySQL 开发库:apt-get install libmysql client-dev)。

测试 Django 数据库连接并构建 Django 基表

一旦用数据库凭证更新了 Django settings.py文件，就可以测试它，看看 Django 应用是否可以与数据库通信。在整个 Django 项目中，有几项任务需要与数据库进行通信，但是现在测试数据库连接最常见的任务之一是将项目的数据结构迁移到数据库中。

Django 数据库迁移过程确保与数据库相关的所有 Django 项目逻辑都反映在数据库本身中(例如，数据库具有 Django 项目所需的必要表格)。当您开始一个 Django 项目时，Django 需要进行一系列的迁移，这些迁移需要创建表来跟踪管理员和会话。这总是 Django 项目对数据库运行的第一个迁移过程。因此，为了测试 Django 数据库连接，让我们在数据库上运行第一次迁移，以创建这组基表。

要针对数据库运行 Django 项目的迁移，在项目的BASE_DIR中使用带有migrate参数的manage.py脚本(例如，python manage.py migrate)。第一次执行这个命令时，输出应该类似于清单 1-15 。

[user@coffeehouse ∼]$ python manage.py migrate
Operations to perform:
  Apply all migrations: admin, auth, contenttypes, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying admin.0001_initial... OK
  Applying admin.0002_logentry_remove_auto_add... OK
  Applying contenttypes.0002_remove_content_type_name... OK
  Applying auth.0002_alter_permission_name_max_length... OK
  Applying auth.0003_alter_user_email_max_length... OK
  Applying auth.0004_alter_user_username_opts... OK
  Applying auth.0005_alter_user_last_login_null... OK
  Applying auth.0006_require_contenttypes_0002... OK
  Applying auth.0007_alter_validators_add_error_messages... OK
  Applying auth.0008_alter_user_username_max_length... OK
  Applying sessions.0001_initial... OK
Listing 1-15.Run first Django migrate operation to create base database tables

如清单 1-15 所示，如果数据库连接成功，Django 会应用一系列迁移来创建数据库表，以管理项目的用户、组、权限和会话。目前，不要太担心这些 Django 迁移是如何工作的或者它们位于哪里——我将在后面提供细节——只需要知道 Django 需要这些迁移来提供一些基本的功能。

Tip

直接连接到数据库。如果您在尝试连接到数据库或迁移 Django 项目以创建初始数据库表集时收到错误，请尝试使用相同的 Django 参数直接连接到数据库。

在许多情况下，Django 变量 NAME、USER、PASSWORD、HOST 或 PORT 中的输入错误会导致进程失败，或者凭据甚至无法直接连接到数据库。

设置内容:了解 URL、模板和应用

Django 项目中的内容使用三个主要的构件:URL、模板和应用。您分别创建和配置 Django 的 URL、模板和应用，尽管您将它们相互连接以实现内容交付，这是 Django 松散耦合架构设计原则的一部分。

URL 定义了访问内容的入口点或位置。模板定义了赋予最终内容形式的端点。应用充当 URL 和模板之间的中间件，改变或添加来自数据库或用户交互的内容。要运行静态内容，您只需要创建和配置 Django urls 和模板。要运行动态内容——从数据库或用户交互中构建——除了 URL 和模板之外，还需要创建和配置 Django 应用。

但在描述如何创建和配置 URL、模板和应用之前，了解这些部分如何相互配合非常重要。图 1-4 显示了 Django 处理用户请求的工作流程，以及他们如何处理 Django urls、模板和应用。

图 1-4。

Django workflow for urls, templates, and apps

正如您在图 1-4 中看到的，有两条独立的管道来传递静态或动态内容。更重要的是，注意每个不同的 Django 层是如何松散耦合的(例如，如果不需要应用层，您可以放弃它，而 URL 层和模板层仍然能够相互通信)。

创建和配置 Django Urls

Django urls 的主要入口点是启动项目时创建的urls.py文件——如果您不熟悉 Django 项目结构，请参见本章前面的清单 1-11 。如果你打开urls.py文件，你会注意到它只有一个到/admin/的活动 url，那就是 Django admin——我将在本章的下一节也是最后一节讨论 Django admin。

现在您已经熟悉了urls.py文件的语法，让我们激活一个 url 来查看 Django 项目主页上的定制内容。

Django urls 使用正则表达式来匹配传入的请求。匹配主页的正则表达式模式是^$——下一章包括一个关于在 Django urls 中使用正则表达式的专门章节。除了正则表达式模式之外，还需要在拦截到匹配模式的请求时做什么的动作(例如，发送来自特定模板的内容)。

打开urls.py文件，添加第 3 行——在django.contrib import admin下面的一行——和第 9 行——在url(r'^admin/', admin.site.urls),下面的一行——如清单 1-16 所示。

from django.conf.urls import url
from django.contrib import admin

from django.views.generic import TemplateView

...
...

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^$',TemplateView.as_view(template_name='homepage.html')),

]

Listing 1-16.Django url for home page to template

如清单 1-16 所示，urlpatterns是一个url()语句的 Python 列表。url方法来自django.conf.urls包。您刚刚添加的url方法定义了主页的模式——正则表达式^$——后跟动作TemplateView.as_view(template_name='homepage.html')。最后一个动作是一个帮助器方法，将请求方指向一个采用参数template_name='homepage.html'的模板。

总之，您在清单 1-16 中添加的url方法告诉 Django 对主页的请求应该返回模板homepage.html中的内容。url方法是非常通用的，可以接受多种变化，我将在下一章简要而详细地描述。

现在让我们测试一下主页。通过在 Django 项目的BASE_DIR上执行python manage.py runserver来启动开发 web 服务器。打开浏览器上的默认地址http://127.0.0.1:8000/。你看到了什么？带有Exception Type: TemplateDoesNotExist homepage.html的错误页面。这个错误是因为 Django 找不到为 url 定义的homepage.html模板。在下一节中，我将向您展示如何配置和创建模板。

Caution

如果您收到错误OperationalError - no such table: django_session而不是错误TemplateDoesNotExist homepage.html，这意味着 Django 项目的数据库仍然没有正确设置。您需要在项目的BASE_DIR中运行python manage.py migrate，这样 Django 就会创建必要的表来跟踪会话。有关更多详细信息，请参见上一节关于设置数据库的内容。

创建和配置 Django 模板

默认情况下，Django 模板被解释为 HTML。这意味着 Django 模板应该有一个标准的 HTML 文档结构和 HTML 标签(例如，<html>、<body>)。您可以使用常规的文本编辑器来创建 Django 模板，并使用.html扩展名保存文件。

让我们为过去部分的 url 创建一个模板。在文本编辑器中，创建一个名为homepage.html的文件，并将清单 1-17 的内容放入其中。将文件保存在您的系统上，在 Django 项目的PROJECT_DIR.的子目录templates中

<html>
 <body>
  <h4>Home page for Django</h4>
 </body>
</html>
Listing 1-17.Template homepage.html

一旦有了包含 Django 模板的目录，就需要配置一个 Django 项目，这样它就可以在这个目录中找到模板。在 Django 项目的settings.py文件中，需要在TEMPLATES变量的DIRS属性中定义模板目录。DIRS属性是一个列表，因此您可以定义几个目录来定位模板，尽管我建议您只使用一个带有各种子目录的目录来进行分类。

正如我之前推荐的，你应该把 Django 模板放在子目录中——在 Django 项目的PROJECT_DIR中使用一个像templates这样明显的名字。例如，如果 Django 项目PROJECT_DIR的绝对路径是/www/STORE/coffeehouse/，那么DIRS值的推荐位置就是/www/STORE/coffeehouse/templates/。清单 1-18 展示了在settings.py中使用在settings.py顶部动态设置的PROJECT_DIR引用变量的示例DIRS定义。

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['%s/templates/' % (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Listing 1-18.TEMPLATES and DIRS definition in settings.py

清单 1-18 的一个重要特点是它没有使用硬编码的目录路径；相反，它使用动态确定的PROJECT_DIR变量。这在目前看起来可能是微不足道的，但是一旦 Django 项目的位置有改变的趋势(例如，组开发，部署到生产)，这就是一个好的实践。

最后，再次启动 Django 开发 web 服务器，并在默认地址http://127.0.0.1:8000/上打开一个浏览器。您现在应该在主页上看到模板homepage.html的内容，而不是您在上一节中看到的错误页面。

创建和配置 Django 应用

Django 应用用于对应用功能进行分组。如果你想处理来自数据库或用户交互的内容，你必须创建和配置 Django 应用。一个项目可以包含任意数量的应用。例如，如果您有一个咖啡馆项目，您可以创建一个商店应用、另一个菜单项应用、另一个关于信息的应用，并根据需要创建其他应用。一个项目中的应用数量没有硬性规定。无论是简化代码管理还是将应用工作委托给团队，Django apps 的目的都是将应用功能分组以使工作更容易。

Django 应用通常包含在项目的子目录中。这种方法使得使用 Python 引用和命名约定更加容易。如果项目名为 coffeehouse，名为 stores 的应用的功能很容易通过 Python 包引用为coffeehouse.stores。

因为应用提供了一种组合应用功能的模块化方法，所以其他人或团体分发具有流行功能的 Django 应用是很常见的。例如，如果一个 Django 项目需要论坛功能，而不是从头开始编写一个论坛应用，您可以利用几个 Django 论坛应用中的一个。你寻找的功能越通用，你就越有可能找到第三方开发的 Django 应用。

You Already Worked With Django Apps!

您可能没有意识到这一点，但是在上一节中，当您为 Django 项目设置数据库时，您已经在调用 migrate 操作时使用了 Django apps。

默认情况下，所有 Django 项目都启用了框架提供的六个应用。这些应用分别是django.contrib.admin、django.contrib.auth、django.contrib.contenttypes、django.contrib.sessions、django.contrib.messages和django.contrib.staticfiles。当您触发迁移操作时，Django 为这些预安装的应用创建了数据库模型。

接下来，让我们创建一个小的 Django 应用。转到PROJECT_DIR——urls.py和settings.py文件所在的位置——执行命令django-admin startapp about创建一个名为 about 的应用。一个名为about的子目录被创建，其中包含该应用。默认情况下，创建应用时，其子目录包括以下内容:

__init__.py。- Python 文件，允许从其他目录导入应用包。注意__init__.py不是一个 Django 特定的文件，它是一个在几乎所有 Python 应用中使用的通用文件。
migrations。-包含应用于应用数据库定义(即模型类)的迁移的目录。
admin.py。-包含应用管理定义的文件-从 Django admin 访问模型类实例需要这些定义。
apps.py。-包含应用配置参数的文件。
models.py。-包含应用数据库定义(即模型类)的文件。
tests.py。-应用的测试定义文件。
views.py。-包含应用视图定义(即控制器方法)的文件。

接下来，打开views.py文件并添加清单 1-19 中的内容。

from django.shortcuts import render

def contact(request):
    # Content from request or database extracted here
    # and passed to the template for display
    return render(request,'about/contact.html')

Listing 1-19.
Handler view method
in views.py

清单 1-19 中的contact方法——像views.py文件中的所有其他方法一样——是一个访问用户 web 请求的控制器方法。注意，联系方法的输入名为request。在这种类型的方法中，您可以使用request引用访问来自 web 请求的内容(例如，IP 地址、会话),或者访问来自数据库的信息，以便最终将这些信息传递给模板。如果您查看 contact 方法的最后一行，它以 Django helper 方法render的返回语句结束。在这种情况下，render 方法将控制权返回给about/contact.html模板。

因为清单 1-19 中的contact方法将控制权返回给模板about/contact.html，所以您还需要在您的templates目录中创建一个名为about的子目录，其中包含一个名为contact.html的模板(即在TEMPLATES变量的DIRS属性中定义的模板)。

contact方法本身什么也不做，它需要被 url 调用。清单 1-20 展示了如何向链接到清单 1-19 中contact方法的urls.py文件添加一个 url。

from django.conf.urls import url
from django.contrib import admin
from django.views.generic import TemplateView

from coffeehouse.about import views as about_views

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^$',TemplateView.as_view(template_name='homepage.html')),
    url(r'^about/', about_views.contact),
]

Listing 1-20.Django url for view method

清单 1-20 中声明的第一件事是一个 import 语句，用于访问清单 1-19 中的contact方法。在这种情况下，因为应用被命名为about，并且它位于coffeehouse项目文件夹下，所以它显示为from coffeehouse.about，后跟import views，这使我们可以访问应用的views.py文件，其中有contact方法。

import 语句以as about_views结束，以分配一个唯一的限定符，如果您计划使用多个应用，这很重要。例如，没有as关键字的导入语句，如from coffeehouse.about import views、from coffeehouse.items import views或from coffeehouse.stores import views可以导入冲突的视图方法引用(例如，三个名为 index 的方法)，因此as限定符是一种保护措施，以确保您不会无意中使用另一个应用中同名的方法。

清单 1-20 中的新 url 定义使用正则表达式来匹配about url 目录(例如http://127.0.0.1:8000/about/)上的请求，而不是将请求定向到模板，而是将控制权交给about_views.contact方法——其中about_views指的是上一段中描述的导入引用。

接下来，启动 Django 开发 web 服务器，并在地址http://127.0.0.1:8000/about/上打开一个浏览器。注意about url 目录上的请求如何显示在views.py的contact方法中定义的底层about/contact.html模板。

最后，虽然您现在可以访问应用的views.py方法，但是您还需要在项目的settings.py文件中配置应用。这最后一步很重要，这样 Django 就可以找到您稍后创建的其他应用构造(例如，数据库模型定义、静态资源、定制模板标签)。

打开 Django 项目的settings.py文件并寻找INSTALLED_APPS变量。你会看到一系列已经在INSTALLED_APPS上定义的应用。注意安装的应用是如何属于django.contrib包的，这意味着它们是由 Django 框架本身提供的。将coffeehouse.about应用添加到列表中，如清单 1-21 的第 8 行所示。

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'coffeehouse.about',

]
Listing 1-21.Add app to INSTALLED_APPS in Django settings.py

如清单 1-21 的第 8 行所示，要将应用添加到项目中，您需要将应用包作为字符串添加到INSTALLED_APPS变量中。虽然coffeehouse.about应用实际上仍然是空的，但是将应用添加到INSTALLED_APPS变量中是未来操作的重要配置步骤，例如数据库操作和与应用相关的静态资源，等等。

设置 Django 管理站点

Django 管理站点提供了一个基于 web 的界面来访问连接到 Django 项目的数据库。即使对于有经验的技术管理员来说，直接在数据库上进行数据库 CRUD(创建-读取-更新-删除)操作也是困难和耗时的，因为需要发出原始 SQL 命令和导航数据库结构。对于非技术用户来说，直接在数据库上进行数据库 CRUD 操作可能会令人望而生畏，如果不是不可能的话。Django 管理站点解决了这个问题。

Django 管理站点可以公开链接到数据库的所有 Django 项目相关的数据结构，因此专家和新手都可以轻松地执行数据库 CRUD 操作。随着 Django 项目的增长，Django 管理站点可以成为管理与 Django 项目相关的数据库中不断增长的大量信息的重要工具。

Django 管理站点是作为 Django 应用构建的；这意味着设置 Django 管理站点唯一需要做的事情就是像其他 Django 应用一样配置和安装应用。如果您不熟悉 Django app 这个术语，请阅读上一节“设置内容:理解 URL、模板和应用”

Django 管理站点要求您预先配置一个数据库并安装 Django 基表。因此，如果您还没有这样做，请参阅上一节“为 Django 项目设置数据库”

配置并安装 Django 管理站点应用

默认情况下，所有 Django 项目都启用了 Django 管理。如果你打开一个 Django 项目的urls.py文件，在urlpatterns变量中你会看到行url(r'^admin/', admin.site.urls)。最后一个正则表达式模式告诉 Django 在/admin url 目录(例如http://127.0.0.1:8000/admin/)上启用管理站点应用。

接下来，如果你打开项目的settings.py文件，转到INSTALLED_APPS变量，在这个变量的顶部附近，你会看到一行django.contrib.admin,表示 Django 管理站点应用已启用。

通过在 Django 的BASE_DIR上执行python manage.py runserver来启动开发 web 服务器。在 Django 管理网站http://127.0.0.1:8000/admin/上打开浏览器。你会看到如图 1-5 所示的登录屏幕。

图 1-5。

Django admin site login

接下来，让我们创建一个 Django 超级用户或管理员，通过图 1-5 中的界面访问 Django admin。要创建 Django 超级用户，你可以使用清单 1-22 中的manage.py命令。

[user@coffeehouse ∼]$ python manage.py createsuperuser
Username (leave blank to use 'admin'):
Email address: admin@coffeehouse.com
Password:
Password (again):
The password is too similar to the email address.
This password is too short. It must contain at least 8 characters.
This password is too common.
Password:
Password (again):
Superuser created successfully.
Listing 1-22.Create Django superuser for admin interface

Caution

如果您收到错误OperationalError - no such table: auth_user，这意味着 Django 项目的数据库仍然没有正确设置。您需要在项目的 BASE_DIR 中运行python manage.py migrate,这样 Django 就会创建必要的表来跟踪用户。更多细节请参见上一节“为 Django 项目设置数据库”。

Tip

默认情况下，Django 强制用户密码符合最低安全级别。例如，在清单 1-22 中，您可以看到在尝试使用密码 coffee 之后，Django 拒绝了这个任务，并给出了一系列错误消息，强制进行新的尝试。您可以在setttings.py的AUTH_PASSWORD_VALIDATORS变量中修改这些密码验证规则。

最后这个过程创建了一个超级用户，其信息存储在连接到 Django 项目的数据库中，具体地说是存储在auth_user表中。现在您可能会问自己，如何更新这个用户的名称、密码或电子邮件？虽然您可以直接进入数据库表并执行更新，但这是一条曲折的路线；更好的方法是依赖 Django admin，它可以让您非常友好地查看 Django 项目中的数据库表。

接下来，将刚刚创建的超级用户用户名和密码引入图 1-5 的界面。一旦你在管理站点上提供了超级用户的用户名和密码，你将访问如图 1-6 所示的管理站点的主页。

图 1-6。

Django admin site home page

在 Django 管理网站的主页上，如图 1-6 所示，点击“用户”链接。您将看到有权访问 Django 项目的用户列表。目前，您只能看到您在上一步中创建的超级用户。您可以更改该用户的凭证(如密码、电子邮件、用户名)或直接从 Django 管理站点屏幕添加新用户。

这种修改或添加存储在与 Django 项目相关的数据库中的记录的灵活性使得 Django 管理站点如此强大。例如，如果您开发了一个咖啡馆项目，并添加了商店、饮料或客户等应用，Django admin 授权用户可以对这些对象进行 CRUD 操作(例如，创建商店、更新饮料、删除客户)。从内容管理的角度来看，这是非常强大的，特别是对于非技术用户。最重要的是，在项目的应用上启用 Django 管理站点几乎不需要额外的开发工作。

这里介绍的 Django 管理站点任务只是功能上的“冰山一角”;下一章将更详细地介绍 Django 管理站点的功能。

配置并安装 Django 管理站点文档应用

Django 管理站点也有自己的文档应用。Django 管理站点文档应用不仅提供关于管理站点本身操作的信息，还包括关于 Django 模板的 Django 过滤器的其他通用文档。更重要的是，Django admin site documentation 应用会对所有已安装的项目应用的源代码进行自省，以呈现关于控制器方法和模型对象的文档(即嵌入在应用models.py和views.py文件的源代码中的文档)。

要安装 Django 管理站点文档应用，您首先需要安装 docutils Python 包，使用 pip 包管理器执行以下命令:pip install docutils。一旦安装了 docutils 包，就可以像安装其他 Django 应用一样安装 Django 管理站点文档应用。

添加 url 以访问 Django 管理站点文档应用。如果打开项目的urls.py文件，在urlpatterns变量中添加下面一行:

 url(r'^admin/doc/', include('django.contrib.admindocs.urls'))

请确保在url(r'^admin/'…行之前添加此内容，以便在底部保留更多通用匹配表达式，在顶部保留同一 url 路径上的更多粒度表达式(例如/admin)。最后一个正则表达式模式告诉 Django 启用/admin/doc/ url 目录下的管理站点文档应用(例如http://127.0.0.1:8000/admin/doc/)。

接下来，打开项目的settings.py文件，转到INSTALLED_APPS变量。在这个变量的最终值附近添加一行django.contrib.admindocs来启用 Django 管理站点文档应用。

随着开发 web 服务器的运行，在地址http://127.0.0.1:8000/admin/doc/上打开一个浏览器，您应该会看到如图 1-7 所示的页面。

图 1-7。

Django admin site doc home page

如果您注销了 Django 管理站点，您将需要再次登录来访问文档，因为它也需要用户认证。登录后，您将能够看到 Django 管理站点的文档主页——如图 1-7 所示——以及关于项目的控制器方法和模型对象的文档。

Footnotes 1

https://djangopackages.org/

https://engineering.instagram.com/what-powers-instagram-hundreds-of-instances-dozens-of-technologies-adf2e22da2ad#.pui97g5jk

https://www.quora.com/Pinterest/What-is-the-technology-stack-behind-Pinterest-1

http://open.pbs.org/

https://github.com/natgeo

https://www.python.org/dev/peps/pep-0020/

https://www.djangoproject.com/download/

https://github.com/django/django/

https://pythonhosted.org/six/

https://docs.djangoproject.com/en/1.11/topics/python3/

二、Django Url 和视图

在第一章中，你学习了 Django 的核心构建模块，包括什么是视图、模型和 URL。在这一章中，您将了解更多关于 Django urls 的内容，它是 Django 应用工作流的入口点。您将学习如何创建复杂的 url 正则表达式，如何在视图方法和模板中使用 url 值，如何构造和管理 URL，以及如何命名 URL。

在 URL 之后，Django 视图代表了几乎所有 Django 工作流的下一步，视图负责检查请求、执行业务逻辑、查询数据库和验证数据，以及生成响应。在本章中，您将学习如何创建带有可选参数的 Django 视图，视图请求和响应的结构，如何使用视图中间件，以及如何创建基于类的视图。

Url 正则表达式

正则表达式在所有编程语言中都提供了一种强大的方法来确定模式。然而，强大的同时也带来了复杂性，甚至有整本书都在讨论正则表达式。 ¹

尽管大多数 Django URL 的复杂性不会超过许多正则表达式书中所描述的一小部分，但是理解 Django URL 中正则表达式的一些底层行为和最常见的模式是很重要的。

优先规则:粒度 URL 优先，广义 URL 最后

Django urls 需要遵循一定的顺序和语法才能正常工作。广义 url 正则表达式应该最后声明，并且只能在更细粒度的 url 正则表达式之后声明。

这是因为 Django url 正则表达式匹配不使用短路行为，就像嵌套条件语句(例如，if/elif/elif/elif/else)一样，只要满足一个条件，其余选项就会被忽略。在 Django urls 中，如果一个传入的 url 请求有不止一个匹配的正则表达式，那么将会触发最顶层的一个操作。匹配 url 正则表达式的优先级从顶部(即第一个声明的)到底部(即最后一个声明的)给出。

你不应该低估引入两个匹配相同模式的 url 正则表达式有多容易，特别是如果你从来没有使用过正则表达式，因为语法可能很神秘。清单 2-1 展示了声明 Django urls 的正确方式，更细粒度的正则表达式在顶部，更宽泛的正则表达式在底部。

from django.views.generic import TemplateVieww

urlpatterns = [
    url(r'^about/index/',TemplateView.as_view(template_name='index.html')),
    url(r'^about/',TemplateView.as_view(template_name='about.html')),
]

Listing 2-1.Correct precedence for Django url regular expressions

基于清单 2-1 ，让我们看看如果 Django 收到对 url /about/index/的请求会发生什么。最初，Django 匹配最后一个正则表达式，即“匹配^about/”。接下来，Django 继续向上检查正则表达式，并到达与请求 url /about/index/完全匹配的‘match^about/index/',因此触发这个动作将控制发送到index.html模板。

现在让我们浏览一个对 url /about/的请求。最初，Django 匹配最后一个正则表达式“匹配^about/”。接下来，Django 继续向上检查正则表达式，寻找潜在的匹配。因为没有找到匹配——因为‘match^about/index/'是一个更细粒度的正则表达式——Django 触发第一个动作，将控制发送给about.html模板，这是唯一的正则表达式匹配。

正如您所看到的，清单 2-1 产生了可以说是预期的行为。但是现在让我们颠倒 url 正则表达式的顺序，如清单 2-2 所示，并分解为什么向底部声明更细粒度的正则表达式是声明 Django url 正则表达式的错误方式。

from django.views.generic import TemplateVieww

urlpatterns = [
    url(r'^about/',TemplateView.as_view(template_name='about.html')),
    url(r'^about/index/',TemplateView.as_view(template_name='index.html')),
]

Listing 2-2.Wrong precedence for Django url regular expressions

当请求 url /about/index/时，清单 2-2 中的问题出现了。最初，Django 匹配最后一个正则表达式，即“匹配^about/index/”。然而，Django 继续检查正则表达式，并到达‘match^about/'，这是对请求 url /about/index/的更广泛的匹配，但仍然是匹配！因此 Django 触发了这个动作，并将控制权发送给了about.html模板，而不是第一次匹配时预期的index.html模板。

精确 Url 模式:放弃广泛匹配

在上一节中，我有意使用了允许广泛 url 匹配的正则表达式。根据我的经验，随着 Django 项目的增长，你最终会面临使用这种类型的 url 正则表达式的需求——但是稍后会详细解释为什么会这样。

事实证明，使用精确的 url 正则表达式是可能的。精确的 url 正则表达式消除了由于 Django url 正则表达式的声明顺序而引入的任何歧义。

让我们修改清单 2-2 中的 url 正则表达式，使它们成为精确的正则表达式，这样它们的顺序就无关紧要了。清单 2-3 在清单 2-2 的基础上展示了精确的正则表达式。

from django.views.generic import TemplateVieww

urlpatterns = [
    url(r'^about/$',TemplateView.as_view(template_name='about.html')),
    url(r'^about/index/$',TemplateView.as_view(template_name='index.html')),
]

Listing 2-3.Exact regular expressions, where url order doesn’t matter

注意清单 2-3 中的正则表达式以$字符结束。这是表示行尾的正则表达式符号，这意味着正则表达式 URL 只匹配一个精确的模式。

例如，如果 Django 接收到对 url /about/index/的请求，它将只匹配清单 2-3 中的最后一个正则表达式，即“匹配^about/index/$”。然而，它不会匹配更高级的^/about/$正则表达式，因为这个正则表达式说与about/完全匹配，因为$表示模式的结束。

然而，尽管$字符对于创建更严格的 url 正则表达式很有用，但是分析它的行为也很重要。如果您计划使用 url 搜索引擎优化(SEO)、A/B 测试技术，或者只是希望允许多个 URL 运行相同的操作，那么使用更严格的正则表达式$最终需要做更多的工作。

例如，如果您开始使用像/about/index/、/about/email/、/about/address/这样的 URL，并且它们都使用相同的模板或视图进行处理，精确正则表达式只会使您声明的 URL 数量更大。类似地，如果您使用 A/B 测试或 SEO，其中相同 url 的较长变体以相同的方式处理(例如，/about/landing/a/、/about/landing/b/、/about/the+coffeehouse+in+san+diego/)，宽泛的 url 匹配比声明精确的 url 模式要简单得多。

最后，无论您是否选择使用以$结尾的精确 url 正则表达式，我仍然建议您保持将更细粒度的 url 正则表达式放在顶部而将更广泛的 url 正则表达式放在底部的做法，因为这可以避免当不止一个正则表达式匹配一个 URL 请求时出现清单 2-2 中描述的意外行为。

常见 Url 模式

尽管 url 正则表达式可以有无限多种变化——几乎不可能描述每种可能性——但我将提供一些您更可能使用的最常见 url 模式的示例。表 2-1 显示了 Django urls 的单个正则表达式字符，表 2-2 显示了 url 模式的一系列更具体的例子。

表 2-2。

Common Django url patterns and their regular expressions, with samples

| Url 正则表达式 | 描述 | 示例 URL | | --- | --- | --- | | URL(r ' ^ $ ') | 空字符串(主页) | 匹配项:http://127.0.0.1/ | | url(r'^stores/'，.....) | 有尾随字符吗 | 火柴: [`http://127.0.0.1/stores/`](http://127.0.0.1/stores/) [`http://127.0.0.1/stores/long+string+with+anything+12345`](http://127.0.0.1/stores/long+string+with+anything+12345) | | url(r'^about/contact/$'，.....) | 精确，无尾随字符 | 匹配: [`http://127.0.0.1/about/contact/`](http://127.0.0.1/about/contact/) 不匹配: [`http://127.0.0.1/about/`](http://127.0.0.1/about/) | | url(r'^stores/\d+/'，..…) | 数字 | 匹配: [`http://127.0.0.1/stores/2/`](http://127.0.0.1/stores/2/) [`http://127.0.0.1/stores/34/`](http://127.0.0.1/stores/34/) 不匹配: [`http://127.0.0.1/stores/downtown/`](http://127.0.0.1/stores/downtown/) | | URL(r ' ^ drinks/\ d+/'， | 非数字 | 匹配: [`http://127.0.0.1/drinks/mocha/`](http://127.0.0.1/drinks/mocha/) 不匹配: [`http://127.0.0.1/drinks/324/`](http://127.0.0.1/drinks/324/) | | url(r'^drinks/mocha|espresso/'，.....) | 单词选项，任何尾随字符 | 匹配:[`http://127.0.0.1/drinks/mocha/`](http://127.0.0.1/drinks/mocha/)[`http://127.0.0.1/drinks/mochaccino/`](http://127.0.0.1/drinks/mochaccino/)[`http://127.0.0.1/drinks/espresso/`](http://127.0.0.1/drinks/espresso/)不匹配: [`http://127.0.0.1/drinks/soda/`](http://127.0.0.1/drinks/soda/) | | url(r'^drinks/mocha$|espresso/$'，.....) | 单词选项精确，无尾随字符 | 匹配: [`http://127.0.0.1/drinks/mocha/`](http://127.0.0.1/drinks/mocha/) 不匹配: [`http://127.0.0.1/drinks/mochaccino/`](http://127.0.0.1/drinks/mochaccino/) 匹配: [`http://127.0.0.1/drinks/espresso/`](http://127.0.0.1/drinks/espresso/) 不匹配: [`http://127.0.0.1/drinks/espressomacchiato/`](http://127.0.0.1/drinks/espressomacchiato/) | | url(r'^stores/\w+/'，.....) | 单词字符(任何小写或大写字母、数字或下划线) | 匹配:[`http://127.0.0.1/stores/sandiego/`](http://127.0.0.1/stores/sandiego/)[`http://127.0.0.1/stores/LA/`](http://127.0.0.1/stores/LA/)[`http://127.0.0.1/stores/1/`](http://127.0.0.1/stores/1/)不匹配: [`http://127.0.0.1/san-diego/`](http://127.0.0.1/san-diego/) | | url(r'^stores/[-\w]+/'，.....) | 单词字符或破折号 | 火柴: [`http://127.0.0.1/san-diego/`](http://127.0.0.1/san-diego/) | | url(r'^state/[A-Z]{2}/'，.....) | 两个大写字母 | 匹配: [`http://127.0.0.1/CA/`](http://127.0.0.1/CA/) 不匹配: [`http://127.0.0.1/Ca/`](http://127.0.0.1/Ca/) |

表 2-1。

Regular expression syntax for Django urls: Symbol (Meaning)

| url 的开头) | url 的结尾) | \(对解释的值进行转义) | |(或) | | + (1 次或多次出现) | ？(出现 0 次或 1 次) | {n}(出现 n 次) | {n，m}(出现次数介于 n 和 m 之间) | | [](字符分组) | (?P ___)(捕获与 regexp ___ 匹配的匹配项，并将其分配给 name | 。(任何字符) | \d+(一个或多个数字)。注意 escape，没有 escape 按字面意思匹配' d+'。 | | \D+(一个或多个非数字)。注意转义，没有转义匹配' D+' | [a-zA-Z0-9_]+(一个或多个单词字符、小写或大写字母、数字或下划线) | \w+(一个或多个单词字符，相当于[a-zA-Z0-9_])。注意 escape，没有 escape 按字面意思匹配‘w+’。 | [-@\w]+(一个或多个单词字符，破折号。或者在符号处)。请注意，\w 没有转义，因为它被括在括号中(即分组)。 |

Django Urls Don’T Inspect Url Query Strings

在某些 URL 上——那些由 HTTP GET 请求生成的 URL，常见于 HTML 表单或 REST 服务中——参数被添加到 URL 中，其中?后跟由&分隔的parameter_name=parameter_value(例如，/drinks/mocha/?type=cold&size=large)。这些值集被称为查询字符串，Django 出于 url 模式匹配的目的忽略了它们。

如果您需要使用这些值作为 url 参数——这是下一节探讨的主题——您可以通过请求引用在 Django 视图方法中访问这些值。另一种方法是改变 url 结构以适应正则表达式(例如，用/drinks/mocha/cold/large/代替/drinks/mocha/?type=cold&size=large)。

Url 参数、额外选项和查询字符串

您刚刚学习了如何使用各种各样的正则表达式为您的 Django 应用创建 URL。然而，如果你回头看看清单 2-1 、 2-2 和 2-3 ，你会注意到 URL 上提供的信息被丢弃了。

有时将 url 信息作为参数传递给处理结构是有帮助的，甚至是必要的。例如，如果你有几个类似于/drinks/mocha/、/drinks/espresso/和/drinks/latte/的 url，URL 的最后一部分代表一个饮料名称。因此，将此 url 信息传递给处理模板以在视图中显示它或以其他方式使用它(例如，查询数据库)可能是有帮助的或必要的。为了传递这些信息，url 需要将这些信息作为一个参数。

为了处理 url 参数，Django 对命名组使用 Python 的标准正则表达式语法。 ² 清单 2-4 显示了一个创建名为drink_name的参数的 url。

urlpatterns = [
    url(r'^drinks/(?P<drink_name>\D+)/',TemplateView.as_view(template_name='drinks/index.html')),
]
Listing 2-4.Django url parameter definition for access in templates

注意清单 2-4 中的(?P<drink_name>\D+)语法。?P<>语法告诉 Django 将正则表达式的这一部分视为命名组，并将值赋给在<>之间声明的名为drink_name的参数。最后一块\D+是确定匹配值的正则表达式；在这种情况下，匹配值是一个或多个非数字字符，如表 2-1 所述。

非常重要的一点是，您必须理解，只有当提供的值与指定的正则表达式匹配时，参数才会被捕获(例如，\D+表示非数字)。例如，对于 url 请求/drinks/mocha/，值mocha被分配给drink_name参数，但是对于像/drinks/123/这样的 url，正则表达式模式不匹配——因为123是数字——所以不采取任何行动。

如果清单 2-4 中出现 url 匹配，请求将被直接发送到模板drinks/index.html。Django 通过同名的 Django 模板上下文变量提供对以这种方式定义的所有参数的访问。因此，要访问参数，您可以直接在模板中使用参数名drink_type。例如，要输出参数drink_name的值，您可以使用标准的{{}} Django 模板语法(例如，{{drink_name}})。

除了将 url 的一部分视为参数，还可以在 url 定义中定义额外的选项，以便在 Django 模板中将它们作为上下文变量来访问。这些额外的选项在一个字典中定义，该字典被声明为 url 定义的最后一部分。

例如，请看清单 2-4 中修改后的 url Django 定义:

url(r'^drinks/(?P<drink_name>\D+)', TemplateView.as_view(template_name='drinks/index.html'), {'onsale':True}),

注意一个带有键值的字典是如何被添加到 url 定义的末尾的。以这种方式，onsale键成为一个 url 额外选项，它作为一个上下文变量被传递给底层模板。Url 额外选项可以像 url 参数一样作为模板上下文变量来访问。因此，为了输出额外的选项onsale，你可以使用{{onsale}}语法。

接下来，让我们看看清单 2-5 中展示的 url 参数的另一种变体，它将控制发送给 Django 视图方法。

# Project main urls.py
from coffeehouse.stores import views as stores_views

urlpatterns = patterns[
    url(r'^stores/(?P<store_id>\d+)/',stores_views.detail),
]

Listing 2-5.Django url parameter definition for access in view methods in main urls.py file

注意清单 2-5 中的(?P<store_id>\d+)语法与清单 2-4 中的非常相似。发生变化的是参数现在被命名为store_id，正则表达式是\d+来匹配数字。因此，举例来说，如果向 url /stores/1/发出请求，则值 1 被赋给store_id参数，如果向类似/stores/downtown/的 url 发出请求，则正则表达式模式不匹配——因为downtown是字母而不是数字——所以不采取任何行动。

如果清单 2-5 出现 url 匹配，请求将被直接发送到 Django 视图方法coffeehouse.stores.views.detail。其中coffeehouse.stores是包名，views.py是 stores 应用中的文件，detail是视图方法的名称。清单 2-6 展示了访问store_id参数的detail视图方法。

from django.shortcuts import render

def detail(request,store_id):
    # Access store_id with 'store_id' variable
    return render(request,'stores/detail.html')

Listing 2-6.Django view method

in views.py to access url parameter

注意清单 2-6 中的detail方法有两个参数。第一个参数是一个request对象，它对于所有 Django 视图方法都是相同的。第二个参数是 url 传递的参数。需要注意的是，url 参数的名称必须与方法参数的名称相匹配。在这种情况下，注意清单 2-5 中的参数名是store_id，而清单 2-6 中的方法参数也被命名为store_id。

通过 view method 参数访问 url 参数，该方法可以使用该参数执行逻辑(例如，查询数据库)，然后可以将该参数传递给 Django 模板以供呈现。

Caution

无论正则表达式如何，Django url 参数总是被视为字符串。例如，\d+捕捉数字，但值 1 被视为“1”(字符串)，而不是 1(整数)。如果您计划在视图方法中使用 url 参数，并执行需要字符串以外的内容的操作，这一点尤其重要。

由视图方法处理的 url 参数的另一个可用选项是使它们成为可选的，这反过来允许您对多个 URL 使用相同的视图方法。通过为视图方法参数分配默认值，可以使参数成为可选的。清单 2-7 显示了一个新的 url，它调用了同一个视图方法(coffeehouse.stores.views.detail)，但是没有定义参数。

from coffeehouse.stores import views as stores_views

urlpatterns = patterns[
    url(r'^stores/',stores_views.detail),
    url(r'^stores/(?P<store_id>\d+)/',stores_views.detail),
]

Listing 2-7.Django urls with optional parameters leveraging the same view method

如果您调用 url /stores/而没有修改清单 2-6 中的detail方法，您会得到一个错误。出现错误是因为detail视图方法需要一个store_id参数，而第一个 url 没有提供这个参数。要解决这个问题，您可以在视图方法中为store_id定义一个默认值，如清单 2-8 所示。

from django.shortcuts import render

def detail(request,store_id='1'):
    # Access store_id with 'store_id' variable
    return render(request,'stores/detail.html')

Listing 2-8.Django view method

in views.py with default value

注意清单 2-8 中的store_id参数如何赋值='1'。这意味着如果调用视图方法时没有使用store_id，参数将会有一个默认值'1'。这种方法允许您利用同一个视图方法来处理带有可选参数的多个 URL。

除了在视图方法中访问 url 参数之外，还可以从 url 定义中访问额外的选项。这些额外的选项在一个字典中定义，该字典被声明为 url 定义中的最后一个参数。在视图方法声明之后，添加一个字典，其中包含您希望在视图方法中访问的键-值对。下面的代码片段展示了清单 2-7 中 url 语句的修改版本。

url(r'^stores/',stores_views.detail,{'location':'headquarters'})

在这种情况下，location键成为一个 url 额外选项，作为参数传递给 view 方法。访问 Url 额外选项就像访问 url 参数一样，因此要访问 view 方法中的 url 额外选项，您需要修改方法签名以接受与 url 额外选项同名的参数。在这种情况下，方法签名:

def detail(request,store_id='1'):

需要更改为:

def detail(request,store_id='1',location=None):

请注意，location参数通过赋予默认值None而成为可选参数。

最后，还可以在 Django 视图方法中访问由?和&分隔的 url 参数——技术上称为查询字符串。使用request对象可以在视图方法中访问这些类型的参数。

以 url /stores/1/?hours=sunday&map=flash为例，清单 2-9 展示了如何使用request.GET从这个由?和&分隔的 url 中提取参数。

from django.shortcuts import render

def detail(request,store_id='1',location=None):
    # Access store_id param with 'store_id' variable and location param with 'location' variable
    # Extract 'hours' or 'map' value appended to url as
    # ?hours=sunday&map=flash
    hours = request.GET.get('hours', '')
    map = request.GET.get('map', '')
    # 'hours' has value 'sunday' or '' if hours not in url
    # 'map' has value 'flash' or '' if map not in url
    return render(request,'stores/detail.html')

Listing 2-9.Django view method extracting url parameters with request.GET

清单 2-9 使用了语法request.GET.get(<parameter>, '')。如果参数出现在request.GET中，它提取值并将其赋给一个变量以备将来使用；如果参数不存在，那么参数变量被赋予一个默认的空值''——你同样可以使用None或任何其他默认值——因为这是 Python 的标准字典get()方法语法的一部分，以获得默认值。

最后一个过程被设计成从 HTTP GET 请求中提取参数；然而，Django 还支持从 HTTP POST 请求中提取参数的语法request.POST.get,这将在 Django 表单一章和本章后面的 Django 视图方法请求一节中详细描述。

Url 整合和模块化

默认情况下，Django 会在项目主目录下的urls.py文件中查找 url 定义——值得一提的是，这是因为settings.py中的ROOT_URLCONF变量。然而，一旦一个项目超过了几个 URL，在这个文件中管理它们就变得困难了。例如，看看清单 2-10 中所示的urls.py文件。

from django.conf.urls import url
from django.views.generic import TemplateView
from coffeehouse.about import views as about_views
from coffeehouse.stores import views as stores_views

urlpatterns = [
    url(r'^$',TemplateView.as_view(template_name='homepage.html')),
    url(r'^about/',about_views.index),
    url(r'^about/contact/',about_views.contact),
    url(r'^stores/',stores_views.index),
    url(r'^stores/(?P<store_id>\d+)/',stores_views.detail,{'location':'headquarters'}),
   ]

Listing 2-10.Django urls.py with no url consolidation

正如您在清单 2-10 中看到的，有几个 URL 有多余的根- about/和stores/。将这些 URL 分开分组会很有帮助，因为这样可以将常见的 URL 保存在各自的文件中，避免了对一个大的urls.py文件进行修改的困难。

清单 2-11 显示了urls.py文件的更新版本，其中about/和stores/根放在不同的文件中。

from django.conf.urls import include, url
from django.views.generic import TemplateView

urlpatterns = [
    url(r'^$',TemplateView.as_view(template_name='homepage.html')),
    url(r'^about/',include('coffeehouse.about.urls')),
    url(r'^stores/',include('coffeehouse.stores.urls'),{'location':'headquarters'}),
   ]

Listing 2-11.Django urls.py with include to consolidate urls

清单 2-11 利用include参数从完全独立的文件中加载 URL。在这种情况下，include('coffeehouse.about.urls')告诉 Django 从 Python 模块coffeehouse.about.urls加载 url 定义，这与 Django 基目录的分离对应于文件路径/coffeehouse/about/urls.py。在这种情况下，我继续使用urls.py文件名，并把它放在相应的 Django about app 目录下，因为它处理的是about/URL。但是，您可以使用任何您喜欢的文件名或路径来定义 url(例如，coffeehouse.allmyurl.resturls从文件路径/coffeehouse/allmyurls/resturls.py加载 URL)。

清单 2-11 中的第二个 include 语句与第一个一样，其中include('coffeehouse.stores.urls')告诉 Django 从 Python 模块coffeehouse.stores.urls加载 url 定义。但是，请注意，第二条语句附加了一个额外的字典作为 url 额外选项，这意味着 include 语句中的所有 URL 也将收到这个额外选项。

清单 2-12 展示了通过include('coffeehouse.about.urls')链接的文件/coffeehouse/about/urls.py的内容。

from django.conf.urls import url
from . import views

urlpatterns = [
    url(r'^$',views.index),
    url(r'^contact/$',views.contact),
]

Listing 2-12.Django /coffeehouse/about/urls.py loaded via include

快速浏览清单 2-12 ，您可以看到其结构与主urls.py文件非常相似；然而，还是有一些细微的区别。虽然 url 正则表达式r'^$'看起来像是匹配主页，但事实并非如此。因为清单 2-12 中的文件通过主urls.py文件中的include链接，Django 将 url 正则表达式与父 url 正则表达式连接起来。所以清单 2-12 中的第一个 url 实际上匹配/about/，清单 2-12 中的第二个 url 实际上匹配/about/contact/。还因为清单 2-12 中的urls.py文件放在应用的views.py文件旁边，所以导入语句使用相对路径from . import views语法。

除了使用include选项引用带有 url 定义的单独文件之外，include选项还可以接受作为 Python 列表的 url 定义。本质上，这允许你在主urls.py文件中保留所有的 url 定义，但是给它更多的模块性。清单 2-13 中说明了这种方法。

from django.conf.urls import include, url
from django.views.generic import TemplateView

from coffeehouse.about import views as about_views
from coffeehouse.stores import views as stores_views

store_patterns = [
    url(r'^$',stores_views.index),
    url(r'^(?P<store_id>\d+)/$',stores_views.detail),
]

about_patterns = [
    url(r'^$',about_views.index),
    url(r'^contact/$',about_views.contact),
]

urlpatterns = [
    url(r'^$',TemplateView.as_view(template_name='homepage.html')),
    url(r'^about/',include(about_patterns)),
    url(r'^stores/',include(store_patterns),{'location':'headquarters'}),
   ]

Listing 2-13.Django urls.py with inline include statements

清单 2-13 中 url 模式的结果与清单 2-11 和 2-12 相同。区别在于清单 2-13 使用主urls.py文件声明多个 url 列表，而清单 2-11 和 2-12 依赖于在不同文件中声明的 url 列表。

Url 命名和名称空间

项目的内部链接或 url 引用(例如<a href='/'>Home Page</a>)往往是硬编码的，无论是在视图方法中将用户重定向到特定位置，还是在模板中提供足够的用户导航。随着项目的增长，硬编码链接会带来严重的维护问题，因为它会导致难以检测和修复的链接。Django 提供了一种命名 URL 的方法，因此很容易在视图方法和模板中引用它们。

命名 Django urls 最基本的技术是将name属性添加到urls.py中的url定义中。清单 2-14 展示了如何命名一个项目的主页，以及如何从一个视图方法或模板中引用这个 url。

# Definition in urls.py
url(r'^$',TemplateView.as_view(template_name='homepage.html'),name="homepage")

# Definition in view method
from django.http import HttpResponsePermanentRedirect
from django.core.urlresolvers import reverse

def method(request):
    ....
    return HttpResponsePermanentRedirect(reverse('homepage'))

# Definition in template
<a href="{% url 'homepage' %}">Back to home page</a>

Listing 2-14.Django url using name

清单 2-14 中的 url 定义使用了正则表达式r'^$'，它被翻译成/或主页，也称为根目录。注意带有homepage值的name属性。通过给 url 分配一个name,您可以在视图方法和模板中使用这个值作为参考，这意味着将来对 url 正则表达式的任何更改，都会自动更新视图方法和模板中的所有 url 定义。

接下来在清单 2-14 中，您可以看到一个视图方法示例，它将控制重定向到reverse('homepage')。Django reverse方法试图通过给定的名称查找 url 定义——在本例中是homepage——并相应地替换它。类似地，清单 2-14 中的链接示例<a href="{% url 'homepage' %}">Back to home page</a>利用了 Django {% url %}标签，该标签试图通过其第一个参数来查找 url 在本例中是homepage——并相应地替换它。

同样的命名和替换过程也适用于更复杂的 url 定义，比如那些带有参数的定义。清单 2-15 显示了带有参数的 url 的过程。

# Definition in urls.py
url(r'^drinks/(?P<drink_name>\D+)/',TemplateView.as_view(template_name='drinks/index.html'),name="drink"),

# Definition in view method
from django.http import HttpResponsePermanentRedirect
from django.core.urlresolvers import reverse

def method(request):
    ....
    return HttpResponsePermanentRedirect(reverse('drink', args=(drink.name,)))

# Definition in template
<a href="{% url 'drink' drink.name %}">Drink on sale</a>

<a href="{% url 'drink' 'latte' %}">Drink on sale</a>

Listing 2-15.Django url with arguments using name

清单 2-15 中的 url 定义使用了一个更复杂的正则表达式，它带有一个参数，可以转换成形式为/drinks/latte/或/drinks/espresso/的 URL。在这种情况下，url 被赋予参数名drink_name。

因为 url 使用一个参数，reverse方法和{% url %}标记的语法略有不同。reverse方法要求 url 参数作为元组提供给args变量，而{% url %}标签要求 url 参数作为值列表提供。注意，在清单 2-15 中，参数同样可以是变量或硬编码值，只要它匹配 url 参数正则表达式类型——在本例中是非数字。

对于有多个参数的 url 定义，使用reverse和{% url %}的方法是相同的。对于reverse方法，您传递给它一个带有所有必要参数的元组，对于{% url %}标记，您传递给它一个值列表。

Caution

小心使用反向和{% url %}的无效 url 定义。Django 总是在启动时检查所有反向和{% url %}定义是否有效。这意味着如果您在反向方法或{% url %}标记定义中出错——比如 url 名称中的输入错误或参数类型与正则表达式不匹配——应用将不会启动并抛出 HTTP 500 内部错误。

这种情况的误差是NoReverseMatch at....Reverse for 'urlname' with arguments '()' and keyword arguments '{}' not found. X pattern(s) tried。如果您查看错误堆栈，您将能够指出这是在哪里发生的，并纠正它。请注意，这是一个致命的错误，如果它没有被隔离到发生它的视图或页面，它将在启动时停止整个应用。

有时使用属性本身不足以对 URL 进行分类。如果您有两个或三个索引页面，会发生什么情况？或者，如果您有两个符合详细信息条件的 URL，但一个是商店的，另一个是饮料的？

一种简单的方法是使用复合名称(例如，drink_details、store_details)。然而，在这种形式中使用复合名称会导致难以记忆的命名约定和松散的层次结构。Django 支持的一种更简洁的方法是通过namespace属性。

属性允许用一个唯一的限定符来标识一组 URL。因为namespace属性与一组 URL 相关联，所以它与前面描述的include方法一起使用来合并 URL。

清单 2-16 展示了一系列 url 定义，它们利用了包含的名称空间属性。

# Main urls.py
from django.conf.urls import include, url

urlpatterns = [
    url(r'^$',TemplateView.as_view(template_name='homepage.html'),name="homepage"),
    url(r'^about/',include('coffeehouse.about.urls',namespace="about")),
    url(r'^stores/',include('coffeehouse.stores.urls',namespace="stores")),
]

# About urls.py
from . import views

urlpatterns = [
    url(r'^$',views.index,name="index"),
    url(r'^contact/$',views.contact,name="contact"),
]

# Stores urls.py
from . import views

urlpatterns = 
    url(r'^$',views.index,name="index"),
    url(r'^(?P<store_id>\d+)/$',views.detail,name="detail"),
)

# Definition in view method
from django.http import HttpResponsePermanentRedirect
from django.core.urlresolvers import reverse

def method(request):
    ....
    return HttpResponsePermanentRedirect(reverse('about:index'))

# Definition in template
<a href="{% url 'stores:index' %}">Back to stores index</a>

Listing 2-16.Django urls.py

with namespace attribute

清单 [2-16 以一组典型的 Django urls.py主文件的include定义开始。注意这两个定义都使用了namespace属性。接下来，您可以看到在主urls.py文件中引用的urls.py文件，这些文件利用了前面示例中描述的name属性。注意 about 和 stores urls.py文件都有一个带name='index'的 url。

要用名称空间限定 url 名称，可以使用语法<namespace>:<name>。正如您在清单 2-16 的底部看到的，要引用 about urls.py中的索引，您使用about:index，要引用 stores urls.py文件中的索引，您使用stores:index.

namespace 属性也可以嵌套使用语法<namespace1>:<namespace2>:<namespace3>:<name>来引用 URL。清单 2-17 展示了一个嵌套名称空间属性的例子。

# Main urls.py
from django.conf.urls import include, url
from django.views.generic import TemplateView

urlpatterns = [
    url(r'^$',TemplateView.as_view(template_name='homepage.html'),name="homepage"),
    url(r'^stores/',include('coffeehouse.stores.urls',namespace="stores")),
]

# Stores urls.py
from . import views

urlpatterns = [
    url(r'^$',views.index,name="index"),
    url(r'^(?P<store_id>\d+)/$',views.detail,name="detail"),
    url(r'^(?P<store_id>\d+)/about/',include('coffeehouse.about.urls',namespace="about")),
]

# About urls.py
from . import views

urlpatterns = [
    url(r'^$',views.index,name="index"),
    url(r'^contact/$',views.contact,name="contact"),
]

# Definition in view method
from django.http import HttpResponsePermanentRedirect
from django.core.urlresolvers import reverse

def method(request):
    ....
    return HttpResponsePermanentRedirect(reverse('stores:about:index', args=(store.id,)))

# Definition in template
<a href="{% url 'stores:about:index' store.id %}">See about for {{store.name}}</a>

Listing 2-17.Django urls.py with nested namespace attribute

清单 2-17 中的 url 结构与清单 2-16 的不同之处在于，它为每个商店(例如/stores/1/about/)创建了 about url，而不是拥有一个通用的 about URL(例如/about/)。在清单 2-17 的顶部，我们使用namespace="stores"来限定 stores urls.py文件中的所有 URL。

接下来，在 stores urls.py文件中，注意还有另一个带有namespace="about"的include元素来限定 about urls.py中的所有 URL。最后，在 about urls.py文件中，有一些 URL 只使用了name属性。在清单 2-17 的最后一部分，您可以看到嵌套的名称空间是如何与reverse方法和{% url %}标签一起使用的，它们使用一个:来分隔名称空间。

在 99%的 Django urls 中，你可以像描述的那样使用name和namespace参数。然而，当您在同一个项目中部署同一个 Django 应用的多个实例时，namespace参数具有特殊的意义。

因为 Django 应用是具有 url 定义的自包含单元，所以即使 Django 应用使用 url 名称空间，也会出现边缘情况。如果 Django 应用使用名称空间 X，但是您想在同一个项目中部署该应用两次或三次，会发生什么情况？假设每个应用都使用名称空间 X，那么如何引用它们的 URL 呢？这就是术语实例名称空间和app_name属性的由来。

让我们看一个场景，这个场景使用同一个 Django 应用的多个实例来说明这个与 url 名称空间相关的边缘情况。假设您开发了一个名为 banners 的 Django 应用来显示广告。横幅应用的构建方式是，它必须在不同的 URL 上运行(例如，/coffeebanners/、/teabanners/、/foodbanners/)，以简化横幅的选择。本质上，您需要在同一个项目中运行横幅应用的多个实例，每个实例位于不同的 URL 上。

那么多个 app 实例和 url 命名有什么问题呢？它与使用需要根据当前应用实例动态改变的命名 URL 有关。这个问题通过一个例子最容易理解，所以让我们跳到清单 2-18 中的例子。

# Main urls.py
from django.conf.urls import include, url

urlpatterns = [
    url(r'^$',TemplateView.as_view(template_name='homepage.html'),name="homepage"),
    url(r'^coffeebanners/',include('coffeehouse.banners.urls',namespace="coffee-banners")),
    url(r'^teabanners/',include('coffeehouse.banners.urls',namespace="tea-banners")),
    url(r'^foodbanners/',include('coffeehouse.banners.urls',namespace="food-banners")),
]

# Banners urls.py
from django.conf.urls import url
from . import views

urlpatterns = [
    url(r'^$',views.index,name="index"),
]

# Definition in view method
from django.http import HttpResponsePermanentRedirect
from django.core.urlresolvers import reverse

def method(request):
    ....
    return HttpResponsePermanentRedirect(reverse('coffee-banners:index'))
    return HttpResponsePermanentRedirect(reverse('tea-banners:index'))
    return HttpResponsePermanentRedirect(reverse('food-banners:index'))

# Definition in template
<a href="{% url 'coffee-banners:index' %}">Coffee banners</a>
<a href="{% url 'tea-banners:index' %}">Tea banners</a>
<a href="{% url 'food-banners:index' %}">Food banners</a>

Listing 2-18.Django urls.py with multiple instances

of the same app

在清单 2-18 中，你可以看到我们有三个指向同一个coffeehouse.banners.urls文件的 URL，每个都有自己独特的名称空间。接下来，让我们看看清单 2-18 中的各种reverse方法和{% url %}标记示例。

清单 2-18 中的reverse方法和{% url %}标记示例都使用<namespace>:<name>语法解析为三个不同的 url 名称。所以你可以使用namespace和name有效地部署同一个 Django 应用的多个实例。

然而，仅仅依靠namespace和name，解析的 url 名称无法动态适应不同的应用实例，这是与内部应用逻辑相关的边缘情况，必须包含内部应用逻辑以支持 Django 应用的多个实例。现在让我们来看看一个视图和模板场景，它展示了这个场景以及app_name属性如何解决这个问题。

假设在横幅应用中，您想要将控制重定向到应用的主索引 url(例如，由于异常)。现在戴上应用设计师的帽子，你会如何解决这个问题？作为一名应用设计师，你甚至不知道咖啡横幅、茶横幅或食物横幅名称空间，因为这些是部署名称空间。您如何在应用中内部集成重定向，以适应正在部署的应用的多个实例？这就是app_name参数的用途。

清单 2-19 展示了如何利用app_name属性来动态确定重定向到哪里。

# Main urls.py
from django.conf.urls import include, url

urlpatterns = [
    url(r'^$',TemplateView.as_view(template_name='homepage.html'),name="homepage"),
    url(r'^coffeebanners/',include('coffeehouse.banners.urls',namespace="coffee-banners")),
    url(r'^teabanners/',include('coffeehouse.banners.urls',namespace="tea-banners")),
    url(r'^foodbanners/',include('coffeehouse.banners.urls',namespace="food-banners")),
]

# Banners urls.py
from django.conf.urls import url
from . import views

app_name = 'banners_adverts'
urlpatterns = [
    url(r'^$',views.index,name="index"),
]

# Logic inside Banners app
from django.http import HttpResponsePermanentRedirect
from django.core.urlresolvers import reverse

def method(request):
    ....
    try:
       ...
    except:
       return HttpResponsePermanentRedirect(reverse('banners_adverts:index'))

Listing 2-19.Django redirect that leverages app_name to determine url

注意横幅应用的清单 2-19 中的urls.py文件在声明urlpatterns值之前设置了app_name属性。接下来，注意清单 2-19 中的reverse方法使用了banners_adverts:index值，其中banners_adverts代表app_name。这是一个重要的约定，因为 Django 依赖相同的语法来搜索app_name或namespace匹配。

那么你认为banners_adverts:index会解析到什么 url 呢？这完全取决于导航发生在哪里，它是动态的！如果用户在咖啡横幅应用实例(即 url coffeebanners)中导航，那么 Django 将banners_adverts:index解析为咖啡横幅实例索引，如果用户在茶横幅应用实例(即 url teabanners)中导航，那么 Django 将banners_adverts:index解析为茶横幅实例索引，以此类推任何其他数量的实例。如果用户在 banners 应用实例之外导航(即没有应用实例)，Django 默认将banners_adverts:index解析为urls.py中最后定义的实例，这将是 food-banners。

以这种方式并基于用户来自的请求路径实例(例如，如果用户在带有/coffeebanners/或/teabanners/的路径上)，反向方法将banners_adverts:index动态解析为三个 url 应用实例之一，而不是硬编码特定的 url 名称空间，如清单 2-18 所示。

现在让我们假设 banners 应用有一个内部模板，里面有一个到应用主index url 的链接。同样，考虑到多个应用实例的可能性，您将如何在模板中生成这个链接？依靠相同的app_name参数解决了清单 2-20 中所示的模板链接的问题。

# template banners/index.html
<a href="{% url 'banners_adverts:index' %}">{% url 'banners_adverts:index' %}</a>
Listing 2-20.Django template link

that leverages app_name to determine url

注意清单 2-20 中的{% url %}标签指向banners_adverts:index。banners_adverts:index的解析过程与前面使用reverse方法的方法示例中概述的过程相同。

如果用户在咖啡横幅应用实例(即 url coffeebanners)中导航，那么 Django 将banners_adverts:index解析为咖啡横幅实例索引，如果用户在茶横幅应用实例(即 url teabanners)中导航，那么 Django 将banners_adverts:index解析为茶横幅实例索引，以此类推任何其他数量的实例。如果用户在横幅应用实例之外导航(即没有应用实例)，Django 默认将banners_adverts:index解析为urls.py中最后定义的实例，即food-banners。

正如您所看到的，app_name属性的目的是为 Django 应用设计者提供一种内部机制，通过这种机制，可以为动态适应同一应用的多个实例的命名 URL 集成逻辑。由于这个原因，它没有被广泛用于 url 命名，并且在大多数情况下可以被放弃，只使用namespace和name属性。

查看方法请求

到目前为止，您已经使用了 Django 视图方法及其输入——request对象和参数——以及它们的输出，包括生成直接响应或依赖模板生成响应。然而，现在是时候更深入地了解视图方法请求中的可用内容以及生成视图方法响应的各种替代方法了。

到目前为止，您毫无疑问地放在视图方法中的request引用是django.http.request.HttpRequest类的一个实例。 ³ 这个request对象包含由视图方法之前存在的实体设置的信息:用户的 web 浏览器、运行应用的 web 服务器或应用上配置的 Django 中间件类。

下面的列表显示了一些在request参考中最常见的属性和方法:

request.method。-包含用于请求的 HTTP 方法(例如，GET、POST)。
request.GET或request.POST。-包含分别作为 GET 或 POST 请求的一部分添加的参数。参数被括为一个django.http.request.QueryDict ^{4 个} 实例。
- request.POST.get('name',default=None)。-获取 POST 请求中的name参数的值，如果该参数不存在，则获取None。注意default可以用自定义值覆盖。
- request.GET.getlist('drink',default=None)。-获取 GET 请求中的drink参数的值列表，或者如果参数不存在，则获取空列表None。注意default可以用自定义值覆盖。
request.META。-包含由浏览器或 web 服务器作为请求的一部分添加的 HTTP 标头。参数包含在一个标准的 Python 字典中，其中键是 HTTP 头名称——大写和下划线(例如，Content-Length作为键CONTENT_LENGTH)。
- request.META['REMOTE_ADDR']。-获取用户的远程 IP 地址。
request.user。-包含链接到请求的 Django 用户的信息(如用户名、电子邮件)。注意user指的是django.contrib.auth包中的用户，通过 Django 中间件设置，这将在本章后面描述。

正如您可以从这个简短的列表中证明的那样，request引用包含许多可操作的信息来满足业务逻辑(例如，您可以基于来自用户'的 IP 地址的地理位置信息来响应某些内容)。在django.http.request.HttpRequest和django.http.request.QueryDict属性和方法之间有超过 50 个request选项可用，所有这些都在书中相关的部分进行了解释——但是你可以在上一页的脚注链接中查看request选项的完整范围。

一旦您完成了从request引用中提取信息并对其进行相关的业务逻辑处理(例如，查询数据库，从第三方 REST 服务中获取数据)，您就需要在一个视图方法中设置数据，以将其作为响应的一部分发送出去。

要在 Django 视图方法中设置数据，首先需要在方法体中声明或提取数据。您可以声明字符串、数字、列表、元组、字典或任何其他 Python 数据结构。

一旦在视图方法中声明或提取了数据，就可以创建一个字典来使数据在 Django 模板上可访问。字典键代表模板的引用名，而值是数据结构本身。清单 2-21 展示了一个视图方法，它声明了多个数据结构并将它们传递给 Django 模板。

from django.shortcuts import render

def detail(request,store_id='1',location=None):
    # Create fixed data structures to pass to template
    # data could equally come from database queries
    # web services or social APIs
    STORE_NAME = 'Downtown'
    store_address = {'street':'Main #385','city':'San Diego','state':'CA'}
    store_amenities = ['WiFi','A/C']
    store_menu = ((0,''),(1,'Drinks'),(2,'Food'))
    values_for_template = {'store_name':STORE_NAME, 'store_address':store_address, 'store_amenities':store_amenities, 'store_menu':store_menu}
    return render(request,'stores/detail.html', values_for_template)

Listing 2-21.Set up dictionary in Django view method for access in template

注意清单 2-21 中的render方法是如何包含values_for_template字典的。在前面的例子中，render方法只包含了request对象和一个处理请求的模板。在清单 2-21 中，字典作为最后一个render参数被传递。通过将一个字典指定为最后一个参数，该字典对模板可用——在本例中是stores/detail.html。

Tip

如果您计划在多个模板上访问相同的数据，而不是在多个视图上声明它，您可以使用上下文处理器来声明它一次，并使它在所有项目模板上都可以访问。关于 Django 模板的下一章将讨论这个主题。

清单 2-21 中的字典包含键和值，它们是在方法体中声明的数据结构。字典键成为访问 Django 模板中的值的引用。

Output View Method Dictionary in Django Templates

虽然下一章将深入讨论 Django 模板，但是下面的代码片段显示了如何使用{{}}语法输出清单 2-21 中的字典值。

<h4>{{store_name}} store</h4>
<p>{{store_address.street}}</p>
<p>{{store_address.city}},{{store_address.state}}</p>
<hr/>
<p>We offer: {{store_amenities.0}} and {{store_amenities.1}}</p>
<p>Menu includes : {{store_menu.1.1}} and {{store_menu.2.1}}</p>

第一个声明{{store_name}}使用独立键显示Downtown值。其他访问声明使用点(.)符号，因为值本身是复合数据结构。

store_address键包含一个字典，因此要访问内部字典值，可以使用由点(.)分隔的内部字典键。store_address.street显示街道值，store_address.city显示城市值，store_address.state显示州值。

store _ 市容键包含一个使用类似点(.)符号来访问内部值。然而，因为 Python 列表没有键，所以使用列表索引号。store _ facilities . 0 显示列表 store _ facilities 和 store _ facilities 中的第一项。1 显示列表 store _ facilities 中的第二项。

store_menu key包含一个元组，由于缺少键，它也需要一个数字。{{store_menu.1.1}}显示store_menu的第二元组值的第二元组值，{{store_menu.2.1}}显示store_menu的第三元组的第二元组值。

查看方法响应

到目前为止，生成视图方法响应的render()方法实际上是一种快捷方式。你可以在清单 2-21 的顶部看到，render()方法是django.shortcuts包的一部分。

这意味着除了生成视图响应的render()方法之外，还有其他方法，尽管render()方法是最常用的技术。对于初学者来说，有三种类似的方法来生成带有模板支持的数据的视图方法响应，如清单 2-22 所示。

# Option 1)
from django.shortcuts import render

def detail(request,store_id='1',location=None):
    ...
    return render(request,'stores/detail.html', values_for_template)

# Option 2)
from django.template.response import TemplateResponse

def detail(request,store_id='1',location=None):
    ...
    return TemplateResponse(request, 'stores/detail.html', values_for_template)

# Option 3)
from django.http import HttpResponse
from django.template import loader, Context

def detail(request,store_id='1',location=None):
     ...
     response = HttpResponse()
     t = loader.get_template('stores/detail.html')
     c = Context(values_for_template)
     return response.write(t.render(c))

Listing 2-22.Django view method response alternatives

清单 2-22 中的第一个选项是django.shortcuts.render()方法，它显示了生成响应的三个参数:(必需的)request引用、(必需的)模板路由和(可选的)字典——也称为上下文——以及要传递给模板的数据。

清单 2-22 : content_type中没有显示render()方法的另外三个(可选)参数，这些参数为响应设置 HTTP Content-Type头，默认为settings.py中的DEFAULT_CONTENT_TYPE参数，后者本身默认为text/html；status为默认为200的响应设置 HTTP Status代码；和using来指定模板引擎——或者是jinja2或者是django——来生成响应。下一节关于render()方法的 HTTP 处理描述了如何使用content_type & status，而第 3 和 4 章讨论了 Django 和 Jinja 模板引擎。

清单 2-22 中的第二个选项是django.template.response.TemplateResponse()类，它在输入方面与render()方法几乎相同。这两种变体的区别在于，一旦一个视图方法完成后,TemplateResponse()可以改变响应(例如，通过中间件),而render()方法被认为是视图方法完成后生命周期中的最后一步。当您预见到需要在多个视图方法完成工作后修改它们的视图方法响应时，您应该使用TemplateResponse()，这种技术将在本章关于视图方法中间件的后续章节中讨论。

清单 2-22 : content_type中没有显示的TemplateResponse()类还有四个(可选)参数，默认为text/html；status默认为200；charset设置来自 HTTP Content-Type头或settings.py中的DEFAULT_CHARSET的响应编码，其本身默认为utf-8；和using来指示模板引擎——或者jinja2或者django——来生成响应。

清单 2-22 中的第三个选项代表了最长的，但也是最灵活的响应创建过程。这个过程首先创建一个原始的HTTPResponse实例，然后用django.template.loader.get_template()方法加载一个模板，创建一个Context()类将值加载到模板中，最后将一个呈现的模板及其上下文写到HTTPResponse实例中。虽然这是三个选项中最长的一个，但是当视图方法响应需要高级选项时，这是首选。即将到来的关于内联和流式内容的内置响应快捷方式的部分，有更多关于HTTPResponse响应类型的细节。

HTTP 状态和内容类型标头的响应选项

浏览器在请求中设置 HTTP 头，告诉应用在处理时考虑某些特征。类似地，应用在响应中设置 HTTP 头，告诉浏览器考虑发送内容的某些特征。Django 等应用设置的最重要的 HTTP 头是Status和Content-Type。

HTTP Status头是一个三位数的代码，表示给定请求的响应状态。Status值的例子有200，它是成功的 HTTP 请求的标准响应，以及404，它用于指示无法找到请求的资源。HTTP Content-Type报头是一个 MIME(多用途互联网邮件扩展)类型的字符串，用于指示响应中的内容类型。Content-Type值的例子有text/html，它是 HTML 内容响应的标准，以及image/gif，它用于指示响应是 GIF 图像。

默认情况下，除非有错误，所有用django.shortcuts.render()、TemplateResponse()类或HttpResponse()类创建响应的 Django 视图方法——如清单 2-22 所示——创建一个响应，将 HTTP Status值设置为200，将 HTTP Content-Type设置为text/html。虽然这些默认值是最常见的，但是如果您想要发送不同类型的响应(例如，错误或非 HTML 内容)，就有必要修改这些值。

覆盖清单 2-22 中三个选项中任意一个的 HTTP Status和Content-Type头值就像提供额外的参数status和/或content_type一样简单。清单 2-23 展示了这个过程的各种例子。

from django.shortcuts import render

# No method body(s) and only render() example provided for simplicity

# Returns content type text/plain, with default HTTP 200
return render(request,'stores/menu.csv', values_for_template, content_type='text/plain')

# Returns HTTP 404, wtih default text/html
# NOTE: Django has a built-in shortcut & template 404 response, described in the next section
return render(request,'custom/notfound.html',status=404)

# Returns HTTP 500, wtih default text/html
# NOTE: Django has a built-in shortcut & template 500 response, described in the next section
return render(request,'custom/internalerror.html',status=500)

# Returns content type application/json, with default HTTP 200
# NOTE: Django has a built-in shortcut JSON response, described in the next section
return render(request,'stores/menu.json', values_for_template, content_type='application/json')

Listing 2-23.HTTP Content-type and HTTP Status for Django view method responses

清单 2-23 中的第一个例子旨在返回一个包含纯文本内容的响应。注意render方法的content_type参数。清单 2-23 中的第二个和第三个例子将 HTTP Status代码设置为404和500。因为 HTTP Status 404代码用于未找到的资源，所以render方法为此使用了一个特殊的模板。类似地，因为 HTTP Status 500代码用于指示错误，render方法也为此使用了一个特殊的模板。

Tip

Django 有内置的快捷方式和模板来处理 HTTP Status代码404和500，以及 JSON 快捷方式响应，所有这些都将在下一节中描述，您可以使用它们来代替清单 2-23 中的示例。

清单 2-23 中的第四个也是最后一个例子旨在返回一个带有 JavaScript 对象符号(JSON)内容的响应。HTTP Content-Type application/json是通过异步 JavaScript (AJAX)消费 JavaScript 数据的浏览器发出的请求的常见要求。

常见 HTTP 状态的内置响应快捷方式和模板:404(未找到)、500(内部服务器错误)、400(错误请求)和 403(禁止)

虽然 Django 在找不到页面时会自动触发 HTTP 404 Status (Not Found)响应，并且在视图中出现未处理的异常时也会触发 HTTP 500 Status(内部服务器错误)响应，但是它有内置的快捷方式和模板，当您知道最终用户应该获得它们时，这些快捷方式和模板就应该在 Django 视图中明确使用。表 2-3 说明了触发特定 HTTP 状态响应的不同快捷方式。

表 2-3。

Django shortcut exceptions to trigger HTTP statuses

| HTTP 状态代码 | Python 代码示例 | | --- | --- | | 404(未找到) | 从 django.http 导入 Http404 引发 Http404 | | 500(内部服务器错误) | 引发异常 | | 400(错误请求) | 从 django.core.exceptions 导入可疑操作提出可疑操作 | | 403(禁止) | 从 django.core.exceptions 导入权限拒绝提升权限拒绝 |

*Django automatically handles not found pages raising HTTP 404 and unhandled exceptions raising HTTP 500

正如你在表 2-3 的例子中看到的，快捷方式的语法很简单。例如，您可以在 Django 视图中进行评估，如if article_id < 100:或if unpayed_subscription:，并基于结果从表 2-3 中抛出异常，以便最终用户获得正确的 HTTP 状态响应。

那么当表 2-3 中的异常被触发时，除了 HTTP 状态之外，响应中发送的实际内容是什么呢？HTTP 400(错误请求)和 HTTP 403(禁止请求)的默认设置是一个单行 HTML 页面，分别显示“Bad Request (400)和“403 Forbidden”。对于 HTTP 404(未找到)和 HTTP 500(内部服务器错误)，取决于settings.py中的DEBUG值。

如果 Django 项目在settings.py中有DEBUG=True，HTTP 404(未找到)生成一个带有可用 URL 的页面——如图 2-1 所示——HTTP500(内部服务器错误)生成一个带有详细错误的页面——如图 2-2 所示。如果 Django 项目在settings.py中有DEBUG=False，HTTP 404(未找到)会生成一个单行 HTML 页面，显示为“Not Found. The requested URL <url_location> was not found on this server.”，HTTP 500(内部服务器错误)会生成一个单行 HTML 页面，显示为“A server error occurred. Please contact the administrator"。

图 2-2。

HTTP 500 for Django project when DEBUG=True

图 2-1。

HTTP 404 for Django project when DEBUG=True

还可以用定制模板覆盖所有以前的 HTTP 代码的默认响应页面。要使用定制的响应页面，您需要用所需的 HTTP 代码和.html扩展名创建一个模板。例如，对于 HTTP 403，您将创建403.html模板，对于 HTTP 500，您将创建500.html模板。所有这些定制的 HTTP 响应模板都需要放在TEMPLATES变量的DIRS列表中定义的文件夹中，以便 Django 在使用默认的 HTTP 响应模板之前找到它们。

Caution

自定义 404.html 和 500.html 页面仅在 DEBUG=False 时有效。

如果DEBUG=True，无论在正确的位置是否有404.html或500.html模板，Django 都使用默认的响应行为，分别如图 2-1 和图 2-2 所示。您需要设置DEBUG=False以使自定义404.html和500.html模板工作。

在某些情况下，使用定制的 HTTP 响应模板可能还不够。例如，如果您想将上下文数据添加到处理 HTTP 响应的自定义模板中，您需要自定义内置的 Django HTTP view 方法本身，因为没有其他方法可以将数据传递到这种类型的模板中。要定制内置的 Django HTTP 视图方法，您需要在项目的urls.py文件中声明特殊的处理程序。清单 2-24 展示了带有 Django 内置 HTTP Status视图方法的定制处理程序的urls.py文件。

# Overrides the default 400 handler django.views.defaults.bad_request
handler400 = 'coffeehouse.utils.views.bad_request'
# Overrides the default 403 handler django.views.defaults.permission_denied
handler403 = 'coffeehouse.utils.views.permission_denied'
# Overrides the default 404 handler django.views.defaults.page_not_found
handler404 = 'coffeehouse.utils.views.page_not_found'
# Overrides the default 500 handler django.views.defaults.server_error
handler500 = 'coffeehouse.utils.views.server_error'

urlpatterns = [....
]

Listing 2-24.Override built-in Django HTTP Status

view methods in urls.py

Caution

如果 DEBUG=True，handler404 和 handler500 处理程序将无法工作，Django 将继续使用内置的 Django HTTP 视图方法。要使 handler404 和 handler500 处理程序工作，需要设置 DEBUG=False。

正如您在清单 2-24 中看到的，在标准urlpatterns变量的正上方urls.py中有一系列变量。清单 2-24 中的每个变量代表一个 HTTP Status处理程序，其值对应于一个定制的 Django 视图来处理请求。例如，handler400表示所有 HTTP 400请求都应该由 Django 视图方法coffeehouse.utils.views.bad_request处理，而不是默认的django.views.defaults.bad_request。对于使用handler403的 HTTP 403请求、使用handler404的 HTTP 404请求和使用handler500的 HTTP 500 请求，采取相同的方法。

就定制 Django 视图方法的实际结构而言，它们与任何其他 Django 视图方法都是相同的。清单 2-26 显示了清单 2-25 中使用的定制视图方法的结构。

from django.shortcuts import render

def page_not_found(request):
    # Dict to pass to template, data could come from DB query
    values_for_template = {}
    return render(request,'404.html',values_for_template,status=404)

def server_error(request):
    # Dict to pass to template, data could come from DB query
    values_for_template = {}
    return render(request,'500.html',values_for_template,status=500)

def bad_request(request):
    # Dict to pass to template, data could come from DB query
    values_for_template = {}
    return render(request,'400.html',values_for_template,status=400)

def permission_denied(request):
    # Dict to pass to template, data could come from DB query
    values_for_template = {}
    return render(request,'403.html',values_for_template,status=403)

Listing 2-25.Custom views to override built-in Django HTTP view methods

正如您在清单 2-26 中看到的，定制的 HTTP 视图方法使用了与前面的视图方法示例相同的来自django.shortcut s 的render方法。这些方法指向一个由 HTTP Status代码命名的模板，使用一个可以在模板上访问的定制数据字典，并使用status参数来指示 HTTP 状态代码。

内联和流式内容的内置响应快捷方式

所有先前的视图响应示例都是基于通过模板结构化的内容来工作的。然而，有时使用模板输出响应是不必要的(例如，一行响应说“这里没有什么可看的”)。

其他时候，响应使用模板是没有意义的，例如 HTTP 301(永久重定向)或 HTTP 302(重定向)，其中响应只需要一个重定向 url。表 2-4 说明了触发 HTTP 重定向的不同快捷方式。

表 2-4。

Django shortcuts for HTTP redirects

| HTTP 状态代码 | Python 代码示例 | | --- | --- | | 301(永久重定向) | 从 django.http 导入 HttpResponsePermanentRedirect 返回 HttpResponsePermanentRedirect("/") | | 302(重定向) | 从 django.http 导入 httpresponserdirect 返回 httpresponserdirect("/") |

表 2-4 中的两个示例都重定向到应用的主页(即"/")。但是，您也可以将重定向设置为任何应用 url，甚至是不同域上的完整 url(例如， http://maps.google.com/ )。

除了响应重定向快捷方式，Django 还提供了一系列响应快捷方式，您可以在其中添加内联响应。表 2-5 说明了具有内嵌内容响应的 HTTP 状态代码的各种其他快捷方式。

表 2-5。

Django shortcuts for inline and streaming content responses

| 目的或 HTTP 状态代码 | Python 代码示例 | | --- | --- | | 304(未修改) | 从 django.http 导入 HttpResponseNotModified 返回 HttpResponseNotModified()* | | 400(错误请求) | 从 django.http 导入 HttpResponseBadRequest 返回 HttpResponseBadRequest("

请求看起来不对劲

") |
| 404(未找到) | 从 django.http 导入 HttpResponseNotFound 返回 HttpResponseNotFound("

Ups，我们找不到那个页面

方法不允许使用

Ups，这是我们的失误，抱歉！

)) |
| 将数据序列化为 JSON 的内联响应(默认为 HTTP 200 和内容类型 application/json) | 从 django.http 导入 JSON response data _ dict = { ' name ':' Downtown '，' address':'Main #385 '，' city':'San Diego '，' state':'CA'}返回 JsonResponse(data_dict) |
| 流数据内联响应(默认为 HTTP 200 和流内容，它是字符串的迭代器) | 从 django.http 导入 StreamingHttpResponse 返回 streaming httpresponse(large _ data _ structure) |
| 流二进制文件的内联响应(默认为 HTTP 200 和流内容) | 从 django.http 导入文件响应返回文件响应(open('Report.pdf '，' rb ')) |
| 带有任何 HTTP 状态代码的内联响应(默认为 HTTP 200) | 从 django.http 导入 HttpResponse 返回 HttpResponse("

Django 内联响应

") |

The HTTP 304 status code indicates a “Not Modified” response, so you can't send content in the response, it should always be empty.

正如您在表 2-5 的示例中所看到的，有多种快捷方式可以生成带有内嵌内容的不同 HTTP 状态响应，并且完全不需要使用模板。另外，你可以看到表 2-5 中的快捷键也可以接受content_type参数，如果内容是 HTML 以外的东西(即content_type=text/html)。

由于非 HTML 响应在 web 应用中变得非常普遍，您可以看到表 2-5 还显示了三个 Django 内置的响应快捷方式来输出非 HTML 内容。JsonResponse类用于将内联响应转换成 JavaScript 对象符号(JSON)。因为这个响应将有效负载转换为 JSON 数据结构，所以它会自动将内容类型设置为application/json。StreamingHttpResponse类的设计目的是在不需要将整个有效负载放在内存中的情况下传输响应，这种情况有助于大型有效负载响应。FileResponse类是StreamingHttpResponse的子类，旨在传输二进制数据(如 PDF 或图像文件)。

这将我们带到表 2-5 中的最后一个条目，即HttpResponse类。事实证明，表 2-5 中的所有快捷方式都是HttpResponse类的定制子类，我最初在清单 2-22 中将其描述为创建视图响应的最灵活的技术之一。

HttpResponse方法有助于为没有直接快捷方法的 HTTP 状态代码创建响应(例如，HTTP408[请求超时]，HTTP429[太多请求])，或者包含性地利用模板来生成内联响应，如清单 2-26 所示。

from django.http import HttpResponse
from django.utils import timezone
from django.template import loader, Context

response = HttpResponse(content_type='text/csv')
response['Content-Disposition'] = 'attachment; filename=Users_%s.csv' % str(timezone.now().today())
t = loader.get_template('dashboard/users_csvexport.html')
c = Context({'users': sorted_users,})
response.write(t.render(c))
return response

Listing 2-26.HttpResponse with template and custom CSV file download

清单 2-26 中的HTTPResponse对象是用text/csv内容类型生成的，用来通知请求方(例如浏览器)它即将接收 CSV 内容。接下来，Content-Disposition报头还告诉请求方(例如浏览器)尝试下载名为Users_%s.csv的内容，其中用当前服务器日期替换了%s。

接下来，使用loader模块，我们使用get_template方法加载模板users_csvexport.html，该模板将具有类似 CSV 的结构，带有数据占位符。然后我们创建一个Context对象来保存将填充模板的数据，在本例中，它只是一个名为 u sers的变量。接下来，我们用context对象调用模板的render方法，以便用数据填充模板的数据占位符。最后，通过write方法将渲染后的模板写入response对象，并返回response对象。

HttpResponse类在属性和方法之间提供了 20 多个选项， ⁵ 以及content_type和status参数。

视图方法中间件

在大多数情况下，在视图方法中，请求和响应中的数据是以逐段的方式添加、删除或更新的。然而，有时将这些更改应用于所有请求和响应会很方便。

例如，如果您想在所有视图方法上访问某些数据，使用中间件类使这些数据可以跨所有请求访问会更容易。就像您想对所有响应进行安全检查一样，使用中间件类更容易在全局范围内完成。

因为中间件是一个相当抽象的概念，所以在我描述 Django 中间件类的结构之前，我将带您浏览各种内置的 Django 中间件类，这样您就可以更好地理解中间件在哪里是好的设计选择。

内置中间件类

Django 配备了一系列中间件类，其中一些在所有 Django 项目中默认启用。如果你打开 Django 项目的settings.py文件，你会注意到MIDDLEWARE变量，其默认内容如清单 2-27 所示。

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]
Listing 2-27.Default Django middleware classes in MIDDLEWARE

正如您在清单 2-27 中看到的，Django 项目在开箱即用状态下启用了七个中间件类，因此所有请求和响应都被设置为通过这七个类运行。如果您计划利用 Django 的主要特性，我建议您不要删除这些默认的中间件类。但是，如果您愿意，可以将MIDDLEWARE变量留空；请注意这样做可能会破坏 Django 的某些功能。

为了让您更好地理解清单 2-27 中的 Django 中间件类的功能，并帮助您做出是否禁用它们的更明智的决定，表 2-6 描述了每个中间件类的功能。

表 2-6。

Django default middleware classes and functionality

| 中间件类 | 功能 | | --- | --- | | django . middleware . security . security 中间件 | 提供安全性增强，例如:基于 SECURE_SSL_REDIRECT 和 SECURE_SSL_HOST 设置的 SSL 重定向。通过各种设置实现严格的运输安全。 | | django . contrib . sessions . middleware . session middleware | 启用会话支持。 | | django . middleware . common . common 中间件 | 提供一组通用的功能，例如:禁止访问 DISALLOWED_USER_AGENTS 设置中的用户代理，该设置可以是已编译的正则表达式对象的列表。根据 APPEND_SLASH 和 PREPEND_WWW 设置执行 url 重写，以便规范化 URL。为非流式响应设置 HTTP Content-Length 标头。 | | django . middleware . csrf . csrfview middleware | 通过在发布表单中添加隐藏的表单域并检查请求的正确值，来防止跨站点请求伪造。 | | django . contraib . auth . middleware . authenticationmiddleware | 将表示当前登录用户的用户属性添加到每个传入的 HttpRequest 对象中。注意:这个中间件类依赖于中间件 django . contrib . sessions . middleware . session middleware 的功能，必须出现在它的后面。 | | django . IB . messages . middleware . message middleware .讯息中介软体 | 启用基于 cookie 和基于会话的消息支持。注意:这个中间件类依赖于中间件 django . contrib . sessions . middleware . session middleware 的功能，必须出现在它的后面。 | | django . middleware . click packing . xframoptions middleware . django .中介软体 | 通过 X-Frame-Options 标题提供点击劫持保护。关于什么是点击劫持的更多细节请参见: [`http://en.wikipedia.org/wiki/Clickjacking`](http://en.wikipedia.org/wiki/Clickjacking) 。 |

正如您在表 2-6 中所看到的，尽管各种默认中间件类的目的差异很大，但它们的功能适用于需要在项目中所有请求或响应中应用的特性。

表 2-6 中中间件类的另一个重要因素是一些依赖于另一些。例如，AuthenticationMiddleware类的设计是基于这样的假设，即它可以访问由SessionMiddleware类提供的功能。这种依赖性很重要，因为它使得中间件类定义顺序相关(例如，在MIDDLEWARE中，某些中间件类需要在其他类之前定义)，这个主题我将在下一节中详细阐述。

除了表 2-6 中给出的默认中间件类，Django 还提供了其他中间件类。表 2-7 展示了你可以在你的项目中利用的 Django 中间件类的剩余集合，这对你没有必要从头开始编写中间件类很有帮助。

表 2-7。

Other Django middleware classes and functionality

| 中间件类 | 功能 | | --- | --- | | django . middleware . cache .updatecache 中间件 | 响应阶段缓存中间件，如果响应可缓存，则更新缓存。注意:UpdateCacheMiddleware 必须是中间件中的第一部分，以便在响应阶段最后调用它。 | | django . middleware . cache . fetchfromcachemiddleware | 从缓存中获取页面的请求阶段缓存中间件。注意:FetchFromCacheMiddleware 必须是中间件中的最后一部分，这样它将在请求阶段最后被调用。 | | django . middleware . common . broken link mail middleware | 向经理发送断开链接通知电子邮件。 | | django，中间件，exceptionmiddleware | Django 使用这个中间件，不管您是否将它包含在中间件中；但是，如果您自己的中间件需要将它处理的异常转换成适当的响应，您可能希望创建子类。 | | django . middleware . gzip . gzip middleware | 为理解 GZip 压缩的浏览器压缩内容。注意:GZipMiddleware 应该放在任何其他需要读取或写入响应体的中间件之前，以便压缩发生在之后。只有当请求方在 HTTP Accept-Encoding 头上发送 gzip，并且内容大于 200 个字节，并且响应没有设置 HTTP Content-Encoding 头时，这个中间件才会进行压缩。 | | django.middleware.http | 处理条件 GET 操作。如果响应没有 HTTP ETag 头，则会添加一个。如果响应有一个 ETag 或 Last-Modified 头，而请求有 If-None-Match 或 If-Modified-Since，则响应被替换为 HttpNotModified。 | | Django，中间件，本地，本地 | 解析请求并决定在当前线程上下文中安装什么翻译对象。这允许页面被动态地翻译成用户想要的语言。 | | django . contrib . sites . middleware . currentsitemiddleware | 将表示当前站点的站点属性添加到每个传入的 HttpRequest 对象中。 | | django . contraib . auth . middleware . persistent treomeusermiddleware | 添加 REMOTE_USER -在请求中可用。META -通过外部来源(如 web 服务器)进行 Django 认证。 | | django . contraib . auth . middleware . remote user middleware | 允许 web 服务器提供的身份验证。如果 request.user 没有通过身份验证，这个中间件会尝试对 REMOTE_USER 请求头中传递的用户名进行身份验证。如果身份验证成功，用户将自动登录，以便将用户保留在会话中。 | | django . contraib . flatpages . middleware . flatpagefallback middleware . django . flatpages 回退中间件 | 每当 Django 应用引发 404 错误时，这个中间件都会检查 flatpages 数据库中所请求的 url，这是最后的手段。 | | django . contrib . redirects . middleware . redirectfallback middleware | 每次 Django 应用引发 404 错误时，这个中间件都会检查重定向数据库中请求的 url，这是最后一招。 |

现在您已经了解了 Django 的内置中间件类以及它们的用途，让我们来看看中间件类的结构及其执行过程。

中间件结构和执行过程

Django 中间件类有两个必需的方法和三个可选的方法，它们在视图请求/响应生命周期的不同点执行。清单 2-28 展示了一个示例中间件类及其各个部分。

class CoffeehouseMiddleware(object):

    def __init__(self, get_response):
        self.get_response = get_response
        # One-time configuration and initialization on start-up

    def __call__(self, request):
        # Logic executed on a request before the view (and other middleware) is called.

        # get_response call triggers next phase
        response = self.get_response(request)

        # Logic executed on response after the view is called.

        # Return response to finish middleware sequence
        return response

    def process_view(self, request, view_func, view_args, view_kwargs):
        # Logic executed before a call to view
        # Gives access to the view itself & arguments

    def process_exception(self,request, exception):
        # Logic executed if an exception/error occurs in the view

    def process_template_response(self,request, response):
        # Logic executed after the view is called,
        # ONLY IF view response is TemplateResponse, see listing 2-22

Listing 2-28.Django middleware class structure

为了让视图方法执行清单 2-28 中的 Django 中间件类，必须将中间件类添加到settings.py中的MIDDLEWARE变量中。例如，如果清单 2-28 中的CoffeehouseMiddleware类存储在coffeehouse/utils/项目文件夹下名为middleware.py的文件/模块中，您可以将coffeehouse.utils.middleware.CoffeeMiddleware语句添加到settings.py中的MIDDLEWARE值列表中。

接下来，我将描述清单 2-28 中显示的所有 Django 中间件类中所需的两个方法:

__init__。-在所有 Python 类中用于引导对象实例。Django 中间件类中的__init__方法只在支持 Django 应用的 web 服务器启动时被调用一次。Django 中间件中的__init__方法必须声明一个get_response输入，它表示对先前中间件类响应的引用。get_response输入被分配给一个实例变量——也称为get_response——稍后用于中间件类的主处理逻辑。当我扩展 Django 中间件的执行过程时，get_response引用的目的将会变得更加清晰。
__call__。-在所有 Python 类中使用，将对象实例作为函数调用。每个应用请求都会调用 Django 中间件类中的__call__方法。正如您在清单 2-28 中看到的，__call__方法声明了一个request输入，它表示视图方法使用的同一个HttpRequest对象。__call__方法分为三个阶段:
- 在视图方法调用之前。-一旦触发了__call__方法，您就有机会在将request引用传递给视图方法之前对其进行修改。如果你想在request中添加或修改一些东西，在它被移交给一个视图方法之前，这就是要做的阶段。
- 触发视图方法调用。-在您修改(或不修改)原始的request之后，您必须将控制权移交给 view 方法，以便它能够运行。当您将request传递给在__init__方法中设置的self.get_response参考时，该阶段被触发。这个阶段实际上是在说，“我已经完成了对request的修改，继续把它交给视图方法，这样它就可以运行了。”
- Post 视图方法调用。-一旦查看方法完成，结果将被分配给__call__中的response引用。在这个阶段，您有机会在视图方法完成后执行逻辑。您可以通过简单地从视图方法返回response引用(即return response)来退出这个阶段。

这是这两个必需方法执行的每个 Django 中间件类背后的核心逻辑。现在让我们看看清单 2-28 中给出的三个可选中间件类方法:

process_view。-所需的中间件方法——__init__和__call__——缺乏任何关于他们正在使用的视图方法的知识。在视图方法被触发之前，process_view方法允许您访问视图方法及其参数。如果存在，process_view中间件方法在__call__之后和调用self.get_response(request)之前被调用，这触发了视图方法。
process_exception。-如果视图方法的逻辑中出现错误，就会调用process_exception中间件方法，让您有机会执行错误后清理逻辑。
process_template_response。-在调用 self.get_response(request)并且视图方法完成后，可能需要更改响应本身以对其执行附加逻辑(例如，修改上下文或模板)。如果存在的话，process_template_response中间件方法会在视图方法完成后被调用，让您有机会修改响应。

Warning

只有当视图方法返回 TemplateResponse 时，才会触发 process_template_response 中间件方法。如果视图方法使用 render()生成响应，则不会触发 process_template_response。更多细节请参见查看方法响应的清单 2-22 。

总之，单个中间件类的执行过程如下:

__init__方法被触发(在服务器启动时)。
__call__触发的方法(针对每个请求)。
如果声明，process_view()方法被触发。
查看方法从__call__中的self.get_response(request)语句开始。
如果声明，process_exception()方法在视图中发生异常时触发。
查看方法完成。
如果声明，当视图返回TemplateResponse时process_template_response()被触发。

尽管理解单个中间件类的执行过程很重要，但更重要的方面是理解多个中间件类的执行过程。正如我在本节开始时提到的，Django 项目支持清单 2-27 中所示的七个中间件类，因此多个中间件类的执行更像是常态而不是例外。

Django 中间件类是背靠背执行的，但是 view 方法代表了它们执行顺序中的一个转折点。清单 2-27 中默认中间件类的执行顺序如下:

Server start-up

__init__ on django.middleware.security.SecurityMiddleware called
__init__ on django.contrib.sessions.middleware.SessionMiddleware called
__init__ on django.middleware.common.CommonMiddleware called
__init__ on django.middleware.csrf.CsrfViewMiddleware called
__init__ on django.contrib.auth.middleware.AuthenticationMiddleware called
__init__ on django.contrib.messages.middleware.MessageMiddleware called
__init__ on django.middleware.clickjacking.XframeOptionsMiddleware called

request for index() view method

__call__ on django.middleware.security.SecurityMiddleware called
process_view on django.middleware.security.SecurityMiddleware called (if declared)
__call__ on django.contrib.sessions.middleware.SessionMiddleware called
process_view on django.contrib.sessions.middleware.SessionMiddleware called (if declared)
__call__ on django.middleware.common.CommonMiddleware called
process_view on django.middleware.common.CommonMiddleware called (if declared)
__call__ on django.middleware.csrf.CsrfViewMiddleware called
process_view on django.middleware.csrf.CsrfViewMiddleware called (if declared)
__call__ on django.contrib.auth.middleware.AuthenticationMiddleware called
process_view on django.contrib.auth.middleware.AuthenticationMiddleware called (if declared)
__call__ on django.contrib.messages.middleware.MessageMiddleware called
process_view on django.contrib.messages.middleware.MessageMiddleware called (if declared)
__call__ on django.middleware.clickjacking.XframeOptionsMiddleware called
process_view on django.middleware.clickjacking.XframeOptionsMiddleware called (if declared)

start index() view method logic

if an exception occurs in index() view
process_exception on django.middleware.clickjacking.XframeOptionsMiddleware called (if declared)
process_exception on django.contrib.messages.middleware.MessageMiddleware called (if declared)
process_exception on django.contrib.auth.middleware.AuthenticationMiddleware called(if declared)
process_exception on django.middleware.csrf.CsrfViewMiddleware called (if declared)
process_exception on django.middleware.common.CommonMiddleware called (if declared)
process_exception on django.contrib.sessions.middleware.SessionMiddleware called (if declared)
process_exception on django.middleware.security.SecurityMiddleware called (if declared)

if index() view returns TemplateResponse
process_template_response on django.middleware.clickjacking.XframeOptionsMiddleware called (if declared)
process_template_response on django.contrib.messages.middleware.MessageMiddleware called (if declared)
process_template_response on django.contrib.auth.middleware.AuthenticationMiddleware called(if declared)
process_template_response on django.middleware.csrf.CsrfViewMiddleware called (if declared)
process_template_response on django.middleware.common.CommonMiddleware called (if declared)
process_template_response on django.contrib.sessions.middleware.SessionMiddleware called (if declared)
process_template_response on django.middleware.security.SecurityMiddleware called (if declared)

请注意，在进入视图方法的执行之前，中间件类的执行顺序遵循声明的顺序(即，先声明的先运行，最后声明的最后运行)。但是，一旦执行了视图方法，中间件的执行顺序就会颠倒(即，最后声明的先运行，首先声明的最后运行)。

这种行为类似于拔塞钻，要到达中心(视图方法)，您需要向一个方向移动(1 到 7)，要向外移动，您需要向相反的方向移动(7 到 1)。因此中间件方法process_exception和process_template_response以__init__、__call__和process_view的相反顺序执行。

清单 2-27 中默认 Django 中间件类的执行过程如图 2-3 所示。

图 2-3。

Django middleware execution process

查看方法中的中间件 Flash 消息

当用户执行一个操作(例如，提交一个表单)时，通常会使用快速消息，并且有必要告诉他们该操作是成功的还是有某种错误。其他时候，快速消息用作网页上的一次性通知，告诉用户某些事件(例如，网站维护或特殊折扣)。图 2-4 显示了一组示例简讯。

图 2-4。

Web page flash messages Django Flash Messages Require a Django App, Middleware, and a Template Context Processor

默认情况下，所有 Django 项目都支持 flash 消息。但是，如果您调整了项目的 settings.py 文件，您可能会无意中禁用了 flash 消息。

为了使 Django flash 消息工作，您必须确保在 settings.py 中设置以下值:变量 INSTALLED_APPS 具有 django.contrib.messages 值，变量 MIDDLEWARE 具有 Django . contrib . messages . messages . message MIDDLEWARE 值，并且模板变量的选项中的 context_processors 列表具有 Django . contrib . messages . context _ processors . messages 值。

正如您在图 2-4 中看到的，可以有不同类型的 flash 消息，在技术上称为级别。Django 遵循标准的 Syslog 标准严重性级别，并支持表 2-8 中描述的五个内置消息级别。

表 2-8。

Django built-in flash messages

| 水平常数 | 标签 | 价值 | 目的 | | --- | --- | --- | --- | | 调试 | 调试 | Ten | 在生产部署中将被忽略(或删除)的开发相关消息。 | | 信息 | 信息 | Twenty | 用户的信息性消息。 | | 成功ˌ成就 | 成功 | Twenty-five | 操作成功，例如，“联系信息已成功发送” | | 警告 | 警告 | Thirty | 故障没有发生，但可能即将发生。 | | 错误 | 错误 | Forty | 操作不成功或发生了其他故障。 |

添加即时消息

Django flash 消息是基于每个请求进行管理的，并被添加到视图方法中，因为这是确定 flash 消息是否被授权的最佳位置。要添加消息，您可以使用django.contrib.messages包。

用django.contrib.messages包添加 flash 消息有两种技术:一种是通用的add_message()方法，另一种是表 2-8 中描述的不同级别的快捷方式方法。清单 2-29 展示了不同的技术。

from django.contrib import messages

# Generic add_message method
messages.add_message(request, messages.DEBUG, 'The following SQL statements were executed: %s' % sqlqueries) # Debug messages ignored by default
messages.add_message(request, messages.INFO, 'All items on this page have free shipping.')
messages.add_message(request, messages.SUCCESS, 'Email sent successfully.')
messages.add_message(request, messages.WARNING, 'You will need to change your password in one week.')
messages.add_message(request, messages.ERROR, 'We could not process your request at this time.')

# Shortcut level methods
messages.debug(request, 'The following SQL statements were executed: %s' % sqlqueries) # Debug messages ignored by default
messages.info(request, 'All items on this page have free shipping.')
messages.success(request, 'Email sent successfully.')
messages.warning(request, 'You will need to change your password in one week.')
messages.error(request, 'We could not process your request at this time.')

Listing 2-29.Techniques to add Django flash messages

清单 2-29 中的第一组样本使用add_message()方法，而第二组样本使用快捷方式级别方法。清单 2-29 中的两组样本产生相同的结果。

如果你仔细观察清单 2-29 ，你会注意到两个DEBUG级消息都有行尾注释# Ignored by default。Django 消息框架默认处理所有高于INFO级别的消息，这意味着DEBUG消息——如表 2-8 所述，是一个较低级别的消息阈值——被忽略，即使它们可能被定义。

您可以更改默认的 Django 消息级别阈值，以包含所有消息级别，或者包含性地降低默认的INFO阈值。默认的消息级别阈值可以用两种方法之一来改变:用清单 2-30 中所示的MESSAGE_LEVEL变量在settings.py中全局地(即对于整个项目)改变，或者用清单 2-31 中所示的django.contrib.messages包的set_level方法在每个请求的基础上改变。

# Reduce threshold to DEBUG level in settings.py
from django.contrib.messages import constants as message_constants
MESSAGE_LEVEL = message_constants.DEBUG

# Increase threshold to WARNING level in setting.py
from django.contrib.messages import constants as message_constants
MESSAGE_LEVEL = message_constants.WARNING

Listing 2-30.Set default Django message level globally in settings.py

# Reduce threshold to DEBUG level per request
from django.contrib import messages
messages.set_level(request, messages.DEBUG)

# Increase threshold to WARNING level per request
from django.contrib import messages
messages.set_level(request, messages.WARNING)

Listing 2-31.Set default Django message level on a per request basis

清单 2-30 中的第一个MESSAGE_LEVEL定义将默认消息级别更改为DEBUG，这意味着所有消息级别定义都会得到处理，因为DEBUG是最低的阈值。清单 2-30 中的第二个MESSAGE_LEVEL定义将默认消息级别更改为WARNING，这意味着处理高于WARNING(含)的消息级别(即WARNING和ERROR)。

清单 2-31 中的第一个set_level定义将默认的请求消息级别更改为DEBUG，这意味着所有的消息级别定义都会得到处理，因为DEBUG是最低的阈值。清单 2-31 中的第二个set_level定义将默认消息级别更改为WARNING，这意味着处理高于WARNING(含)的消息级别(即WARNING和ERROR)。

如果您同时定义了两个默认的消息级别机制，默认的请求消息级别优先于默认的全局消息级别定义(例如，如果您定义了messages.set_level(request, messages.WARNING)，则处理高于WARNING(包含)的消息级别，即使全局MESSAGE_LEVEL变量被设置为MESSAGE_LEVEL = message_constants.DEBUG以包含所有消息。

除了设置 flash 消息和了解忽略来自某个级别的消息的内置阈值机制之外，您还必须认识到清单 2-29 中的消息定义假设 Django 消息框架的先决条件在settings.py中声明——如本节开始的侧栏中所述。

因为您最终可能会将 Django 项目发布给第三方，并且无法控制最终的部署settings.py文件，所以 Django messages 框架提供了在必要的先决条件没有在settings.py.中声明的情况下静默忽略消息定义的能力。为了在没有声明先决条件的情况下静默忽略消息定义，您可以向任何一种添加消息的技术添加fail_silently=True属性，如清单 2-32 所示。

from django.contrib import messages

# Generic add_message method, with fail_silently=True
messages.add_message(request, messages.INFO, 'All items on this page have free shipping.',fail_silently=True)

# Shortcut level method, with fail_silently=True
messages.info(request, 'All items on this page have free shipping.',fail_silently=True)

Listing 2-32.Use of the fail_silently=True attribute to ignore errors in case Django messages framework not installed

现在您已经知道了如何添加消息以及添加消息时需要记住的重要方面，让我们来看看如何访问消息。

访问即时消息

您最常访问 Django flash 消息的地方是显示给最终用户的 Django 模板。作为一种快捷方式，感谢上下文处理器django.contrib.messages.context_processors.messages Django flash 消息通过messages变量在所有模板上可用。但是在我们开始实际的模板示例之前，让我们快速看一下 Django flash 消息的结构。

当您使用上一节描述的技术之一添加 Django flash 消息时，Django 会创建一个storage.base.Message类的实例。表 2-9 描述了storage.base.Message级的结构。

表 2-9。

Django storage.base.Message structure

| 属性 | 描述 | 例子 | | --- | --- | --- | | 消息 | 消息的实际文本。 | 此页面上的所有项目都有免费送货。 | | 水平 | 描述消息类型的整数(见表 2-8 中的值列)。 | Twenty | | 标签 | 由空格分隔的所有消息标记(extra_tags 和 level_tag)组合而成的字符串。 | 信息 | | 额外标签 | 包含此消息的自定义标记的字符串，用空格分隔。 | 默认情况下为空。 | | 级别标签 | 级别的字符串表示形式。 | 信息 |

正如您在表 2-9 中看到的，您可以利用几个属性在 Django 模板中显示。清单 2-33 显示了样板模板代码，您可以用它来显示请求中设置的所有 flash 消息。

{% if messages %}
<ul class="messages">
    {% for msg in messages %}
    <li>
        <div class="alert alert-{{msg.level_tag}}" role="alert">
        {{msg.message}}
        </div>
    </li>
    {% endfor %}
</ul>
{% endif %}
Listing 2-33.
Boilerplate code

to use in Django template to display Django flash messages

清单 2-33 从检查messages变量是否存在开始——它包含所有的 flash 消息——如果存在，那么一个 HTML 列表从<ul>开始。接下来，对messages中的所有元素进行循环，其中每个元素对应于一个storage.base.Message实例。对于这些元素中的每一个，都创建了一个列表和部分标签——<li>和<div>——将level_tag属性作为 CSS 类输出，将消息属性作为<div>内容输出。

您可以根据需要修改清单 2-33 中的样板代码，例如，添加条件并输出特定的消息级别，或者利用其他storage.base.Message属性，等等。

Note

清单 2-33 中的 HTML 代码使用 CSS class = " alert alert-{ { msg . level_tag } } "，该代码根据 level _ tag 属性呈现为 class="alert alert-info "或 class="alert alert-success "。这些 CSS 类是 CSS 引导框架的一部分。通过这种方式，你可以快速格式化 flash 消息，看起来如图 2-2 所示。

虽然您通常会在 Django 模板中访问 Django flash 消息，但这并不意味着您不能在其他地方访问它们，比如视图方法。您还可以通过django.contrib.messages包的get_messages()方法访问请求中的 Django flash 消息。清单 2-34 展示了使用get_messages()方法的代码片段。

from django.contrib import messages

the_req_messages = messages.get_messages(request)
for msg in the_req_messages:
    do_something_with_the_flash_message(msg)

Listing 2-34.Use of get_messages() method

to access Django flash messages

在清单 2-34 中，get_messages()方法接收request作为输入，并将结果赋给the_req_messages变量。接下来，对the_req_messages中的所有元素进行循环，其中每个元素都对应于一个storage.base.Message实例。对于这些元素中的每一个，都会调用方法do_something_with_the_flash_message来处理每个 flash 消息。

访问 Django flash 消息时需要理解的一个重要方面是消息本身的持续时间。Django flash 消息被标记为在主 messages 实例上发生迭代时被清除，并在处理响应时被清除。

对于 Django 模板中的访问，这意味着如果你不能在 Django 模板中像清单 2-33 中那样进行迭代，并且请求中有 flash 消息，这可能会导致陈旧或幻影消息出现在其他地方，直到进行迭代并处理响应。对于 Django 视图方法中的访问(即使用get_messages())，这没有影响，因为即使您可以对主消息实例进行迭代——因此，将消息标记为待清除——在 Django 视图方法中不会处理响应，因此消息永远不会被清除，只是被标记为待清除。

基于类的视图

在第一章和本章的开始——在清单 2-1——你看到了如何定义一个 Django url 并使它在不需要视图方法的情况下使用 Django 模板操作。这可能是由于django.views.generic.TemplateView类，它被称为基于类的视图。

与使用 Django HttpRequest输入参数并输出 Django HttpResponse的标准 Python 方法支持的 Django 视图方法不同，基于类的视图通过成熟的 Python 类提供其功能。这反过来又允许 Django 视图按照面向对象编程(OOP)原则(例如封装、多态和继承)进行操作，从而提高可重用性并缩短实现时间。

尽管基于 Django 类的视图代表了一种更强大的创建 Django 视图的方法，但它们只是到目前为止您所使用的视图方法的一种替代方法。如果您想在 Django 请求上快速执行业务逻辑，您可以继续使用视图方法，但是对于要求更高的视图需求(例如表单处理、样板模型查询)，基于类的视图可以节省您大量的时间。

内置的基于类的视图

由django.views.generic.TemplateView基于类的视图提供的功能确实节省了时间。虽然可以配置一个 url 来执行一个空视图方法，然后将控制发送给一个模板，但是TemplateView类允许这个过程在一行中完成。

除了TemplateView基于类的视图之外，Django 还提供了许多其他内置的基于类的视图，使用类似 OOP 的原则来缩短普通 Django 视图操作的创建过程。表 2-10 展示了 Django 的内置视图类。

表 2-10。

Built-in classes for views

| 班级 | 描述 | | --- | --- | | django.views.generic.View | 所有基于类的视图的父类，提供核心功能。 | | django . views . generic . template view | 允许 url 返回模板的内容，而不需要视图。 | | django . views . generic . redirect view | 允许 url 执行重定向，而不需要视图。 | | django . views . generic . archive index view django . views . generic . yeararchiveview django . views . generic . monthararchiveview django . views . generic . weekarchiveview django . views . generic . dayarchiveview django . views . generic . todayarchiveview django . views . generic . date detail view | 允许视图返回基于日期的对象结果，而无需显式执行 Django 模型查询。 | | django . views . generic . create view django . views . generic . detail view django . views . generic . update view django . views . generic . delete view django . views . generic . listview django . views . generic . formview | 允许视图执行创建-读取-更新-删除(CRUD)操作，而不需要显式执行 Django 模型查询。 |

在本章接下来也是最后一节，我将解释表 2-10 上半部分的类，这样你可以更好地理解 Django 基于类的视图的结构和执行过程。表 2-10 下半部分中涉及 Django 模型的基于类的视图在关于 Django 模型的单独章节中描述。

基于类的视图结构和执行

要创建基于类的视图，您需要创建一个从表 2-10 中的一个类继承而来的类。清单 2-35 显示了使用这种继承技术的基于类的视图，以及执行基于类的视图的相应 url 定义。

# views.py
from django.views.generic import TemplateView

class AboutIndex(TemplateView):
      template_name = 'index.html'

      def get_context_data(self, **kwargs):
         # **kwargs contains keyword context initialization values (if any)
         # Call base implementation to get a context
         context = super(AboutIndex, self).get_context_data(**kwargs)
         # Add context data to pass to template
         context['aboutdata'] = 'Custom data'
         return context

#urls.py
from coffeehouse.about.views import AboutIndex

urlpatterns = [
    url(r'^about/index/',AboutIndex.as_view(),{'onsale':True}),
]

Listing 2-35.Class-based view inherited from TemplateView

with url definition

我选择首先创建一个继承自TemplateView的视图，因为它很简单，而且您已经知道了这个类的用途。清单 2-35 中的例子和本章中清单 2-1 中的第一个例子产生了几乎相同的结果。

不同之处在于，清单 2-1 直接声明了一个TemplateView类实例作为 url 的一部分(例如TemplateView.as_view(template_name='index.html'))，而清单 2-35 声明了一个名为AboutIndex的TemplateView子类的实例。比较这两种方法，您可以对基于类的视图的 OOP 行为有一个初步的感觉。

清单 2-35 的第一部分声明了基于AboutIndex类的视图，它从TemplateView类继承了它的行为。注意这个类声明了template_name属性和get_context_data()方法。

AboutIndex类中的template_name值充当基于类的视图的默认模板。但是在 OOP 方式中，相同的值可以通过在实例创建时提供一个值来覆盖(例如，AboutIndex.as_view(template_name='other.html')使用other.html模板)。

AboutIndex类中的get_context_data方法允许您向类视图模板添加上下文数据。请注意，get_context_data方法的签名使用**kwargs来访问上下文初始化值(例如，在 url 或父类视图中声明的值),并根据标准 OOP Python 实践使用 Python super()方法调用父类的get_context_data方法。接下来，get_context_data方法使用aboutdata键添加额外的上下文数据，并返回修改后的context引用。

在清单 2-35 的第二部分中，您可以看到基于AboutIndex类的视图是如何首先导入到一个urls.py文件中，然后连接到一个 url 定义。注意基于类的视图是如何使用as_view()方法在url定义上声明的。此外，请注意 url 定义如何声明 url 额外选项{'onsale':True}，该选项作为上下文数据传递给基于类的视图(即在get_context_data方法的**kwargs中)。

Tip

所有基于类的视图都使用 as_view()方法集成到 url 定义中。

现在您已经对 Django 基于类的视图有了基本的了解，清单 2-36 展示了另一个基于类的视图，它有不同的实现细节。

# views.py
from django.views.generic import View
from django.http import HttpResponse
from django.shortcuts import render

class ContactPage(View):
    mytemplate = 'contact.html'
    unsupported = 'Unsupported operation'

    def get(self, request):
        return render(request, self.mytemplate)

    def post(self, request):
        return HttpResponse(self.unsupported)

#urls.py
from coffeehouse.contact.views import ContactPage

urlpatterns = [
    url(r'^contact/$',ContactPage.as_view()),
]

Listing 2-36.Class-based view inherited from View with multiple HTTP handling

清单 2-36 中的第一个区别是基于类的视图继承了通用类django.views.generic.View的行为。如表 2-10 所示，View类为所有基于类的视图提供核心功能。所以事实上，清单 2-35 中使用的TemplateView类是View的子类，这意味着使用TemplateView的基于类的视图可以访问使用View的基于类的视图的相同功能。

您选择一个类而不是另一个类来实现基于类的视图的原因根植于 OOP 多态性原则。例如，在 OOP 中你可以有一个饮料→咖啡→拿铁的类层次结构，其中饮料类提供了可用于饮料、咖啡和拿铁实例的通用功能；Coffee 类提供了更多适用于 Coffee 和后续实例的特定功能；Latte 类提供了仅适用于 Latte 实例的最具体的功能。

因此，如果您事先知道您需要一个基于类的视图来放弃对模板的控制，而不应用复杂的业务逻辑或定制的请求和响应处理，那么与更通用的View类相比，TemplateView类提供了最快的解决方案。扩展同样的原则，一旦你开始使用 Django 模型和视图，你会发现表 2-10 中一些更专业的基于类的视图也比创建一个从通用View类继承的基于类的视图提供更快的解决方案。现在你知道了为什么你会选择一个基于View类的视图而不是一个更专业的类，让我们来分解清单 2-36 中的功能。

注意基于类的视图ContactPage声明了两个属性:mytemplate和unsupported。这些是通用的类属性，我使用了mytemplate名称来说明与清单 2-35 和TemplateView基于类的视图中使用的template_name属性没有关系。从TemplateView派生的基于类的视图需要一个template_name值，并自动使用这个模板来生成响应。然而，从View类派生的基于类的视图并不期望特定的模板，而是期望您实现如何生成响应，这就是清单 2-36 中的get和post方法发挥作用的地方。

get方法用于处理视图上的 HTTP GET 请求，而post方法用于视图上的 HTTP POST 请求。这提供了一种更加模块化的方法来处理不同的 HTTP 操作，而标准视图方法需要显式地检查请求并创建条件来处理不同的 HTTP 操作。目前，不要担心 HTTP GET 和 HTTP POST 视图处理；Django 表格中对此进行了更详细的探讨，其中主题更具相关性。

接下来，注意到get和post方法都声明了一个request输入，它表示一个 Django HttpRequest实例，就像标准视图方法一样。在这两种情况下，方法都会立即返回响应，但是在生成响应之前，可以检查请求值或执行任何业务逻辑，就像在标准视图方法中一样。

get方法使用django.shortcuts.render方法生成响应，而post方法使用HttpResponse类生成响应，这两种方法都是在标准视图方法中用于生成响应的相同技术。清单 2-36 中唯一微小的区别是render方法和HttpResponse类都使用实例属性(例如self.mytemplate、self.unsupported)来生成响应，但除此之外，您可以自由地返回一个 Django HttpResponse，其中包含本章已经解释过的任何变体(例如，清单 2-22 响应替代，表 2-5 快捷响应)。

最后，清单 2-36 中的最后一部分展示了如何将ContactPage基于类的视图导入到urls.py文件中，然后使用as_view()方法连接到一个 url。

为了结束对基于类的视图和本章的讨论，我们来看一下django.views.generic.RedirectView类。类似于TemplateView基于类的视图允许您快速生成响应而不需要视图方法，而RedirectView基于类的视图允许您快速生成 HTTP 重定向——就像表 2-4 中描述的那样——不需要视图方法。

RedirectView类支持以下列表中描述的四个属性:

permanent。-默认为False执行表 2-4 中描述的HttpResponseRedirect类支持的非永久重定向。如果设置为True，则使用表 2-4 中描述的HttpResponsePermanentRedirect类进行永久重定向。
url。-默认为None。定义执行重定向的 url 值。
pattern_name。-默认为None。定义一个 url 名称，通过reverse方法生成一个重定向 url。注意reverse方法在本章前面的 url 命名和名称空间部分已经解释过了。
query_string。-默认为False将查询字符串附加到重定向 url。如果提供，重定向 url 的query_string值。

至此，我们结束了对 Django 视图和 URL 的探索。在接下来的两章中，您将了解 Django 模板和 Jinja 模板。

Footnotes 1

http://www.apress.com/la/book/9781590594414

https://docs.python.org/3/howto/regex.html#non-capturing-and-named-groups

https://docs.djangoproject.com/en/1.11/_modules/django/http/request/#HttpRequest

https://docs.djangoproject.com/en/1.11/_modules/django/http/request/#QueryDict

https://docs.djangoproject.com/en/1.11/ref/request-response/#django.http.HttpResponse

三、Django 模板

Django 模板定义了在视图方法处理完请求后发送给最终用户的布局和最终格式。在本章中，您将学习 Django 模板使用的语法、Django 模板可用的配置选项，以及各种 Django 模板构造(例如过滤器、标签、上下文处理器),这些构造允许您创建精细的布局并将格式应用于呈现给最终用户的内容。

Django 模板语法

虽然有超过 100 个内置的构造可以帮助你构建 Django 模板——所有这些你都将在本章中学习到——但是首先，这些是你需要认识的最重要的语法元素:

{{output_variable}}。-开头和结尾用双花括号括起来的值表示变量的输出。Django 视图、url 选项或上下文处理器将变量传递到模板中。在模板中，您可以使用{{}}来输出变量的内容，以及使用 Python 的点符号来输出变量的更深层次的元素(例如，字段、键、方法)。例如，{{store.name}}告诉 Django 模板输出store变量的name，其中store可以是一个object，而name可以是一个字段，或者store可以是一个字典，而name可以是一个键。
{% tag %}。-用百分号括起来的大括号括起来的值称为标记。Django 标签提供了包装在简单语法表示中的复杂格式化逻辑。
variable|filter。-竖线|后声明的值称为过滤器。Django 过滤器提供了一种将格式化逻辑应用于单个变量的方法。

Django 模板中除了这三种变体之外的任何其他语法都被“照原样”处理。这意味着如果一个模板声明了超文本标记语言(HTML)标题<h1>Welcome!</h1>，用户将得到一个大的 HTML 标题。就这么简单。

但是让我们来看看一个不太明显的 Django 模板语法行为，它很重要，你必须马上理解，因为它是几乎所有与 Django 模板相关的事物中反复出现的主题。

自动转义:HTML 和安全方面的错误

Django 项目在 Web 上运行，所以默认情况下所有模板都被假定为产生 HTML。虽然这是一个合理的假设，但它并不合理，除非你面临以下两种情况之一:

你不能确保 Django 模板产生有效的 HTML，事实上可能会产生危险的标记。
您希望 Django 模板生成非 HTML 内容，比如逗号分隔值(CSV)、可扩展标记语言(XML)或 JavaScript 对象符号(JSON)。

那么，您怎么可能在 Django 模板中引入无效的 HTML 甚至危险的内容呢？这是互联网，来自其他用户或提供商的内容可能会出现在您的 Django 模板中，从而导致问题(例如，用户提交的数据、第三方服务、来自数据库的内容)。

问题不在于你直接放在 Django 模板中的内容——因为你输入的内容是有效的——问题在于通过变量、标签、过滤器和上下文处理器放置的动态内容，它有可能来自任何地方。让我们使用以下变量对此进行进一步分析:

store_legend = "<b>Open since 1965!</b>"

js_user_date = "<script>var user_date = new Date()</script>"

如果带有这种内容的变量进入 Django 模板，并且您试图输出它们，它们会被逐字输出。store_legend不会作为 HTML 粗体语句输出，而是由<b>和</b>包围的语句。类似地，js_user_date不会产生带有用户浏览器本地日期的 JavaScript 变量，而是逐字输出<script>语句。

这是因为在默认情况下，Django 会自动转义动态结构(即变量、标签、过滤器和上下文处理器)中的内容。表 3-1 显示了字符 Django 默认自动转义。

表 3-1。

Characters Django auto-escapes by default

| 原始字符 | 逃到 | | --- | --- | | < | < | | > | > | | (单引号) | ' | | “(双引号) | " | | & | & |

正如您在表 3-1 中看到的，Django 自动转义包括将潜在冲突甚至危险的字符——在 HTML 的上下文中——转换成等价的可视表示，也称为转义字符。 ¹

之所以这样做，是因为恶意用户或未经检查的来源可以轻松生成包含表 3-1 左列字符的内容，这可能会破坏用户界面或执行恶意 JavaScript 代码。所以 Django 为了安全起见会出错，并自动将表 3-1 中的字符换成等价的可视化表示。虽然你当然可以禁用表 3-1 中字符的自动转义，但这必须显式完成，因为这代表着安全风险。

虽然自动转义对于 HTML 输出来说是一个很好的安全预防措施，但这将我们带到假设 Django 总是生成 HTML 的第二点。如果 Django 模板必须输出 CSV、JSON 或 XML 内容，而像<、>、'(单引号)、"(双引号)和&这样的字符对内容消费者有特殊的意义，并且不能使用等效的视觉表示，那么会发生什么呢？在这种情况下，您还需要显式禁用 Django 强制的默认自动转义行为。

因此，无论您想通过 Django 模板中的变量输出实际的 HTML，还是输出 CSV、JSON 或 XML，而 Django 没有对这些内容应用 HTML 安全实践，您都需要处理 Django 自动转义。

在 Django 模板中有各种方法来控制自动转义(例如，全局地，单独的变量，单独的过滤器)，你将在本章的学习中了解到这些。但是自动转义是 Django 模板中的一个永恒主题，还有以下相关术语:

安全。-如果 Django 模板构造被标记为安全，这意味着表 3-1 中没有字符被转义。换句话说，安全等于“我知道我在做什么”输出内容“原样”。
逃跑。-如果 Django 模板构造被标记为转义，这意味着表 3-1 中的字符被转义。换句话说，escape 等于“确保没有潜在危险的 HTML 字符被输出，使用等效的可视化表示。”
自动逃生开/自动逃生关(安全)。-如果 Django 模板使用 auto-escape on，这意味着该范围内的 Django 模板构造应该对表 3-1 中的字符进行转义。如果 Django 模板使用自动转义关闭，这意味着该范围内的 Django 模板构造应该“按原样”输出，而不是对表 3-1 中的字符进行转义。

就这样，我们结束了关于 Django 自动逃脱这个相当枯燥但重要的话题的谈话。接下来，让我们探索 Django 模板的各种配置选项。

Django 模板配置

默认情况下，由于settings.py中的TEMPLATES变量，所有 Django 项目上都启用了 Django 模板。清单 3-1 展示了 Django 项目中的默认TEMPLATES值。

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]
Listing 3-1.Default Django template configuration in settings.py

BACKEND变量表示项目使用 Django 模板。DIRS和APP_DIRS变量告诉 Django 在哪里定位 Django 模板，这将在下一节解释。OPTIONS中的context_processors字段告诉 Django 为 Django 项目启用哪些上下文处理器。简而言之，上下文处理器提供了跨所有 Django 模板共享数据的能力，而不需要在 Django 视图中以零碎的方式定义它。

本章后面的部分描述了默认 Django 上下文处理器提供的数据，以及如何编写自己的上下文处理器来共享所有 Django 模板上的定制数据。

模板搜索路径

Django 根据变量DIRS和APP_DIRS中的值决定在哪里寻找模板。正如您在清单 3-1 中看到的，Django 默认为空的DIRS值，并将APP_DIRS变量设置为真。

设置为True的APP_DIRS变量告诉 Django 在名为templates的 Django 应用子文件夹中寻找模板——如果你从未听说过 Django 应用的概念，请看第一章，它描述了这个概念。

APP_DIRS行为有助于将应用的模板包含到应用的结构中，但请注意，模板搜索路径不知道应用的名称空间。例如，如果你有两个应用都依赖于一个名为index.html的模板，并且这两个应用在views.py中都有一个将控制权返回给index.html模板的方法(例如render(request,'index.html')，那么这两个应用都将使用INSTALLED_APPS中最顶层声明的应用的index.html，因此只有一个应用将使用预期的index.html。

清单 3-2 中展示的第一组文件夹显示了两个 Django 应用，它们具有这种潜在的模板布局冲突。

# Templates directly under templates folder can cause loading conflicts
+---+-<PROJECT_DIR_project_name_conflict>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
    |
    +-about(app)-+
    |            +-__init__.py
    |            +-models.py
    |            +-tests.py
    |            +-views.py
    |            +-templates-+
    |                        |
    |                        +-index.html
    +-stores(app)-+
                 +-__init__.py
                 +-models.py
                 +-tests.py
                 +-views.py
                 +-templates-+
                             |
                             +-index.html

# Templates classified with additional namespace avoid loading conflicts
+---+-<PROJECT_DIR_project_name_namespace>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
    |
    +-about(app)-+
    |            +-__init__.py
    |            +-models.py
    |            +-tests.py
    |            +-views.py
    |            +-templates-+
    |                        |
    |                        +-about-+
    |                                |
    |                                +-index.html
    +-stores(app)-+
                 +-__init__.py
                 +-models.py
                 +-tests.py
                 +-views.py
                 +-templates-+
                             |
                             +-stores-+
                                      |
                                      +-index.html

Listing 3-2.Django apps with templates dirs with potential conflict and namespace qualification

为了解决这个潜在的模板搜索冲突，推荐的做法是在每个templates目录中添加一个额外的子文件夹作为名称空间，如清单 3-2 中的第二组文件夹所示。

通过这种方式，您可以使用这个额外的命名空间子文件夹将控件重定向到模板，以避免任何歧义。因此，要将控制权发送给about/index.html模板，您应该声明render(request,'about/index.html')，要将控制权发送给stores/index.html，您应该声明render(request,'stores/index.html')。

如果您希望禁止这种允许从这些内部应用子文件夹加载模板的行为，您可以通过将APP_DIRS设置为FALSE来实现。

定义 Django 模板的一个更常见的方法是在应用结构之外建立一个或多个文件夹来保存 Django 模板。为了让 Django 找到这样的模板，可以使用清单 3-3 中所示的DIRS变量。

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['%s/templates/' % (PROJECT_DIR),
                 '%s/dev_templates/' % (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Listing 3-3.
DIRS definition

with relative path in settings.py

正如您在清单 3-3 中看到的，您可以在DIRS变量中声明各种目录。Django 在DIRS值中寻找模板，然后在应用的templates文件夹中寻找模板——如果APP_DIRS是TRUE——直到找到匹配的模板或者抛出TemplateDoesNotExist错误。

还要注意清单 3-3 中的DIRS值依赖于由PROJECT_DIR变量动态确定的路径。当您在不同的机器上部署 Django 项目时，这种方法很有帮助，因为该路径是相对于顶级 Django 项目目录的(即，settings.py和主urls.py文件所在的位置)，并且不管 Django 项目安装在哪里(例如，/var/www/、/opt/website/、C://website/)，该路径都会动态调整。

无效的模板变量

默认情况下，Django 模板在包含无效变量时不会抛出错误。这是因为与 Django admin 相关的设计选择也使用了 Django 模板。

虽然在大多数情况下这不是一个大问题，但是对于调试任务来说，这可能会令人沮丧，因为 Django 不会通知您拼写错误或未定义的变量。例如，您可以输入{{datee}}而不是{{date}}，Django 通过输出一个空字符串''来忽略这一点，您也可以忘记在视图方法中将一个变量值传递给一个模板，Django 也静默地输出一个空字符串''，即使您可能已经在模板中定义了它。

要让 Django 在遇到 Django 模板中的无效变量时通知您，您可以使用string_if_invalid选项。清单 3-4 中显示的string_if_invalid的第一个配置选项输出一个可见字符串，而不是空字符串''。

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['%s/templates/' % (PROJECT_DIR),'%s/dev_templates/' % (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'string_if_invalid': "**** WARNING INVALID VARIABLE %s ****",
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Listing 3-4.
Output warning message

for invalid template variables with string_if_invalid

正如您在清单 3-4 中看到的，string_if_invalid被赋予了字符串"**** WARNING INVALID VARIABLE %s ****"。当 Django 遇到一个无效变量时，它用这个字符串替换出现的变量，其中的%s变量被替换为无效的变量名，这让您可以很容易地定位哪里和哪些变量是无效的。

string_if_invalid选项的另一个配置选项是在遇到无效变量时执行更复杂的逻辑。例如，清单 3-5 展示了在发现无效变量的情况下，如何引发错误以使模板无法呈现。

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

class InvalidTemplateVariable(str):
    def __mod__(self,other):
        from django.template.base import TemplateSyntaxError
        raise TemplateSyntaxError("Invalid variable : '%s'" % other)

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['%s/templates/' % (PROJECT_DIR),'%s/dev_templates/' % (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'string_if_invalid': InvalidTemplateVariable("%s"),
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Listing 3-5.
Error generation

for invalid template variables with string_if_invalid

在清单中，3-5 string_if_invalid被赋予使用%s输入变量的InvalidTemplateVariable类，它代表无效的变量名——就像清单 3-4 中的前一个例子一样。

InvalidTemplateVariable类很有趣，因为它继承了str(string)类的行为，并使用了 Python __mod__(模)魔法方法实现。虽然__mod__(模)魔术方法适合数字运算，但在这种情况下，它很有用，因为传入的字符串使用了%(模)符号，这使得__mod__方法运行。在__mod__方法中，我们只是用无效的变量名引发TemplateSyntaxError错误来暂停模板的执行。

Caution

Django admin 可能会被自定义的string_if_invalid值破坏。

由于某些显示的复杂程度，Django 管理模板特别依赖默认的string_if_invalid输出空字符串''。事实上，这种string_if_invalid默认行为通常被认为是一种“特性”，就像它被认为是一种“缺陷”或“烦恼”一样

因此，如果您使用清单 3-4 或清单 3-5 中的一种方法来覆盖string_if_invalid，请注意您很可能会损坏或中断 Django 管理页面。如果您依赖 Django admin，那么您应该只使用这些技术来调试项目的模板。

调试输出

当您使用顶级DEBUG=True设置运行 Django 项目并出现错误时，Django 模板会输出一个非常详细的页面，以使调试过程更容易——参见第五章了解关于DEBUG变量的更多细节，特别是“Django settings.py用于真实世界”一节

默认情况下，Django 模板重用顶级的DEBUG变量值来配置模板调试活动。在幕后，这个配置是通过TEMPLATES变量的OPTIONS内的调试字段设置的。图 3-1 说明了DEBUG=True时错误页面的样子。

图 3-1。

Django error page when DEBUG=True automatically sets template OPTION to ‘debug’:True

正如你在图 3-1 中看到的，Django 打印了模板的位置，以及模板本身的一个片段，以便于定位错误。该模板信息是由'debug':True选项生成的，该选项是基于顶级DEBUG变量设置的。但是，您可以显式地将调试选项设置为False，如清单 3-6 所示，在这种情况下，错误页面将没有任何模板细节，只有回溯信息，如图 3-2 所示。

图 3-2。

Django error page when DEBUG=True and explicit OPTION ‘debug’:False

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['%s/templates/' % (PROJECT_DIR),'%s/dev_templates/' % (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'debug':False,
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Listing 3-6.Option with debug equals False omits template details

自动退出

默认情况下，Django 模板使用安全惯例来自动转义某些字符——如表 3-1 所述——包含在动态生成的结构中(例如变量、标签、过滤器)。自动转义将可能破坏用户界面或产生危险结果的字符转换成安全的表示形式，这个过程在本章的第一节中有所描述。

然而，你可以在所有 Django 模板上全局禁用自动转义——并且故意渲染< as as >等...-OPTIONS中的autoescape字段如清单 3-7 所示。

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['%s/templates/' % (PROJECT_DIR),'%s/dev_templates/' % (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'autoescape':False,
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Listing 3-7.Option with auto-escape equals False omits auto-escaping on all Django templates

值得一提的是，在每个 Django 模板上禁用自动转义的另一种方法——如清单 3-7 所示——是有选择地禁用自动转义。您可以使用{% autoescape off %}标签来禁用 Django 模板的一部分的自动转义，或者使用safe过滤器来禁用单个 Django 模板变量的自动转义。

如果你决定禁用所有 Django 模板的自动转义，如清单 3-7 所示——坦白地说，如果你打算只使用 HTML，由于潜在的安全风险，我不建议这样做——如果需要，你也可以再次精确地启用自动转义。您可以使用{% autoescape on %}标签对 Django 模板的一部分启用自动转义，或者使用escape过滤器对单个 Django 模板变量进行转义。

文件字符集

Python 项目中使用的文件通常在顶部声明一个基于 Python PEP-263 规范的编码值(如# -*- coding: utf-8 -*-),²，以确保文件中的字符被正确解释。在 Django 模板中，你不用这种方式定义底层文件的编码，而是在项目的settings.py文件中定义。

有两种方法可以声明 Django 模板的编码字符:显式地作为TEMPLATES变量中OPTIONS的file_charset字段的一部分，或者通过settings.py中的顶级FILE_CHARSET变量。在OPTIONS中的file_charset中的显式声明优先于FILE_CHARSET赋值，但是file_charset的值默认为FILE_CHARSET，其本身默认为 utf-8 (Unicode)编码。

所以默认情况下，Django 模板编码被指定为 utf-8 或 Unicode，这是软件中使用最广泛的编码之一。尽管如此，如果您决定将数据合并到与 utf-8 不兼容的 Django 模板中(例如，带有重音符号的西班牙元音，如编码为 ISO-8859-1 的á或é，或日本汉字字符，如漢或者字编码为 JIS)您必须在项目的settings.py文件中定义FILE_CHARSET值——或者直接在TEMPLATES内OPTIONS的file_charset字段中定义——这样 Django 模板数据才能被正确解释。

Django 模板可以被赋予 Python 标准编码值中的任何编码值。 ³

自动访问定制模板标签/过滤器模块

Django 模板可以访问一系列内置的标签和过滤器，不需要任何设置步骤。但是，如果您计划使用第三方模板标签/过滤器模块或者编写自己的模板标签/过滤器模块，那么您需要在每个 Django 模板上设置带有{% load %}标签(例如{% load really_useful_tags_and_filters %})的访问，如果您需要访问几十或几百个模板上的特定标签/过滤器，这个过程可能会很烦人。

要自动访问第三方模板标签/过滤器或您自己的模板标签/过滤器，就像它们是内置标签/过滤器一样(即，不需要{% load %}标签)，您可以使用OPTIONS中的builtins字段，如清单 3-8 所示。

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['%s/templates/' % (PROJECT_DIR),'%s/dev_templates/' % (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
            'builtins': [
                 'coffeehouse.builtins',
                 'thirdpartyapp.customtags.really_useful_tags_and_filters',
            ],
        },
    },
]

Listing 3-8.Option with builtins to gain automatic access to tags/filters on all templates

正如您在清单 3-8 中看到的，builtins字段接受一个模块列表，该列表包含用于内置处理的标签/过滤器。在这种情况下，coffeehouse.builtins代表一个名为coffeehouse的项目下的builtins.py文件——它包含定制的标签/过滤器。而thirdpartyapp.customtags.really_useful_tags_and_filters是一个带有标签/过滤器的第三方包，我们也想在 Django 模板中访问它，而不需要使用{% load %}标签。

第三方模板标签/过滤器模块和自定义模板标签/过滤器模块的另一个默认行为是，它们需要使用其原始标签/名称作为参考，而后者还需要将其放在注册的 Django 应用中名为templatetags的文件夹内。这两个默认行为可以用OPTIONS中的libraries字段覆盖，如清单 3-9 所示。

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['%s/templates/' % (PROJECT_DIR),'%s/dev_templates/' % (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
            'libraries': {
                 'coffeehouse_tags': 'coffeehouse.tags_filters.common',
            },
        },
    },
]

Listing 3-9.Option with libraries to register tags/filters with alternative label/name and under any project directory

清单 3-9 'coffeehouse_tags': 'coffeehouse.tags_filters.common'中的 libraries 语句告诉 Django 从coffeehouse项目的tags_filters文件夹中加载common.py文件——包括定制标签/过滤器——并通过coffeehouse_tags引用(例如{% load coffeehouse_tags %})使模板可以访问它。使用清单 3-9 中的方法，您可以在 Django 项目中的任何地方放置定制的标签/过滤器模块，并且为定制的标签/过滤器模块——或者第三方标签/过滤器模块——分配一个替代的参考值，而不是它们原来的标签/名称。

模板加载器

在前面的“模板搜索路径”一节中，我描述了 Django 如何使用DIRS和APP_DIRS变量搜索模板，这是 Django 模板配置的一部分。然而，我有意忽略了与这个模板搜索过程相关的一个更深层的方面:每个搜索机制都由一个模板加载器支持。

模板加载器是一个 Python 类，它实现了搜索和加载模板所需的实际逻辑。表 3-2 展示了 Django 中可用的内置模板加载器。

表 3-2。

Built-in Django template loaders

| 模板加载器类 | 描述 | | --- | --- | | django . template . loaders . file system . loader | 在 DIRS 变量中声明的目录中搜索并加载模板。当 DIRS 不为空时，默认启用。 | | django . template . loaders . app _ directory。装货设备 | 从 INSTALLED_APPS 中声明的所有应用中名为 templates 的子目录中搜索并加载模板。当 APP_DIRS 为真时，默认情况下启用。 | | django . template . loaders . cached . loader | 从文件系统或应用目录加载程序加载模板后，从内存缓存中搜索模板。 | | django . template . Loader . location mem . loader .模板. loader | 从 Python 字典加载模板后，从内存缓存中搜索模板。 |

正如你所看到的，表 3-2 中的两个 Django 模板加载器是由DIRS或APP_DIRS变量自动设置的。然而，表 3-2 中的任何模板加载器都可以使用TEMPLATES内OPTIONS中的loaders字段进行明确设置。

创建可重复使用的模板

模板倾向于具有在多个实例中同等使用的公共部分。例如，无论一个项目有 5 个还是 100 个模板，所有模板的页眉和页脚部分很少改变。其他模板部分，如菜单和广告，也属于这种在多个模板中保持不变的内容类别。所有这些都会导致多个模板的重复，这可以通过创建可重用的模板来避免。

使用可重用的 Django 模板，您可以在单独的模板上定义公共部分，并在其他模板中重用它们。此过程使创建和管理项目模板变得容易，因为单个模板更新会影响所有模板。

可重用的 Django 模板还允许您定义页面块来逐页覆盖内容。此过程使项目的模板更加模块化，因为您定义了顶级块来建立整体布局并逐页定义内容。

让我们朝着构建可重用的 Django 模板迈出第一步，探索 Django 内置的{% block %}标签。清单 3-10 展示了一个名为base.html的模板的第一行，带有几个{% block %}标签。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>{% block title%}Default title{% endblock title %}</title>
    <meta name="description" content="{% block metadescription%}{% endblock metadescription %}">
    <meta name="keywords" content="{% block metakeywords%}{% endblock metakeywords %}">
Listing 3-10.Django template with {% block %} tags

注意清单 3-10 中的语法{% block <name>%}{% endblock <name> %}。每个{% block %}标签都有一个引用名。其他 Django 模板使用引用名来覆盖每个块的内容。

例如，HTML <title>标签中的{% block title %}标签定义了一个网页标题。如果另一个模板重用清单 3-10 中的模板，它可以通过覆盖标题块来定义自己的网页标题。如果未在模板上覆盖块，则块将接收块中的默认内容。对于title块，默认内容是Default title，对于metadescription和metakeywords块，默认内容是一个空字符串。

清单 3-10 中所示的相同机制可用于定义任意数量的块(例如，内容、菜单、页眉、页脚)。值得一提的是{% endblock <name> %}的<name>参数是可选的，仅使用{% endblock %}来结束一个 block 语句是有效的；但是，前一种技术使得 block 语句的结束位置更加清晰，这在一个模板有多个块时尤其有用。

尽管可以通过 Django 视图方法或 url 请求直接调用清单 3-10 中的模板，但这种模板的目的是将其用作其他模板的基础模板。要重用 Django 模板，可以使用 Django 内置的{% extends %}标签。

{% extends %}标签使用语法{% extends <name> %}来重用另一个模板的布局。这意味着为了重用在文件base.html中定义的清单 3-10 中的布局，您使用语法{% extends "base.html" %}。此外，如果使用{% extends %}标签，它必须是 Django 模板中的第一个定义，如清单 3-11 所示。

{% extends "base.html" %}
{% block title %}Coffeehouse home page{% endblock title %}
Listing 3-11.Django template with {% extends %} and {% block %} tag

Tip

在{% extend %}标记语句中，值也可以使用相对路径(例如，“../base.html”)，以及由视图传递的变量，该变量可以是字符串(例如，“master.html”)或视图中加载的模板对象。

注意清单 3-11 中第一个模板语句是如何{% extends "base.html" %}的。此外，注意清单 3-11 是如何用内容Coffeehouse home page定义{% block title %}标签的。清单 3-11 中的块覆盖了base.html模板中的标题栏。那么清单 3-11 中的 HTML <title>标签在哪里呢？没有，你也不需要。Django 自动重用来自base.html模板的布局，并在必要的地方替换块内容。

重用其他模板的 Django 模板倾向于使用有限的布局元素(例如 HTML 标签)和更多的 Django block语句来覆盖内容。这是有益的，因为正如我前面所概述的，它允许您一次建立整体布局，并在逐页的基础上定义内容。

Django 模板的可重用性可以多次出现。例如，您可以拥有模板 A、B 和 C，其中 B 要求重用 A，但是 C 要求重用 B 的一部分，唯一的区别是模板 C 需要使用{% extends "B" %}标签而不是{% extends "A"%}标签。但是由于模板 B 重用了 A，模板 C 也可以访问模板 A 中的相同元素。

当重用 Django 模板时，也可以从父模板访问块内容。Django 通过引用block.super公开父模板中的块内容。清单 3-12 展示了三个模板，展示了包含网页路径或“面包屑”的块的这种机制

# base.html template
<p>{% block breadcrumb %}Home{% endblock breadcrumb %}</p>

# index.html template
{% extends "base.html" %}
{% block breadcrumb %}Main{% endblock breadcrumb %}

# detail.html template
{% extends "index.html" %}
{% block breadcrumb %} {{block.super}} : Detail {% endblock breadcrumb %}

Listing 3-12.Django templates use of {{block.super}} with three reusable templates

清单 3-12 中的base.html模板用默认值Home定义了breadcrumb块。接下来，index.html模板重用base.html模板并用值Main覆盖breadcrumb块。最后，detail.html模板重用index.html模板并覆盖breadcrumb块值。但是，请注意最后一个块覆盖中的{{block.super}}语句。因为{{block.super}}在breadcrumb块中，{{block.super}}告诉 Django 从父模板块中获取内容。

Django 模板中的另一个可重用功能是将一个 Django 模板包含在另一个 Django 模板中。Django 通过{% include %}标签支持这个功能。

{% include %}标签需要一个模板参数——类似于{% extend %}标签——它可以是硬编码的字符串引用(如{% include "footer.html" %})、模板的相对路径(如{% include "../header.html" %})，或者是视图传递的变量，可以是视图中加载的字符串或模板对象。

声明为{% include %}标签一部分的模板知道声明它们的模板中的上下文变量。这意味着如果模板 A 使用了{% include "footer.html" %}标签，模板 A 的变量就会自动地为footer.html模板所用。

包含性地，可以使用with关键字显式地为{% include %}语句提供上下文变量。例如，{% include "footer.html" with year="2013" %}语句使得year变量可以在footer.html模板中访问。{% include %}标签还支持使用with符号传递多个变量的能力(例如{% include "footer.html" with year="2013" copyright="Creative Commons" %})。

最后，如果您希望声明为{% include %}标签一部分的模板能够限制声明它们的模板对上下文变量的访问，那么您可以使用only关键字。例如，如果模板 B 使用{% include "footer.html" with year="2013" only %}语句，那么footer.html模板只能访问year变量，而不考虑模板 B 中可用的变量。类似地，{% include "footer.html" only %}语句将footer.html模板限制为没有变量，而不考虑使用该语句的模板中可用的变量。

内置上下文处理器

默认情况下，Django 模板可以访问各种变量。这消除了在每个 Django 视图方法中不断声明广泛使用的变量或作为 url 额外选项的需要。这些变量通过模板上下文处理器变得可用。

Django 模板上下文处理器在项目的settings.py文件中明确定义，在OPTIONS键内的TEMPLATES变量中。默认情况下，如清单 3-1 所示，Django 项目通过内置于 Django 的四个上下文处理器来启用。接下来，我将描述每个上下文处理器提供的数据变量。

Django 调试上下文处理器(django . template . context _ processors . debug)

Django 调试上下文处理器公开了有助于调试的变量。这个上下文处理器使得以下变量在所有 Django 模板上都可用:

debug。-基于settings.py文件中的DEBUG变量，包含真或假。
sql_queries。-包含由支持方法视图运行的数据库连接详细信息(例如，SQL 语句)。

Note

只有在 settings.py 中的 INTERNAL_IPS 变量中定义了请求 IP 地址时，Django 调试上下文处理器才会显示变量值。即使变量是在模板中声明的(例如{{debug}}或{{sql_queries}})，这种限制也只允许某些用户查看模板中的调试消息，而其他用户不会查看任何内容。

例如，要查看本地工作站上的 debug 和 sql_queries 值，请将 INTERNAL_IPS = ['127.0.0.1']添加到 settings.py 文件中。这告诉 Django 为来自 IP 地址 127.0.0.1 的请求显示这些变量值。

Django 请求上下文处理器(django . template . context _ processors . request)

Django 请求上下文处理器公开与请求(即 HTTP 请求)相关的变量。这个上下文处理器通过一个名为request的大型字典提供数据，该字典包括以下一些键值:

request.GET。-包含请求的 HTTP GET 参数。
request.POST。-包含请求的 HTTP POST 参数。
request.COOKIES。-包含请求的 HTTP COOKIES。
request.CONTENT_TYPE。-包含请求的 HTTP 内容类型标头。
request.META。-包含请求的 HTTP 元数据。
request.REMOTE_ADDR。-包含请求的 HTTP 远程地址。

Django 授权上下文处理器(django . contrib . auth . context _ processors . auth)

Django 身份验证上下文处理器公开了与身份验证逻辑相关的变量。这个上下文处理器使得 Django 模板中的以下变量可以访问:

user。-包含用户数据(例如，id、姓名、电子邮件、匿名用户)。
perms。-包含用户应用权限(例如，用户在django.contrib.auth.context_processors.PermWrapper对象中可以访问的真、假或显式应用权限)。

Django 消息上下文处理器(django . contrib . messages . context _ processors . messages)

Django 消息上下文处理器公开与 Django 消息框架相关的变量，在第二章中介绍。消息在 Django 视图方法中添加到消息框架中，然后在 Django 模板中公开。这个上下文处理器使得 Django 模板中的以下变量可以访问:

messages。-包含通过 Django 视图方法中的 Django 消息框架添加的消息。
DEFAULT_MESSAGE_LEVELS。-包含消息级别名称到其数值的映射(如{'DEBUG': 10, 'INFO': 20, 'WARNING': 30, 'SUCCESS': 25, 'ERROR': 40})。

其他内置的 Django 上下文处理器:i18n、媒体、静态、tz 和 CSRF 上下文处理器

之前的上下文处理器提供了所有 Django 项目模板所需的一些最常见的数据，这也是它们默认启用的原因。然而，这并不意味着它们是唯一内置的 Django 上下文处理器。事实上，还有五个内置的上下文处理器可以用来访问所有 Django 模板中的某些数据。

Django i18n 上下文处理器(django . template . context _ processors . i18n)

Django i18n 上下文处理器公开了与国际化逻辑相关的变量。这个上下文处理器使得 Django 模板中的以下变量可以访问:

LANGUAGES。-包含 Django 项目的可用语言。
LANGUAGE_CODE。-包含项目语言代码，基于settings.py文件中的LANGUAGE_CODE变量。
LANGUAGE_BIDI。-包含当前项目语言方向。对于从左到右的语言(例如，英语、法语、德语)，它被设置为False;对于从右到左的语言(例如，希伯来语、阿拉伯语)，它被设置为True。

Django 媒体上下文处理器(django . template . context _ processors . media)

Django 媒体上下文处理器公开了一个与媒体资源相关的变量。这个上下文处理器使得 Django 模板中的以下变量是可访问的:

MEDIA_URL。-包含媒体 url，基于settings.py文件中的MEDIA_URL变量。

Django 静态上下文处理器(django . template . context _ processors . static)

Django 静态上下文处理器公开了一个与静态资源相关的变量。这个上下文处理器使得 Django 模板中的以下变量是可访问的:

STATIC_URL。-包含静态 url，基于settings.py文件中的STATIC_URL变量。

Tip

尽管静态上下文处理器是可访问的(也就是说，它没有被弃用)，但它的功能已经过时，应该避免使用。您应该改用 staticfiles 应用。更多细节在第五章设置静态网页资源(图片、CSS、JavaScript)一节中提供。

Django tz 上下文处理器(django . template . context _ processors . tz)

Django tz 上下文处理器公开了一个与项目时区相关的变量。这个上下文处理器使得 Django 模板中的以下变量是可访问的:

TIME_ZONE。-包含项目的时区，基于settings.py文件中的TIME_ZONE变量。

Django CSRF 上下文处理器(django . template . context _ processors . csrf)

跨站点请求伪造(CSRF)上下文处理器将csrf_token变量添加到所有请求中。这个变量被{% csrf_token %}模板标签用来防止跨站点请求伪造。

尽管您可以访问任何 Django 模板中的csrf_token变量值，但是您几乎不需要(如果有的话)直接公开它，因为它被用作检测伪造请求的安全机制。第六章，涵盖了 Django 表单的主题，描述了它是什么以及 CSRF 如何与 Django 一起工作。

由于让csrf_token变量在所有请求上可用的安全重要性，CSRF 上下文处理器总是被启用——不管OPTIONS中的context_processors列表如何——并且不能被禁用。

自定义上下文处理器

当您在 view methods 或 url extra 选项中设置数据时，您这样做是为了访问各个 Django 模板上的数据。定制的 Django 上下文处理器允许您在所有 Django 模板上设置访问数据。

Django 自定义上下文处理器的结构就像一个常规的 Python 方法，带有一个返回字典的HttpRequest对象参数。上下文处理器的返回字典关键字表示模板引用和可在模板中访问的字典值数据对象(例如，字符串、列表、字典)。清单 3-13 展示了一个定制的 Django 上下文处理器方法。

def onsale(request):
    # Create fixed data structures to pass to template
    # data could equally come from database queries
    # web services or social APIs
    sale_items = {'Monday':'Mocha 2x1','Tuesday':'Latte 2x1'}
    return {'SALE_ITEMS': sale_items}
Listing 3-13.Custom Django context processor method

正如您在清单 3-13 中看到的，onsale方法有一个request参数——代表一个HttpRequest对象——并返回一个字典。本例中的字典有一个名为SALE_ITEMS的键和一个硬编码字典值。

然而，正如您可以在 Django 视图方法或 url 选项中设置任何类型的数据以传递给模板一样，自定义 Django 上下文处理器方法也可以从请求参数(例如，cookie、远程 IP 地址)中访问数据，甚至查询数据库并使这些数据对所有模板可用。

自定义上下文处理器方法可以放在任何项目文件或目录中。位置和命名约定并不重要，因为 Django 通过项目的settings.py文件中的TEMPLATES变量的OPTIONS中的context_processors变量来检测上下文处理器。我将把清单 3-13 中的上下文处理器方法放在stores app 子目录中一个名为processors.py的文件中。

一旦保存了自定义上下文处理器方法，就必须配置 Django 来定位它。清单 3-14 显示了context_processors变量的更新，包括了来自清单 3-13 的自定义上下文处理器方法。

'OPTIONS': {
    'context_processors': [
        'coffeehouse.stores.processors.onsale',
        'django.template.context_processors.debug',
        'django.template.context_processors.request',
        'django.contrib.auth.context_processors.auth',
        'django.contrib.messages.context_processors.messages',
    ],
}
Listing 3-14.Django template context processor definitions in context_processors in OPTIONS of TEMPLATES

在清单 3-14 中，您可以看到coffeehouse.stores.processors.onsale声明，其中coffeehouse.stores表示 package.app 名称，processors是包含自定义上下文处理器的文件(即，stores 应用中的processors.py)，而onsale是包含自定义上下文处理器逻辑的实际方法。

一旦在项目的settings.py文件中声明了上下文处理器，带有清单 3-13 中的SALE_ITEMS键的定制字典就可以用于所有的 Django 模板。

内置 Django 过滤器

Django 过滤器设计用于格式化模板变量。应用 Django 过滤器的语法是竖线字符|，在 Unix 环境中也称为“管道”(例如{{variable|filter}})。值得一提的是，可以在同一个变量上使用多个过滤器(例如，{{variable|filter|filter}})。

我将把每个内置的 Django 过滤器分成不同的功能部分，这样更容易识别它们。我将使用的功能类是日期、字符串、列表、数字、字典、空格和特殊字符、开发、测试和 URL。

Tip

您可以使用{% filter %}标签将 Django 过滤器应用于整个部分。如果在同一个部分中有一组变量，并且希望对所有变量应用相同的过滤器，那么使用{% filter %}标记比在每个变量上单独声明过滤器更容易。本章关于 Django 内置标签的下一节提供了关于{% filter %}标签的更多细节

日期

date。-date过滤器格式化 Python datetime对象，并且仅当变量是这种类型的 Python 对象时才起作用。date过滤器使用一个字符串来指定格式。例如，如果一个变量包含一个日期为 01/01/2018 的datetime对象，过滤器语句{{variable|date:"F jS o"}}输出 2018 年 1 月 1 日。日期过滤器的字符串语法基于表 3-3 中描述的字符。

Tip

如果没有为日期筛选器提供字符串参数(例如{{variable|date}})，则默认为“N j，Y”字符串，该字符串来自 DATE_FORMAT 的默认值。

Note

日期筛选器还可以接受预定义的日期变量{ { variable | DATE:" DATE _ FORMAT " } } 、{ { variable | DATE:" DATETIME _ FORMAT " }、{ { variable | DATE:" SHORT _ DATE _ FORMAT " % }或{ { variable | DATE:" SHORT _ DATETIME _ FORMAT " }。

预定义的日期变量本身也由基于表 3-3 中语法的日期字符串组成。例如，DATE_FORMAT 默认为“N j，Y”(例如，2018 年 1 月 1 日)，DATETIME_FORMAT 默认为“N j，Y，P”(例如，2018 年 1 月 1 日上午 12 点)，SHORT_DATE_FORMAT 默认为“m/d/Y”(例如，2018 年 1 月 1 日上午 12 点)，SHORT_DATETIME_FORMAT 默认为“m/d/Y P”(例如，2018 年 1 月 1 日上午 12 点)。在项目的 settings.py 文件中，可以用不同的日期字符串重写每个日期变量。

表 3-3。

Django date and time format characters

| 基于标准的字符 | 描述 | | --- | --- | | c | 输出 ISO 8601 格式(例如，2015-01-02T10:30:00.000123+02:00 或 2015-01-02t 10:30:00.000123，如果日期时间没有时区[即，简单日期时间]) | | r | 输出 RFC 2822 格式的日期(例如，“星期四，2000 年 12 月 21 日 16:01:07 +0200”) | | U | 输出自 Unix 纪元日期-1970 年 1 月 1 日 00:00:00 UTC 以来的秒数 | | I(大写的 I) | 输出夏令时是否有效(例如，“1”或“0”) | | 基于小时的字符 | 描述 | | a | 输出'上午'或'下午' | | A | 输出' AM '或' PM ' | | f | 输出时间，12 小时制的小时和分钟，如果分钟为零，则不输出分钟(例如，“1”，“1:30”) | | g | 输出不带前导零的小时、12 小时格式(例如“1”到“12”) | | G | 输出不带前导零的 24 小时制小时格式(例如，0 到 23) | | h | 输出小时，12 小时格式(例如，“01”到“12”) | | H | 输出小时，24 小时格式(例如，“00”到“23”) | | 我 | 输出分钟数(例如“00”到“59”) | | P | 输出时间，12 小时制的小时、分钟和' a.m.'/'p.m . '，如果分钟为零，则不输出分钟，如果合适，则输出特殊情况字符串' midnight '和' noon '(例如，' a . m . 1 '，' 1:30 p.m . '，' midnight '，' noon '，' 12:30 p.m . ') | | s | 输出秒，带前导零的两位数(例如，“00”到“59”) | | u | 输出微秒数(例如，000000 到 999999) | | 时区字符 | 描述 | | e | 输出时区名称。可以是任何格式，或者可能返回空字符串，具体取决于日期时间的定义(例如，“”、“GMT”、“-500”、“美国/东部”) | | O | 以小时为单位输出时区与格林威治时间的差异(例如，“+0200”) | | T | 输出日期时间时区(例如' EST '，' MDT ') | | Z | 以秒为单位输出时区偏移量。UTC 以西的时区偏移量始终为负，而 UTC 以东的时区偏移量始终为正(例如-43200 到 43200) | | 日和周字符 | 描述 | | D | 输出星期几，文本，3 个字母(例如，“Thu”，“Fri”) | | L(小写 L) | 输出星期几，文本，长型(例如，“星期四”，“星期五”) | | S | 输出一个月中某一天的英文序号后缀，2 个字符(例如，“st”、“nd”、“rd”或“th”) | | w | 输出星期几，不带前导零的数字(例如，“0”代表星期日，“6”代表星期六) | | z | 输出一年中的某一天(例如，0 到 365) | | W | 输出一年中的周数，基于 ISO-8601 从星期一开始(例如，1，53) | | o | 输出周编号年份，对应于 ISO-8601 周编号(W)(例如，“1999”) | | 月份字符 | 描述 | | b | 输出文本月份，3 个字母，小写(例如'一月'，'二月') | | d | 输出一个月中的某一天，2 位数，带前导零(例如，“01”到“31”) | | j | 输出不带前导零的一个月中的某一天(例如，“1”到“31”) | | E | 输出月份，区域特定的替代表示，通常用于长日期表示(例如，波兰语区域的“listopada”，与“Listopad”相对) | | F | 输出月份，文本，长型(例如，“一月”，“二月”) | | m | 输出月份，带前导零的两位数(例如，“01”到“12”) | | M | 输出月份，文本，3 个字母(例如'一月'，'二月') | | n | 输出不带前导零的月份(例如“1”到“12”) | | 普通 | 以美联社风格输出月份缩写(例如，“一月”、“二月”、“三月”、“五月”) | | t | 输出给定月份的天数(例如，28 到 31) | | 年份字符 | 描述 | | L | 输出布尔值来判断是否是闰年(例如，真或假) | | y | 输出年份，两位数(例如“99”) | | Y | 输出年份，4 位数字(例如，“1999”) |

To literally output a date character in a string statement you can use the backslash character (e.g., {{variable|date:"jS \o\f F o"}} outputs 1st of January 2018, note the escaped \o\f)

time。-time过滤器格式化 Python datetime对象的时间部分。time过滤器类似于date过滤器，它使用一个字符串来指定时间格式。例如，如果一个变量包含一个时间为中午的datetime对象，那么过滤器语句{{variable|time:"g:i"}}输出 12:00。时间过滤器使用与时间相关的表 3-3 中所示的相同格式字符。

Tip

如果没有为日期筛选器提供字符串参数(例如{{variable|time}} ),则默认为“P”字符串，该字符串来自 TIME_FORMAT 的默认值。

Note

时间过滤器还可以接受预定义的时间变量{{variable|date:"TIME FORMAT"}。预定义时间也由基于表 3-3 中语法的时间字符串组成。例如，TIME_FORMAT 默认为“P”(例如，凌晨 4 点)，这可以通过在项目的 settings.py 文件中定义 TIME_FORMAT 来覆盖。

timesince。-timesince过滤器输出一个datetime物体和当前时间之间经过的时间。timesince过滤器输出以秒、分、小时、天或周表示。例如，如果变量包含datetime对象 01/01/2018 12:00pm，当前时间为 01/01/2018 3:30pm，则语句{{variable|timesince}}输出 3 小时 30 分钟。timesince过滤器还可以通过附加第二个 datetime 对象参数(例如，{{variable|timesince:othervariable}})来计算两个datetime对象变量之间经过的时间，而不是默认的当前时间。
timeuntil。-timeuntil过滤器输出从当前时间到datetime对象所需的时间。timeuntil过滤器输出以秒、分、小时、天或周表示。例如，如果变量包含datetime对象 01/01/2018 10:00pm，并且当前时间是 01/01/2018 9:00pm，则语句{{variable|timeuntil}}输出 1 小时。timeuntil过滤器还可以通过附加第二个datetime对象参数(例如{{variable|timeuntil:othervariable}})来计算两个datetime对象变量之间需要经过的时间，而不是默认的当前时间。

字符串、列表和数字

add。-add过滤器增加数值。add过滤器可以添加两个变量或一个硬编码值和一个变量。例如，如果一个变量包含 5，那么过滤语句{{variable|add:"3"}}输出 8。如果值可以被强制转换成整数——就像上一个例子一样——add过滤器执行一次求和，如果不能，加法过滤器进行连接。对于包含“Hello”的字符串变量，过滤器语句{{variable|add:" World"}}输出 Hello World。对于包含['a '，' e '，' i']的列表变量和包含['o '，' u']的列表变量，过滤器语句{{variable|add:othervariable}}输出['a '，' e '，' I '，' o '，' u']。
default。-default过滤器用于在变量为假、不存在或为空时指定默认值。例如，如果一个变量在模板中不存在，包含 False 或者是一个空字符串(')，过滤语句{{variable|default:"no value"}}输出no value。
default_if_none。-默认过滤器用于指定变量为None时的默认值。例如，如果一个变量包含None，过滤语句{{variable|default_if_none:"No value"}}输出No value。注意如果一个变量包含一个空字符串('')，这不被认为是None，default_if_none过滤器不输出它的参数值。
length。-length过滤器用于获取值的长度。例如，如果一个变量包含字符串latte，过滤语句{{variable|length}}输出 5。对于包含['a','e','i']的列表变量，过滤语句{{variable|length}}输出 3。
length_is。-length_is过滤器用于评估值的长度是否是给定参数的大小。例如，如果一个变量包含latte，那么标签和过滤器语句{% if variable|length_is:"7" %}的计算结果为假。对于包含['a','e','i']的列表变量，标签和过滤器语句{% if variable|length_is:"3" %}评估为真。
make_list。-make_list过滤器从一个字符串或数字创建一个列表。例如，对于过滤器和标签语句{% with mycharlist="mocha"|make_list %}，mycharlist 变量被赋予列表['m '，' o '，' c '，' h '，' a']。对于包含 724 个过滤器和标签语句{% with myintlist=variable|make_list %}的整数变量，myintlist 被分配列表['7 '，' 2 '，' 4']。
yesno。-yesno过滤器将来自True、False和None的变量值映射到字符串 yes、no、maybe。例如，如果一个变量评估为True，过滤器语句{{variable|yesno}}输出 yes，如果该变量评估为False，相同的语句输出 no，如果该变量评估为None，相同的语句输出 maybe。yesno过滤器也接受自定义消息作为参数。例如，如果一个变量的值为True，过滤语句{{variable|yesno:"yea,nay,novote"}}输出 yea，如果该变量的值为False，相同的语句输出 nay，如果该变量的值为None，相同的语句输出 novote。

民数记

divisibleby。-divisibleby过滤器返回一个布尔值，如果一个变量可以被一个给定值整除。例如，如果一个变量包含 20，过滤语句{{variable|divisibleby:"5"}}返回True。
filesizeformat。-filesizeformat过滤器将多个字节转换成友好的文件大小字符串。例如，如果一个变量包含 250，过滤语句{{variable|filesizeformat}}输出 250 字节，如果它包含 2048，输出是 2 KB，如果它包含 2000000000，输出是 1.9 GB。
floatformat。-floatformat过滤器对浮点数变量进行舍入。floatformat过滤器可以接受正整数或负整数参数，将变量四舍五入到特定的小数位数。如果没有使用参数，floatformat过滤器会舍入到一个小数位，就像参数 where -1 一样。例如，如果变量包含 9.33253，过滤语句{{variable|floatformat}}输出 9.3，对于同一变量{{variable|floatformat:3}}输出 9.333，对于{{variable|floatformat:-3}}输出 9.333；如果变量包含 9.00000，过滤语句{{variable|floatformat}}输出 9，{{variable|floatformat:3}}输出 9.000，{{variable|floatformat:-3}}输出 9；如果变量包含 9.37000，过滤语句{{variable|floatformat}}输出 9.4，{{variable|floatformat:3}}输出 9.370，{{variable|floatformat:-3}}输出 9.370。
get_digit。-get_digit过滤器输出一个数字变量的数字，其中 1 是最后一个数字，2 是倒数第二个数字，依此类推。例如，如果变量包含 10257，过滤语句{{variable|get_digit:"1"}}输出 7，过滤语句{{variable|get_digit:"3"}}输出 2。如果变量或自变量不是整数，或者自变量小于 1，则get_digit过滤器输出原始变量值。
phone2numeric。-phone2numeric过滤器将电话号码中的助记字母转换成数字。例如，如果变量包含 1-800-DJANGO，过滤器语句{{variable|phone2numeric}}输出 1-800-352646。phone2numeric过滤器值不一定需要处理有效的电话号码，过滤器只是将字母转换成它们对应的电话键盘号码。

用线串

capfirst。-capfirst过滤器将字符串变量的第一个字符大写。例如，如果变量包含hello world，过滤语句{{variable|capfirst}}输出Hello world。

cut。-cut过滤器从字符串变量中删除给定参数的所有值。例如，如果变量包含mocha latte，过滤语句{{variable|filter:"mocha"}}输出latte。对于同一个变量，过滤语句是{{variable|filter:" "}}输出mochalatte。

linenumbers。-linenumbers过滤器将行号添加到由新行分隔的每个字符串值中。清单 3-15 展示了一个linenumbers过滤器的例子。

# Variable definition
Downtown
Uptown
Midtown

# Template definition with linenumbers filter
{{variable|linenumbers}}

# Output
1.Downtown
2.Uptown
3.Midtown

Listing 3-15.Django linenumbers filter

lower。-lower过滤器将字符串变量的所有值转换成小写。例如，如果一个变量包含Hello World，过滤语句{{variable|lower}}输出hello world。
stringformat。-stringformat过滤器使用 Python 字符串格式语法格式化一个值。 ⁴ 例如，如果一个变量包含7，则过滤语句{{variable|stringformat:"03d"}}输出007。注意stringformat过滤器不需要 Python 字符串格式语法中使用的前导%。
pluralize。-pluralize过滤器根据参数值返回复数后缀。例如，如果变量drink_count包含 1，过滤语句"You have {{drink_count}} drink{{pluralize|drink_count}}"输出"You have 1 drink"，如果变量包含 2，相同的过滤语句输出"You have 2 drinks"。默认情况下，复数过滤器使用字母 s，这是最常见的复数后缀。但是，您可以使用附加参数指定不同的单数和复数后缀。例如，如果store_count为 1，则过滤语句"We have {{store_count}} business{{store_count|pluralize:"es"}}"输出"We have 1 business"，如果store_count为 5，则输出"We have 5 businesses"。另一个例子是过滤语句"We have {{resp_number}} responsibilit{{resp_number|pluralize:"y","ies"}}"，如果resp_number为 1，则输出"We have 1 responsibility"，如果resp_number为 3，则输出"We have 3 responsibilities"。
slugify。-slugify过滤器将字符串转换成 ASCII 类型的字符串。这意味着字符串被转换为小写，删除非单词字符(字母数字和下划线)，去除前导和尾随空格，以及将空格转换为连字符。例如，如果一个变量包含Welcome to the #1 Coffeehouse!，过滤语句{{variable|slugify}}输出welcome-to-the-1-coffeehouse。slugify过滤器通常用于规范 URL 和文件路径的字符串。
title。-title过滤器将字符串变量的所有第一个字符值转换为大写。例如，如果一个变量包含hello world，过滤语句{{variable|title}}输出Hello World。
truncatechars。-truncatechars过滤器将字符串截断成给定数量的字符，并附加一个省略号序列。例如，如果变量包含Coffeehouse started as a small store，过滤语句{{variable|truncatechars:20}}输出Coffeehouse started...。
truncatechars_html。-truncatechars_html过滤器类似于truncatechars过滤器，但是能够识别 HTML 标签。这个过滤器是为 HTML 内容设计的，所以内容不会留下打开的 HTML 标签。例如，如果变量包含<b>Coffeehouse started as a small store</b>，过滤语句{{variable|truncachars_html:20}}输出<b>Coffeehouse start...</b>。
truncatewords。-truncatewords过滤器将字符串截断成给定数量的单词，并附加一个省略号序列。例如，如果一个变量包含Coffeehouse started as a small store，过滤语句{{variable|truncatwords:3}}输出Coffeehouse started as...。
truncatewords_html。-truncatewords_html过滤器类似于truncatewords过滤器，但是能够识别 HTML 标签。这个过滤器是为 HTML 内容设计的，所以内容不会留下打开的 HTML 标签。例如，如果变量包含<b>Coffeehouse started as a small store</b>，过滤语句{{variable|truncatwords_html:3}}输出<b>Coffeehouse started as...</b>。
upper。-upper过滤器将字符串变量的所有值转换为大写。例如，如果一个变量包含Hello World，过滤语句{{variable|lower}}输出HELLO WORLD。
wordcount。-wordcount过滤器对字符串中的单词进行计数。例如，如果变量包含Coffeehouse started as a small store，过滤语句{{variable|wordcount}}输出 6。

列表和词典

dictsort。-dictsort过滤器对字典列表进行排序，并返回一个按给定的关键参数排序的新列表。例如，如果一个变量包含[{'name':'Downtown','city':'San Diego'}, {'name':'Uptown','city':'San Diego'},{'name':'Midtown','city':'San Diego'}]过滤器和标签语句{% with newdict=variable|dictsort:"name" %}，那么newdict变量被分配到列表[{'name':'Downtown','city':'San Diego'},{'name':'Midtown','city':'San Diego'},{'name':'Uptown','city':'San Diego'}]。dictsort过滤器还可以通过指定索引号(例如，{ % with otherlist=listoftuples|dictsort:0 %})对元组列表或列表进行操作，以通过列表中每个元组的第一个元素进行排序。
dictsortreversed。-dictsortreversed过滤器对字典列表进行排序，并返回一个按给定关键参数反向排序的新列表。dictsortreversed过滤器的工作方式类似于dictsort，只是它以相反的顺序返回列表。
join。-join过滤器用一个字符串连接一个列表。连接过滤器就像 Python 的str.join(list)一样工作。例如，对于包含['a '，' e '，' I '，' o '，' u']的列表变量，过滤语句{{variable|join:"--"}}输出 a - e - i - o - u。
first。-first过滤器返回列表中的第一项。例如，对于包含['a '，' e '，' I '，' o '，' u']的列表变量，过滤语句{{variable|first}}输出一个
last。-last过滤器返回列表中的最后一项。例如，对于包含['a '，' e '，' I '，' o '，' u']的列表变量，过滤语句{{variable|last}}输出 u
random。-random过滤器返回一个列表中的随机项目。例如，对于包含['a '，' e '，' I '，' o '，' u']的列表变量，过滤语句{{variable|random}}可以输出 a，e，I，o 或 u
slice。-slice过滤器返回列表的片段。例如，对于包含['a '，' e '，' I '，' o '，' u']的列表变量，过滤语句{{variable|slice:":3"}}输出['a '，' e '，' i']。
unordered_list。-unordered_list从一个列表变量中输出一个 HTML 无序列表。清单 3-16 展示了一个无序列表过滤器的例子。

# Variable definition
["Stores",["San Diego",["Downtown","Uptown","Midtown"]]]

# Template definition with linenumbers filter
{{variable|unordered_list}}

# Output
<li>Stores
   <ul>
       <li>San Diego
          <ul>
   <li>Downtown</li>
   <li>Uptown</li>
   <li>Midtown</li>
  </ul>
       </li>
   </ul>
</li>

Listing 3-16.Django unordered_list filter

Caution

unordered_list 过滤器的第一级不包括开始或结束 HTML

间距和特殊字符

addslashes。-addslashes过滤器向所有引号添加斜线(即，它对引号进行转义)。当 Django 模板用于将数据导出到其他需要转义引号的系统(例如 CSV 文件)时,addslashes过滤器非常有用。例如，如果变量包含Today's news，过滤语句{{variable|addslashes}}输出Today\'s新闻。
center。-center过滤器中心对齐一个值并用额外的空白字符填充它，直到它到达给定的字符参数。例如，如果一个变量包含mocha，过滤语句{{variable|center:"15"}}输出。
"mocha"。(即，摩卡左边 5 个空格，摩卡 5 个空格，摩卡右边 5 个空格。
ljust。-ljust过滤器左对齐一个值并用额外的空白字符填充它，直到它到达给定的字符参数。例如，如果一个变量包含mocha，过滤语句{{variable|ljust:"15"}}输出。
"mocha"。(即 5 个空格用于摩卡，10 个空格填充)。
rjust。-rjust过滤器右对齐一个值并用额外的空白字符填充它，直到它到达给定的字符参数。例如，如果一个变量包含latte，过滤语句{{variable|rjust:"10"}}输出。
"latte"."(即 5 个空格填充，5 个空格给拿铁)。
escape。-escape过滤器从一个值中转义 HTML 字符。具体用escape滤镜:<转换为<，>转换为>，'(单引号)转换为'，"(双引号)转换为"，&转换为&amp。

Tip

如果在连续的变量上使用转义过滤器，用{% autoescape %}标记包装变量会更容易达到相同的结果。

escapejs。-escapejs过滤器将字符转义成通常用于 JavaScript 字符串的 Unicode 字符串。虽然escapejs过滤器不能保证字符串 HTML 的安全，但是它可以防止在使用模板生成 JavaScript/JSON 时出现语法错误。例如，如果一个变量包含mocha\r\n \'price:2.25，过滤语句{{variable|escapejs}}输出\u0022mocha\u000D\u000A \u0027price:2.25\u0022。
force_escape。-force_escape过滤器从一个值中转义 HTML 字符，就像escape过滤器一样。不同的是force_escape被立即应用并返回一个新的转义字符串。当您需要多次转义或想要对转义结果应用其他过滤器时，这很有用。通常，你会使用escape滤镜。
linebreaks。-linebreaks过滤器用 HTML 标签替换纯文本换行符，单个换行符变成 HTML 换行符(<br/>)，新的一行后面跟一个空行变成段落换行符(</p>)。例如，如果变量包含385 Main\nSan Diego, CA，过滤语句{{variable|linebreaks}}输出<p>385 Main<br/>San Diego, CA</p>。
linebreaksbr。-linebreaksbr过滤器将所有文本变量换行符转换成 HTML 换行符(<br/>)。例如，如果变量包含385 Main\nSan Diego, CA，过滤语句{{variable|linebreaksbr}}输出385 Main<br/>San Diego, CA。
striptags。-striptags过滤器从一个值中删除所有 HTML 标签。例如，如果一个变量包含<b>Coffee</b>house, the <i>best</i> <span>drinks</span>，过滤语句{{variable|striptags}}输出Coffeehouse, the best drinks。

Caution

striptags 过滤器使用非常基本的逻辑来剥离 HTML 标签。这意味着一段复杂的 HTML 有可能没有完全去掉标签。这就是为什么通过 striptags 过滤器传递的变量中的内容会被自动转义，并且永远不应该被标记为安全的。

safe。-安全过滤器将字符串标记为不需要 HTML 转义。
safeseq。-safeseq将safe过滤器应用于列表的每个元素。它和其他操作列表的过滤器一起使用很有用，比如join过滤器(例如{{stores|safeseq|join:", "}}))。您不会直接在列表变量上使用safe过滤器，因为它会首先将变量转换成字符串，而不是处理列表的单个元素。
wordwrap。-wordwrap过滤器在给定的字符行长度参数处换行。清单 3-17 展示了一个wordwrap过滤器的例子。

# Variable definition

Coffeehouse started as a small store

# Template definition with wordwrap filter for every 12 characters
{{variable|wordwrap:12}}

# Output
Coffeehouse
started as a
small store

Listing 3-17.Django wordwrap filter

开发和测试

pprint。-pprint过滤器是 Python 的pprint.pprint()的包装器。pprint过滤器在开发和测试期间很有用，因为它输出对象的格式化表示。

资源定位符

iriencode。-iriencode过滤器将国际化资源标识符(IRI)转换成适合包含在 URL 中的字符串。如果您试图在 URL 中使用包含非 ASCII 字符的字符串，这是必要的。例如，如果一个变量包含?type=cold&size=large，过滤语句{{variable|iriencode}}输出?type=cold&size=large。
urlencode。-urlencode过滤器对 URL 中使用的值进行转义。例如，如果一个变量包含http://localhost/drinks?type=cold&size=large，过滤语句{{variable|urlencode}}输出http%3A//localhost/drinks%3Ftype%3Dcold%26size%3Dlarge。urlenconde过滤器假设/角色是安全的。urlencode过滤器可以接受带有不应该转义字符的可选参数。当所有字符都应该转义时，可以提供空字符串(例如，{{variable|urlencode:""}}输出http%3A%2F%2Flocalhost%2Fdrinks%3Ftype%3Dcold%26size%3Dlarge)。
urlize。-urlize过滤器将文本 URL 或电子邮件地址转换成可点击的 HTML 链接。这个urlize过滤器作用于以 http://、https://或 www 为前缀的链接..urlize 过滤器生成的链接添加了一个rel="nofollow"属性。例如，如果一个变量包含Visit http://localhost/drinks，过滤语句{{variable|urlize}}输出Visit <a href="http://localhost/drinks" rel="nofollow">http://localhost/drinks</a>；如果变量包含Contact support@coffeehouse.com，过滤语句{{variable|urlize}}输出Contact <a href="mailto:support@coffeehouse.com">support@coffeehouse.com</a>。
urlizetrunc。—urlizetrunc过滤器将文本 url 和电子邮件转换为可点击的 HTML 链接——就像urlize过滤器一样——除了它将 URL 截断为给定数量的包含省略号序列的字符。例如，如果变量包含Visit http://localhost/drinks，过滤语句{{variable|urlizetrunc:20}}输出Visit <a href="http://localhost/drinks" rel="nofollow">http://localhost/...</a>。

Caution

urlize 和 urlizetrunc 筛选器应该只应用于纯文本变量。如果应用于带有 HTML 链接的变量，过滤逻辑将不会像预期的那样工作。

内置 Django 标签

Django 提供了几个内置标签，可以直接访问 Django 模板上的复杂操作。与对单个变量进行操作的 Django 过滤器不同，标记被设计成在没有变量的情况下产生结果，或者跨模板部分进行操作。

我将把这些内置标签分为不同的功能部分，这样更容易识别它们。我将使用的函数类是日期、表单、比较操作、循环、Python 和过滤器操作、空格和特殊字符、模板结构、开发和测试以及 URL。

日期

{% now %}。-{% now %}标签提供对当前系统时间的访问。{% now %}标签接受第二个参数来格式化系统日期。例如，如果语句{% now "F jS o" %}的系统日期为 2015 年 1 月 1 日，则标签输出为 2015 年 1 月 1 日。{% now %}标签的字符串语法基于表 3-3 中描述的 Django 日期字符。也可以使用as关键字通过变量重用该值(例如{% now "Y" as current_year %}和模板声明Copyright {{current_year}})。

Tip

{% now %}标记可以接受 Django 日期变量:{% now "DATE_FORMAT" %} 、{% now "DATETIME_FORMAT" %} 、{% now "SHORT_DATE_FORMAT" %}或{% now "SHORT_DATETIME_FORMAT"}。

日期变量本身也由日期字符串组成。例如，DATE_FORMAT 默认为“N j，Y”(例如，2015 年 1 月 1 日)，DATETIME_FORMAT 默认为“N j，Y，P”(例如，2015 年 1 月 1 日，上午 12 点)，SHORT_DATE_FORMAT 默认为“m/d/Y”(例如，2015 年 1 月 1 日)，SHORT_DATETIME_FORMAT 默认为“m/d/Y P”(例如，2015 年 1 月 1 日，上午 12 点)。在项目的 settings.py 文件中，可以用不同的日期字符串重写每个日期变量。

形式

{% csrf_token %}。-{% csrf_token %}标签提供了一个字符串来防止跨站脚本。{% csrf_token %}标签仅用于 HTML <form>标签中。{% csrf_token %}标签的数据输出允许 Django 防止表单数据提交中的伪造请求(例如 HTTP POST 请求)。Django 表单一章中提供了关于{% csrf_token %}标签的更多细节。

比较操作

{% if %}同{% elif %} {% else %}。-{% if %}标签通常与{% elif %}和{% else %}标签结合使用，以评估多个条件。如果变量存在且不为空，或者如果变量持有一个True布尔值，则带有自变量变量的{% if %}标签评估为真。清单 3-18 展示了一系列{% if %}标签示例。

{% if drinks %}             {% if drinks %}              {% if drinks %}
  We have drinks!                We have drinks              We have drinks
{% endif %}                 {% else %}                   {% elif drinks_on_sale %}
                                No drinks,sorry              We have drinks on sale!
                            {% endif %}                  {% else %}
                                                           No drinks, sorry
                                                         {% endif %}
Listing 3-18.Django {% if %} tag with {% elif %} and {% else %}

Note

变量必须既存在又不为空才能计算为 true。仅存在且为空的变量的计算结果为 false。

{% if %}带and、or和not操作符。-{% if %}标签还支持and、or和not操作符来创建更复杂的条件。这些运算符允许您比较是否有多个变量不为空(如{% if drinks and drinks_on_sale %})，是否有一个或另一个变量不为空(如{% if drinks or drinks_on_sale %})，或者是否有一个变量为空(如{% if not drinks %})。
{% if %}带==、!=、<、>、<=和>=操作符。-{% if %}标签还支持等于、不等于、大于和小于运算符，以创建将变量与固定字符串或数字进行比较的条件。这些运算符允许您比较变量是否等于字符串或数字(如{% if drink == "mocha" %})、变量是否不等于变量或数字(如{% if store.id != 2 %})或变量是否大于或小于数字(如{% if store.id > 5 %})。

{% firstof %}。-{% firstof %}标记是一个简写标记，用于输出一组非空变量中的第一个变量。通过嵌套{% if %}标签可以实现{% firstof %}标签的相同功能。清单 3-19 展示了{ % firstof %}标签的一个示例，以及一组等价的嵌套{% if %}标签。

# Firstof example
{% firstof var1 var2 var3 %}

# Equivalent of firstof example
{% if var1 %}
    {{var1|safe}}
{% elif var2 %}
    {{var2|safe}}
{% elif var3 %}
    {{var3|safe}}
{% endif %}

# Firstof example with a default value in case of no match (i.e, all variables are empty)
{% firstof var1 var2 var3 "All vars are empty" %}

# Assign the firstof result to another variable
{% firstof var1 var2 var3 as resultof %}
# resultof now contains result of firstof statement

Listing 3-19.Django {% firstof %} tag and equivalent {% if %}{% elif %}{% else %} tags

{% if <value> in %}和{% if <value> not in %}。-{% if %}标签还支持in和not in操作符来验证常量或变量的存在。例如，{% if "mocha" in drinks %}测试值"mocha"是否在drinks列表变量中，或者{% if 2 not in stores %}测试值2是否不在stores列表变量中。虽然in和not in操作符通常用于测试列表变量，但是也可以测试字符串中是否存在字符(例如{% if "m" in drink %})。此外，还可以比较一个变量的值是否出现在另一个变量中(如{% if order_drink in drinks %})。
{% if <value> is <value> %}和{% if <value> is not %}。-{% if %}标签还支持is和is not操作符进行对象级比较。例如，{% if target_drink is None %}测试值target_drink是否是一个None对象，或者{% if daily_special is not True %}测试值daily_special是否不是True。
{% if value|<filter> <condition> <value> %}。-{% if %}标签还支持直接对一个值应用过滤器，然后执行评估。例如，{% if target_drink_list|random == user_drink %}Congratulations your drink just got selected!{% endif %}在一个条件中直接使用random过滤器。

Parentheses are Not Allowed in If Tags: Operator Precedence Governs, Use Nested If Tags to Alter Precedence

比较运算符通常被聚合到单个语句中(例如，if...<...or...>...和...==...)并遵循一定的执行优先级。Django 遵循与 Python 相同的操作符优先级。 ⁵ 例如，语句{ % if drink in specials or drink == drink _ of _ the _ day % }的计算结果为((drink in specials)or(drink = = drink _ of _ the _ day))，其中首先运行内部括号运算，因为 in 和= =的优先级高于 or。

在 Python 中，可以通过在比较语句中使用显式括号来改变这种优先级。但是，Django 不支持在{% if %}标记中使用括号，您必须依赖操作符优先级或者使用嵌套的{% if %}语句来声明由显式括号产生的相同逻辑。

环

{% for %}和{% for %}同{% empty %}。-{% for %}标签遍历字典、列表、元组或字符串变量上的项目。{% for %}标签语法是{% for <reference> in <variable> %}，其中reference在每次迭代中被赋予一个来自变量的新值。

根据变量的性质，可以有一个或多个引用(例如，对于列表一个引用{% for item in list %}，对于字典两个引用{% for key,value in dict.items %})。此外，也可以用reversed关键字(例如{ % for item in list reversed %})反转循环顺序。{% for %}标签还支持{% empty %}标签，在循环中没有迭代的情况下(即主变量为空)会处理该标签。清单 3-20 展示了一个{% for %}和一个{% for %}和{% empty %}循环示例。

<ul>                                 <ul>
{% for drink in drinks %}             {% for storeid,store in stores %}
 <li>{{ drink.name }}</li>            <li><a href="/stores{{storeid}}/">{{store.name}}</a></li>
{% empty %}                           {% endfor %}
 <li>No drinks, sorry</li>           </ul>
{% endfor %}
</ul>
Listing 3-20.Django {% for %} tag and {% for %} with {% empty %}

{% for %}标签还生成一系列变量来管理迭代过程，例如迭代计数器、第一次迭代标志和最后一次迭代标志。当您想要在给定的迭代中创建行为(例如，格式化、附加处理)时，这些变量会很有用。表 3-4 说明了{% for %}标签变量。

{% ifchanged %}。-{% ifchanged %}标签是在{% for %}标签中使用的特殊逻辑标签。有时，了解循环引用是否从一个迭代更改到另一个迭代(例如，插入新标题)会很有帮助。{% ifchanged %}标签的参数是循环引用本身(如{% ifchanged drink %}{{drink}} section{% endifchanged %})或引用的一部分(如{% ifchanged store.name %}Available in {{store.name}}{% endifchanged %})。{% ifchanged %}标签也支持使用{% else %}标签(例如{% ifchanged drink %}{{drink.name}}{% else %}Same old {{drink.name}} as before{% endifchanged %})。
{% cycle %}。-{% cycle %}标签被用在{% for %}标签中来迭代一组给定的字符串或变量。标签的主要用途之一是定义 CSS 类，这样每次迭代都会收到不同的 CSS 类。例如，如果你想给一个列表分配不同的 CSS 类，这样每一行以不同的颜色出现(例如，白色，灰色，白色，灰色)，你可以使用<li class="{% cycle 'white' 'grey' %}">，这样在每次循环迭代中类值在白色和灰色之间交替。{% cycle %}标签可以顺序迭代任意数量的字符串或变量(例如{% cycle var1 var2 'red' %})。

表 3-4。

Django {% for %} tag variables

| 可变的 | 描述 | | --- | --- | | forloop .柜台 | 循环的当前迭代(1 索引) | | forloop.counter0 | 循环的当前迭代(索引为 0) | | forloop.revcounter | 从循环结束开始的迭代次数(1-索引) | | forloop.revcounter0 | 从循环结束开始的迭代次数(索引为 0) | | forloop.first | 如果是第一次通过循环，则为 True | | forloop.last | 如果是最后一次循环，则为真 | | 渐变.括号 | 对于嵌套循环，这是当前循环的父循环 |

默认情况下，{% cycle %}标签根据其封闭循环遍历其值(即，一个接一个)。但是在某些情况下，你可能需要在循环之外使用一个{% cycle %}标签或者明确声明一个{% cycle %标签如何前进。您可以通过用as关键字命名{% cycle %}标签来实现这种行为，如清单 3-21 所示。

<li class="{% cycle 'disc' 'circle' 'square' as bullettype %}">...</li>
<li class="{{bullettype}}">...</li>
<li class="{{bullettype}}">...</li>
<li class="{% cycle bullettype %}">...</li>
<li class="{{bullettype}}">...</li>
<li class="{% cycle bullettype %}">...</li>
# Outputs
<li class="disc">...</li>
<li class="disc">...</li>
<li class="disc">...</li>
<li class="circle">...</li>
<li class="circle">...</li>
<li class="square">...</li>
Listing 3-21.Django {% cycle %} with explicit control of progression

正如您在清单 3-21 中看到的，{% cycle %}标记语句最初产生第一个值，然后您可以继续使用循环引用名来输出相同的值。为了前进到循环中的下一个值，您用循环引用名再次调用{% cycle %}。{% cycle %}标签的一个小副作用是它在声明的地方输出初始值，如果你打算把循环作为占位符或者在嵌套循环中使用，这可能会有问题。为了避免这种副作用，您可以在循环引用名称后使用silent关键字(例如，{ % cycle 'disc' 'circle' 'square' as bullettype silent %})。

{% resetcycle %}。—{% resetcycle %}标签用于将{% cycle %}标签重新初始化到其第一个元素。在返回到第一个值之前，{% cycle %}标签总是在它的整个值集上循环，这在嵌套循环的上下文中是有问题的。例如，如果您想要为嵌套组分配三个颜色代码(如{% cycle 'red' 'orange' 'yellow' %})，第一个组可以由两个元素组成，这两个元素用完了前两个循环值(如“红色”和“橙色”)，这意味着第二个组从第三个颜色代码(如“黄色”)开始。为了让第二个组再次从第一个{% cycle %}元素开始，您可以在嵌套循环迭代完成后使用{% resetcycle %}标签，这样{% cycle %}标签就会返回到它的第一个元素。
{% regroup %}。-{% regroup %}标签用于将字典变量的内容重新排列到不同的组中。{% regroup %}标签避免了在{% for %}标签内创建复杂条件来实现所需显示的需要。{% regroup %}标签预先安排了字典的内容，使得{% for %}标签的逻辑更加简单。清单 3-22 展示了一个使用{% regroup %}标签及其输出的字典。

# Dictionary definition
stores = [
    {'name': 'Downtown', 'street': '385 Main Street', 'city': 'San Diego'},
    {'name': 'Uptown', 'street': '231 Highland Avenue', 'city': 'San Diego'},
    {'name': 'Midtown', 'street': '85 Balboa Street', 'city': 'San Diego'},
    {'name': 'Downtown', 'street': '639 Spring Street', 'city': 'Los Angeles'},
    {'name': 'Midtown', 'street': '1407 Broadway Street', 'city': 'Los Angeles'},
    {'name': 'Downton', 'street': '50 1st Street', 'city': 'San Francisco'},
]

# Template definition with regroup and for tags
{% regroup stores by city as city_list %}

<ul>
{% for city in city_list %}
    <li>{{ city.grouper }}
    <ul>
        {% for item in city.list %}
          <li>{{ item.name }}: {{ item.street }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

# Output
San Diego
    Downtown : 385 Main Street
    Uptown : 231 Highland Avenue
    Midtown : 85 Balboa Street
Los Angeles
    Downtown: 639 Spring Street
    Midtown: 1407 Broadway Street
San Francisco
    Downtown: 50 1st Street

Listing 3-22.Django {% for %} tag and {% regroup %}

Tip

{% regroup %}标记也可以使用筛选器或属性来获得分组结果。例如， 3-22 中的商店列表可以方便地按城市预先排序，从而自动按城市进行分组，但是如果商店列表没有预先排序，您需要先按城市对列表进行排序，以避免分组不完整，您可以直接使用 dictsort 过滤器(例如，{ % regroup stores | dict sort:' city ' by city as city _ list % })。{% regroup %}标记的另一种可能性是使用嵌套属性，如果分组对象有嵌套属性(例如，如果 city 有一个 state 属性{ % regroup stores by city . state as state _ list % })。

Python 和过滤器操作

{% filter %}。-{% filter %}标签用于将 Django 过滤器应用于模板部分。如果你声明了{% filter lower %}，那么lower过滤器将应用于这个标签和{% endfilter %}标签之间的所有变量——注意过滤器lower将所有内容转换成小写。也可以使用相同的管道技术将多个过滤器应用到同一个部分，以将过滤器链接到变量(例如{% filter lower|center:"50" %}...variables to convert to lower case and center...{% endfilter %})。
{% with %}。-{% with %}标签允许您在 Django 模板的上下文中定义变量。当您需要为 Django view 方法没有公开的值创建变量时，或者当一个变量与一个重量级操作相关联时，这很有用。也可以在同一个{% with %}标签中定义多个变量(例如{% with drinkwithtax=drink.cost*1.07 drinkpromo=drink.cost*0.85 %})。在到达{% endwith %}标签之前，{% with %}标签中定义的每个变量都可供模板使用。

Python Logic Only Allowed Behind the Scenes in Custom Django Tags or Filters

Django 模板不允许包含内联 Python 逻辑。事实上，Django 模板允许内联 Python 逻辑的最接近的方式是通过{% with %}标记，这并不复杂。

让自定义 Python 逻辑在 Django 模板中工作的唯一方法是将代码嵌入到自定义 Django 标签或过滤器中。这样，您可以在模板上放置一个定制的 Django 标签或过滤器，Python 逻辑在后台运行。下一节将描述如何创建定制的 Django 过滤器。

间距和特殊字符

{% autoescape %}。-{% autoescape %}标签用于对模板部分的 HTML 字符进行转义。{% autoescape %}接受两个参数on或off中的一个。使用{% autoescape on %}时，该标签和{% endautoescape %}标签之间的所有模板内容都被 HTML 转义，而使用{% autoescape off %}时，该标签和{% endautoescape %}标签之间的所有模板内容都不被转义。

Tip

如果您想要全局启用或禁用自动转义(即，在所有模板上)，更容易的方法是使用项目 settings.py 文件中模板配置的 OPTIONS 变量中的 autoescape 字段在项目级别禁用它，如本章第一节所述。

如果您想要启用或禁用单个变量的自动转义，您可以使用 safe 过滤器禁用单个 Django 模板变量的自动转义，或者使用 escape 过滤器对单个 Django 模板变量进行转义。

{% spaceless %}。-{% spaceless %}标签删除 HTML 标签之间的空白，包括制表符和换行符。因此，{% spaceless %}和{% endspaceless %}中包含的所有 HTML 内容变得更加紧凑。注意{% spaceless %}标签只移除 HTML 标签之间的空间，它不移除文本和 HTML 标签之间的空间(例如<p> <span> my span </span> </p>，只移除<p> <span>和</span> </p>标签之间的空间，填充myspan字符串的<span>标签之间的空间保留)。
{% templatetag %}。-{% templatetag %}标签用于输出保留的 Django 模板字符。因此，如果您想在模板上逐字显示任何字符{%、%}、{{、}}、{、}、{#或#}，您可以这样做。{% templatetag %}与八个参数中的一个结合使用来表示 Django 模板字符。{% templatetag openblock %}输出{%，{% templatetag closeblock %}输出%}，{% templatetag openvariable %}输出{{，{% templatetag closevariable %}输出}}，{% templatetag openbrace %}输出{，{% templatetag closebrace %}输出}，{% templatetag opencomment %}输出{#，{% templatetag closecomment %}输出#}。一种更简单的方法是用{% verabtim %}标签包装保留的 Django 字符。
{% verbatim %}。-{% verbatim %}标签用于隔离正在处理的模板内容。Django 会绕过{% verbatim %}标签和{% endverbatim %}标签中的任何内容。这意味着像{{这样的特殊字符，像{{drink}}这样的变量语句，或者使用特殊 Django 字符的 JavaScript 逻辑将被忽略并逐字呈现。如果需要输出单个特殊字符，使用{% templatetag %}标签。
{% widthratio %}。-{% widthratio %}标签用于计算一个值与最大值的比值。{% widthratio %}标签有助于显示宽度固定但需要根据可用空间大小进行缩放的内容，例如图像和图表。例如，给定语句<img src="logo.gif" style="width:{% widthratio available_width image_width 100 %}%"/>，如果available_width是 75，而image_width是 150，则 0.50 乘以 100 得到 50。该图像的宽度比是根据可用空间和图像大小计算的，在这种情况下，该语句被呈现为:<img src="logo.gif" style="width:50%"/>。
{% lorem %}。-{% lorem %}标签用于显示随机的拉丁文本，这对模板上的填充符很有用。{% lorem %}标签支持多达三个参数{% lorem [count] [method] [random] %}。其中[count]是要生成的段落数或字数的数字或变量，如果未提供，默认[count]为 1。其中[method]是单词的w、HTML 段落的p或纯文本段落块的b，如果没有提供，默认[method]是b。并且其中单词random(如果给定的话)输出随机的拉丁单词，而不是公共模式(例如，Lorem ipsum dolor sit amet...).

模板结构

{% block %}。-{% block %}标签用于定义可以在不同 Django 模板上覆盖的页面部分。请参阅本章上一节如何创建可重用模板，以获取该标签的示例。
{% comment "Optional explanation" %}。-{% comment %}标签用于定义 Django 模板上的注释部分。Django 会绕过放置在{% comment %}和{% endcomment %}标签之间的任何内容，这些内容不会出现在最终呈现的网页中。注意开始的{% comment %}标签中的字符串参数是可选的，但是有助于澄清注释的目的。
{# #}。-{# #}语法可以用于 Django 模板上的单行注释。Django 会绕过单行中位于{#和#}之间的任何内容，这些内容不会出现在最终呈现的网页中。注意，如果注释跨越多行，你应该使用{% comment %}标签。
{% extends %}。-{% extends %}标签用于重用另一个 Django 模板的布局。参见本章上一节关于创建可重用模板的例子。
{% include %}。-{% include %}标签用于将一个 Django 模板嵌入到另一个 Django 模板中。参见本章上一节关于创建可重用模板的例子。
{% load %}。-{% load %}标签用于加载自定义 Django 标签和过滤器。{% load %}标签需要一个或多个参数作为自定义 Django 标签或过滤器的名称。本章的下一节将描述如何创建自定义过滤器以及如何使用{% load %}标签。

Tip

如果您发现自己在许多模板上使用{% load %}标记，您可能会发现用模板中的 builtins 选项注册 Django 标记和过滤器更容易，这样它们就可以在所有模板上访问，就像它们是内置的一样。有关详细信息，请参见本章中关于模板配置的第一节。

开发和测试

{% debug %}。-{% debug %}标签输出包括模板变量和导入模块的调试信息。{% debug %}标签在开发和测试期间很有用，因为它输出 Django 模板使用的“幕后”信息。

资源定位符

{% url %}。-{% url %}标签用于从项目的urls.py文件中的预定义值构建 URL。{% url %}标签很有用，因为它避免了在模板上硬编码 URL 的需要，而是基于名称插入 URL。{% url %}标签接受一个 url 名称作为第一个参数，url 参数作为后续参数。

比如一个 url 指向/drinks/index/，命名为drinks_main，可以用{% url %}引用这个 url(如<a href="{% url drinks_main %}"> Go to drinks home page </a>)；如果一个 url 指向/stores/1/并且被命名为stores_detail，你可以使用{% url %}和一个参数来引用这个 url(例如<a href="{% url stores_detail store.id %}"> Go to {{store.name}} page </a>)。

{% url %}标签还支持as关键字，将结果定义为一个变量。这允许结果被多次使用，或者在声明了{% url %}标签以外的地方使用(例如{% url drink_detail drink.name as drink_on_the_day%}...后来在模板<a href="{{drink_of_the_day}}> Drink of the day </a>。第二章详细描述了命名 Django url 的过程，以便于管理和反向匹配。

自定义过滤器

有时候，Django 内置的过滤器在逻辑或输出方面有所欠缺。在这些情况下，解决方案是编写一个自定义筛选器来实现您需要的结果。

Django 过滤器背后的逻辑完全是用 Python 编写的，因此使用 Python & Django 可以实现的任何功能(例如，执行数据库查询、使用第三方 REST 服务)都可以集成为定制过滤器生成的逻辑或输出的一部分。

结构

最简单的定制 Django 过滤器只需要你创建一个标准的 Python 方法并用@register.filter()修饰它，如清单 3-23 所示。

from django import template
register = template.Library()

@register.filter()
def boldcoffee(value):
    '''Returns input wrapped in HTML  tags'''
    return '<b>%s</b>' % value

Listing 3-23.Django custom filter with no arguments

清单 3-23 首先导入template包，创建一个register引用来修饰boldcoffee方法，并告诉 Django 从中创建一个自定义过滤器。

默认情况下，筛选器接收与修饰方法相同的名称。所以在这种情况下，boldcoffee方法创建了一个名为boldcoffee的过滤器。方法输入value代表过滤器调用者的输入。在这种情况下，该方法只是返回包装在 HTML <b>标记中的输入值，其中 return 语句中使用的语法是标准的 Python 字符串格式操作。

要在 Django 模板中应用这个定制过滤器，可以使用语法{{byline|boldcoffee}}。byline变量作为value参数传递给过滤器方法，所以如果byline变量包含文本Open since 1965!，过滤器输出就是<b>Open since 1965!</b>。

Django 定制过滤器也支持包含参数，如清单 3-24 所示。

@register.filter()
def coffee(value,arg="muted"):
    '''Returns input wrapped in HTML  tags with a CSS class'''
    '''Defaults to CSS class 'muted' from Bootstrap'''
    return '<span class="%s">%s</span>' % (arg,value)
Listing 3-24.Django custom filter with arguments

清单 3-24 中的过滤方法有两个输入参数。代表应用过滤器的变量的参数value和第二个参数arg="muted"，其中"muted"代表默认值。如果您查看 return 语句，您会注意到它使用了arg变量来定义一个class属性，而value变量用于定义一个<span>标签内的内容。

如果使用与第一个定制过滤器相同的语法调用清单 3-24 中的定制过滤器(例如{{byline|coffee}})，输出默认使用"muted"作为arg变量，最终输出为<span class="muted">Open since 1965!</span>。

然而，您也可以调用清单 3-24 中的过滤器，使用一个参数覆盖arg变量。过滤参数附加有:。例如，过滤器语句{ {byline|coffee:"lead muted"}}将"lead muted"指定为arg变量的值，并产生输出<span class="lead muted">Open since 1965!</span>。

参数为自定义过滤器提供了更大的灵活性，因为它们可以用不同于主输入的数据进一步影响最终输出。

Tip

如果筛选器需要两个或更多参数，您可以在筛选器定义中使用空格分隔或 CSV 类型的字符串参数(例如，byline|mymultifilter:"18，success，green，2em ")，然后在 filter 方法中解析该字符串以访问每个参数。

选项:命名、HTML 和进出的内容

尽管前面的两个例子说明了定制过滤器的核心结构，但是它们缺少一系列使定制过滤器更加灵活和强大的选项。表 3-5 展示了一系列自定义过滤器选项，以及它们的语法和功能描述。

表 3-5。

Custom filter options.

| 选项语法 | 价值观念 | 描述 | | --- | --- | --- | | @register.filter(name= ) | 命名过滤器的一个刺 | 指定不同于筛选方法名称的筛选名称。 | | @register.filter(is_safe=False) | 对/错 | 定义如何处理过滤器的返回值(安全或带自动转义)。 | | @ register . filter(needs _ auto escape = False) | 对/错 | 定义访问调用者的自动转义状态的需要(即，是否在带有或不带有自动转义的模板中调用过滤器)。 | | @ register . filter(expects _ local time = False) | 对/错 | 如果筛选器应用于日期时间值，则在运行筛选器逻辑之前，它会将该值转换为项目时区。 | | @ register . filter()@ string filter | 不适用的 | 将输入转换为字符串的独立装饰器。 |

正如你在表 3-5 中看到的，除了一个选项，所有的自定义过滤器选项都由@register.filter()装饰器的参数提供，并且包括默认值。因此，即使您声明了一个空的@register.filter()装饰器，表 3-5 中五个选项中的四个都使用默认值。注意可以给@register.filter()装饰器添加多个选项，用逗号分隔(例如@register.filter(name='myfilter',is_safe=True))。

下面说说表 3-5 中的name选项。默认情况下，正如您在前面的例子中所了解到的，自定义过滤器的名称与它们修饰的方法相同(也就是说，如果自定义过滤器的后台方法被命名为coffee，那么该过滤器也被称为coffee)。name选项允许您给过滤器一个不同于支持方法名称的名称。注意，如果使用name选项并试图用方法名调用过滤器，你会得到一个错误，因为过滤器不再以方法名存在。

所有自定义过滤器都在由变量提供的输入上操作，这些变量可能是任何 Python 类型(字符串、整数、日期时间、列表、字典等)。).这产生了必须在定制过滤器的逻辑中处理的多种可能性；否则，错误必然是常见的(例如，使用整数变量调用过滤器，但内部过滤器逻辑是为字符串变量设计的)。为了缓解这些潜在的输入类型问题，自定义过滤器可以使用表 3-5 中给出的最后两个选项。

表 3-5 中的expects_localtime选项是为操作datetime变量的过滤器设计的。如果你期待一个datetime输入，你可以将expects_localtime设置为True，这使得datetime输入时区基于你的项目设置而被感知。

表 3-5 中的@stringfilter选项——是一个独立的装饰器，位于@register.filter装饰器的下方——设计用于将过滤器输入变量转换为字符串。这是有帮助的，因为它消除了执行输入类型检查的需要，并且不管过滤器被调用的变量类型是什么(例如，字符串、整数、列表或字典变量)，过滤器逻辑都可以确保它将总是获得字符串。

由于表 3-5 中的is_safe选项默认为False，自定义过滤器的一个微妙但默认的行为是输出被认为是不安全的。

这个默认设置使得来自包含 HTML <b>或<span>标签的清单 3-23 和 3-24 的定制过滤器创建逐字输出(也就是说，您不会看到以粗体显示的文本，而是逐字显示的<b>Open since 1965!</b>)。有时这是想要的行为，但有时不是。

Tip

要使 Django 模板在使用默认设置应用自定义过滤器后呈现 HTML 字符，您可以使用内置的safe过滤器(例如{{byline|coffee|safe}})或使用内置的{% autoescape %}标签(例如{% autoescape off %} {{byline|coffee}} {% endautoescape %}标签)包围过滤器声明。然而，Django filters 也可以将 filter is_safe 选项设置为 True，以使该过程自动化，并避免使用额外的过滤器或标记。

您可以将自定义过滤器中的is_safe选项设置为True，以确保自定义过滤器输出“按原样”呈现(例如，<b>标签以粗体显示)，并且 HTML 元素不会被转义。

这种过滤器设计方法做了一个很大的假设:自定义过滤器总是用包含安全内容的变量来调用。如果byline变量包含文本Open since 1965 & serving > 1000 coffees day!会发生什么？变量现在包含了不安全的字符&和>，为什么它们是不安全的？因为它们在 HTML 中有特殊的含义，如果不转义，就有可能破坏页面布局(例如，>在这个上下文中可能意味着“不止”，但在 HTML 中它也意味着标签打开，浏览器可以将其解释为标记，从而破坏页面，因为它从未关闭)。

为了避免标记不安全的输入字符并在输出时将其标记为安全的潜在问题，您需要依靠调用模板来告诉过滤器输入是安全的还是不安全的，这将我们带到表 3-5 : needs_autoescape.中的最后一个自定义过滤器选项

needs_autoescape选项——默认为 False——用于通知过滤器调用模板中的底层自动转义设置。清单 3-25 显示了一个使用这个选项的过滤器。

from django import template
from django.utils.html import escape
from django.utils.safestring import mark_safe

register = template.Library()

@register.filter(needs_autoescape=True)
def smartcoffee(value, autoescape=True):
    '''Returns input wrapped in HTML tags'''
    '''and also detects surrounding autoescape on filter (if any) and escapes '''
    if autoescape:
        value = escape(value)
    result = '<b>%s</b>' % value
    return mark_safe(result)

Listing 3-25.Django custom filter that detects autoescape setting

filter 方法的needs_autoescape参数和autoescape关键字参数允许过滤器知道在调用过滤器时转义是否有效。如果自动转义开启，那么value通过escape方法来转义所有字符。无论 value 的内容是否转义，过滤器都通过mark_safe方法传递最终结果，因此 HTML <b>标签在模板中被解释为粗体。

这个过滤器比使用is_safe=True选项的过滤器更健壮——并且将所有东西都标记为“安全”——因为它可以处理不安全的输入，只要模板用户正确使用自动转义。

安装和进入

Django 自定义过滤器可以存储在以下两个位置之一:

内部应用。-储存在。py 文件位于 Django apps 中一个名为templatetags的文件夹中。
任何项目位置。-储存在。通过settings.py.中TEMPLATES变量的OPTIONS中的libraries域配置 Django 项目中任意文件夹下的 py 文件

清单 3-26 展示了一个项目目录结构，举例说明了存储定制过滤器的这两个位置。

+-<PROJECT_DIR_project_name>
|
+-__init__.py
+-settings.py
+-urls.py
+-wsgi.py
|
+----common----+
|              |
|              +--coffeehouse_filters.py
|
+----<app_one>---+
|                |
|                +-__init__.py
|                +-models.py
|                +-tests.py
|                +-views.py
|                +-----------<templatetags>---+
|                                              |
|                                              +-__init__.py
|                                              +-store_format_tf.py
+----<app_two>---+
|                |
                 +-__init__.py
                 +-models.py
                 +-tests.py
                 +-views.py
                 +-----------<templatetags>---+
                                               |
                                              +-__init__.py
                                               +-tax_operations.py
Listing 3-26.Django custom filter directory structure

清单 3-26 显示了两个应用，它们在两个不同的文件中包含 Django 定制过滤器- store_formay.tf.py和tax_operations.py。请记住，您需要在 Django app 文件夹中手动创建templatetags文件夹，还需要创建一个__init__.py文件，以便 Python 能够从这个文件夹中导入模块。此外，记住需要在 Django 的settings.py内的INSTALLED_APPS变量中定义应用，以便加载自定义过滤器。

在清单 3-26 中还有一个。py 文件- coffeehouse_filters.py -也包含 Django 自定义过滤器。最后一个定制过滤器文件是不同的，因为它位于一个名为common的通用文件夹中。为了让 Django 在一个通用位置找到一个定制的过滤器文件，您必须将它声明为settings.py中TEMPLATES变量的OPTIONS中libraries字段的一部分。有关使用“库”字段的详细说明，请参阅本章的第一节。

尽管自定义滤镜通常根据其功能放入文件和应用中，但这并不限制自定义滤镜在特定模板中的使用。您可以在任何 Django 模板上使用定制过滤器，而不管定制过滤器存储在哪里。

要在 Django 模板中使用 Django 定制过滤器，你需要在 Django 模板中使用{% load %}标签，如清单 3-27 所示。

{% load store_format_tf %}
{% load store_format_t tax_operations %}
{% load undercoffee from store_format_tf %}
Listing 3-27.Configure Django template to load custom filters

如清单 3-27 所示，有多种方式可以使用{% load %}标签。您可以使自定义文件中的所有过滤器对模板可用。py 在{% load %}标记语法中——或者一次包含多个定制文件。此外，您还可以使用类似 Python 的语法load filter from custom_file有选择地加载某些过滤器。记住{% load %}标签应该在模板的顶部声明。

Tip

如果您发现自己经常使用{% load %}标记，那么您可以使用 builtins 字段使定制过滤器对所有模板都可用。builtins 字段是 settings.py 中 TEMPLATES 变量选项的一部分。有关使用 builtins 字段的详细说明，请参见本章第一节 Django 模板配置。

Footnotes 1

https://en.wikipedia.org/wiki/Escape_character

https://www.python.org/dev/peps/pep-0263/

https://docs.python.org/3/library/codecs.html#standard-encodings

https://docs.python.org/3/library/stdtypes.html#old-string-formatting

https://docs.python.org/3/reference/expressions.html#evaluation-order

四、Django 的 Jinja 模板

除了 Django 模板，Django 框架还支持 Jinja 模板。Jinja 是一个独立的模板引擎项目 ¹ 与 Django 的内置模板系统非常相似。

然而，Django 项目中 Jinja 模板的采用和增长部分是由于 Django 模板的设计限制，自 Django 创建以来，这些模板几乎没有变化。

金贾的优势和劣势

为了让您对 Jinja 模板有一个高层次的了解，并了解它们是否适合您的 Django 项目，我将首先列举 Jinja 模板的一些主要优点和缺点。先说优点:

速度和性能。- Jinja 在首次加载时将模板源代码编译成 Python 字节码，因此模板只需解析一次，从而获得更好的运行时性能。此外，Jinja 还支持提前编译选项，这也可以获得更好的性能。尽管速度和性能是 Jinja 模板最有争议的优势，但考虑到影响速度和性能基准的许多因素(例如，数据库查询/负载、服务器配置)。一般来说，在所有条件相同的情况下，Jinja 模板做的事情和 Django 模板完全一样，Jinja 版本将比 Django 版本快。

Note

公平地说，Django 模板也支持带缓存的定制加载器，以提高速度和性能——如前一章所述——但这需要在 Django 中做进一步的配置工作。

灵活性。- Jinja 模板在内容方面非常灵活，支持宏和更多类似 Python 的结构。虽然 web 模板不鼓励这些做法，但是您会逐渐喜欢上 Django 模板中没有的或者受到严重限制的一些特性。
类似于 Django 模板。- Jinja 实际上是受 Django 模板的启发，所以这两个系统之间有很多共同点。模板继承和块等强大的特性也以同样的方式工作，所以在 Django 项目中使用 Jinja 的学习曲线比您可能意识到的要小。此外，安全特性(例如，自动转义)也紧密集成到了 Jinja 中，就像它们在 Django 模板中一样。
异步执行。-模板有时会加载大量数据或使用需要长时间运行的功能，导致模板延迟，模板必须“等待”后台任务完成(即它们是同步的)。Jinja 模板支持异步执行，这允许支持任务运行它们的进程——没有保留模板——并且稍后在完成时用模板重新集合。注意该特性需要使用异步生成器， ² ，这仅在 Python 3.6 或更新版本中可用。

现在还有一些金贾模板的缺点:

很少或没有第三方软件包支持。-因为 Django 对 Jinja 模板的官方支持相对较新-从 Django 1.8 开始，这是本书所基于的 Django 1.11 的早期长期支持(LTS)版本-几乎所有第三方软件包(例如 Django admin)仍然是用 Django 模板设计的。这使得很难有一个纯粹的 Jinja 模板 Django 项目，并要求 Jinja 模板与 Django 模板共存，这反过来会在需要模板定制时导致困难和混乱。
新概念。-如果你习惯了 Django 模板，一些 Jinja 特性需要额外的练习才能理解和正确使用(例如，Jinja 宏、Jinja 过滤器)。虽然如果你是 Django 的新手，这应该不是问题，因为每个概念都是新的，需要一些实践。

从 Django 模板过渡到 Jinja 模板

如果你习惯于使用 Django 模板，这一节描述了你在使用 Jinja 模板时需要注意的细节，比如你可以在 Jinja 模板中利用哪些 Django 模板知识，与 Django 模板相比，Jinja 模板的工作方式有什么不同，以及你需要学习哪些新的东西，你会逐渐喜欢上 Jinja 模板。

如果您从未使用过 Django 模板，您可以跳到下一节关于 Django 中 Jinja 模板配置的内容，因为接下来的大部分内容是为有经验的 Django 模板用户准备的。

Jinja 和 Django 模板中的工作方式是一样的

仅仅因为 Jinja 是一个完全不同的模板引擎，并不意味着它与 Django 的内置模板引擎完全不同。对于变量和块、条件和循环、注释以及空格和特殊字符，您可以使用相同的方法。

变量和块

花括号{}在 Jinja 模板中被广泛使用，就像在 Django 模板中一样。要在 Jinja 中输出一个变量，可以使用相同的{{myvariable}}语法。类似地，您也可以用{% block footer %} {% endblock %}语法命名块来继承模板之间的代码片段。此外，Jinja 还使用相同的 Django {% extends "base.html" %}语法来创建模板之间的父/子关系。

条件句和循环

Jinja 使用相同的 Django 语法创建条件:{ % if variable %}{% elif othervariable %}{% else %}{% endif %}。此外，Jinja 还使用了与 Django 相同的 for 循环语法:{% for item in listofitems %}{{item}}{% endfor %}。

Jinja 也使用了和 Django 一样的评论标签:{# This is a template comment that isn't rendered #}。然而，note Jinja 对单行和多行注释都使用了{# #}标记。

间距和特殊字符

由于 Jinja 模板的灵感来自 Django 模板，Jinja 使用类似的方法来处理空格和特殊字符。例如，间距过滤器(例如，center和wordwrap)和特殊字符处理(例如，safe和escape过滤器)在 Jinja 模板中的工作方式与在 Django 模板中的相同。

与 Django 模板相比，Jinja 模板有什么不同

然而，在 Jinja 模板中，并不是所有的东西都以同样的方式工作；这里有一些 Django 模板技术，你需要重新学习使用 Jinja 模板。

过滤

尽管 Jinja 使用相同的管道符号|将过滤器应用于变量，但 Jinja 过滤器在技术上分为过滤器和测试。在 Django 模板中，只有执行测试的过滤器(例如，divisibleby)，但在 Jinja 中，这些类型构造被称为测试，并使用条件语法{% if variable is test %}而不是标准管道符号|。

此外，Jinja 过滤器和测试由标准方法支持。这样做的好处是，向 Jinja 过滤器和测试传递参数就像方法调用一样简单(例如，{{variable|filesizeformat(true)}})，而 Django 过滤器的参数语法不直观，需要使用冒号，甚至需要在自定义的 Django 过滤器中解析参数(例如，{{variable|get_digit:"1"}})。

除了与 Django 内置过滤器相似的内置 Jinja 过滤器和测试之外，还可以创建定制的 Jinja 过滤器和测试。然而，与通过{% load %}标签加载到模板中的 Django 过滤器不同，Jinja 定制过滤器和测试是全局注册的，可以像 Django 上下文处理器一样被所有 Jinja 模板访问。

上下文处理器

上下文处理器允许 Django 模板访问项目中每个模板的变量集合，但是在 Jinja 中，这种功能被称为全局变量。这是您可能会错过 Django 模板功能的一个方面，它只是简单地声明上下文处理器和访问变量集。然而，创建 Jinja 全局变量变得可以在所有 Jinja 模板上访问并充当 Django 上下文处理器是相对容易的。

没有像{% now %}标记这样的日期元素，也没有像 time 和 timesince 这样的过滤器

Jinja 在开箱即用状态下不提供标签或过滤器来处理日期或时间。尽管 Jinja 确实提供了format过滤器，其工作方式就像 Python 的标准方法一样，可以用于日期格式化，但是您需要编写自己的定制过滤器和标签，以更高级的方式处理日期和时间元素。

不支持{% comment %}标记

Jinja 使用{# #}标签来定义单行或多行注释，所以不支持{% comment %}，在 Django 模板中，?? 用于多行注释。

不支持{% load %}标记

在 Jinja 中，不支持导入定制标签和过滤器的{% load %}标签。在 Jinja 中，自定义标签和过滤器是全局注册的，并自动可供所有 Jinja 模板访问。

使用{{super()}}而不是{{block.super}}

在 Django 模板中，使用语法{{ block.super }}来访问父模板块的内容。在 Jinja 中，您必须使用{{super()}}语法来访问父模板块的内容。

不支持{% csrf_token %}标记，请使用 csrf_input 或 csrf_token 变量

在 Django 模板中，当您创建一个具有 HTTP POST 动作的表单时，您将{% csrf_token %}标记放在表单体中，以生成一个避免 XSS 的特殊标记(“跨站点脚本”)。要在 Jinja 中复制这种行为，您必须使用csrf_input变量(例如，{{csrf_input}}生成类似<input type="hidden" name="csrfmiddlewaretoken" value="4565465747487">的字符串)或使用包含原始 CSRF 令牌的csrf_token变量(例如，4565465747487)。

{% for %}循环变量

在 Django 模板中，{% for %}循环的上下文提供了对一系列变量的访问(例如，计数器、第一次和最后一次迭代)。Jinja 模板在{% for %}的上下文中提供了一个类似的变量，但它们并不相同。

循环中不支持{% empty %}标记，请使用{% else %}标记

Django 模板中的循环支持将{% empty %}子句作为最后一个参数，以便在迭代为空时生成逻辑或消息。在 Jinja {% for %}循环中，当迭代为空时，可以使用{% else %}子句作为最后一个参数来生成逻辑或消息。

不支持{% groupby %}标记，请使用 groupby 筛选器

Django 模板支持{% groupby %}标签来根据不同的属性重新排列字典或对象。在 Jinja 中你可以实现同样的功能，但是你必须通过 Jinja groupby过滤器中描述的groupby过滤器来实现。

不支持{% cycle %}标记，请在{% for %}循环中使用 cycler 函数或 loop.cycle 变量

Django 模板支持{% cycle %}标签来循环遍历一系列值。在 Jinja 中，这种功能有两种形式。如果需要循环之外的功能，可以使用cycler方法。或者您可以使用所有{% for %}循环中可用的loop.cycle功能。

不支持{% lorem %}标记，请使用 lipsum 函数

Django 模板支持{% lorem %}标签来生成随机的拉丁文本作为填充内容。在 Jinja 中，您可以使用lipsum函数实现相同的功能。

不支持其他杂项标记，如{% static %}、{% trans %}、{% blocktrans %}和

像{% static %}和{% trans %}这样的一系列 Django 模板标签在 Jinja 中根本就没有。然而，有些第三方项目已经将这些和许多其他 Django 模板标签移植到了 Jinja 扩展中。本章后面关于 Jinja 扩展的部分将讨论这些选项。

Jinja 模板与 Django 模板中的新概念和新特性

现在您已经知道了可以利用哪些 Django 模板知识，以及需要重新学习哪些技术才能有效地使用 Jinja 模板，让我们来看看一些只适用于 Jinja 模板的概念。

更有用的内置过滤器、测试，与 Python 环境更相似

Jinja 模板提供了 Django 模板中所缺少的各种内置过滤器和测试。例如，像检查变量类型这样简单的事情(例如，字符串、数字、iterable 等。)，Jinja 为此提供了一系列内置测试，而在 Django 中，这需要创建自定义过滤器。

与 Django 模板相比，Jinja 模板对复杂数据类型(例如对象和字典)的访问和操作也得到了极大的改进。例如，Jinja 提供了诸如reject、select和map之类的过滤器来修剪、过滤或更改模板上的数据子集，这种技术虽然被纯粹主义者(即那些只在视图中操作数据的袖手旁观人)所不喜欢，但在实际和时间受限的项目中却是一种非常常见的需求。

Jinja 模板还支持更符合标准 Python 环境的语法。例如，在 Django 中，像通过变量访问字典键这样的事情需要定制过滤器，而在 Jinja 模板中，这与标准 Python 语法一起工作(例如，如果您有变量stores={"key1":"value1", "key2":"value2"}和var="key1"，Django 模板不能执行标准 Python 语法的stores.get(var)，但是在 Jinja 中，这与 Python 环境的预期一样开箱即用)。

全局函数

Jinja 还支持一系列全局函数。例如，Jinja 提供了range函数，它的工作方式就像 Python 中在循环中有用的标准函数一样(例如{% for number in range(50 - coffeeshops|count) %})。此外，Jinja 还提供了全局函数lipsum来生成虚拟占位符内容、dict来生成字典、cycler来生成元素循环、joiner来连接节。

灵活的标签嵌套、条件和引用

Jinja 在嵌套标签方面非常灵活，尤其是与 Django 模板相比。例如，在 Jinja 中，你甚至可以有条件地应用{% extends %}标签(例如{% if user %}{% extends "base.html" %}{% else %}{% extends "signup_base.html" %}{% endif %})或者使用带有内嵌条件的变量引用名称(例如{% extends layout_template if layout_template is defined else 'master.html' %})——这在 Django 模板中是不可能的。

宏指令

在 Jinja 中，宏允许定义具有复杂布局的类似函数的片段，可以从任何具有不同实例值的模板中调用这些片段。宏对于限制复杂布局在模板间的传播特别有用。使用宏，您可以一次定义一个复杂的布局(即，作为一个宏)，并使用不同的参数调用它，以每次输出定制的复杂布局，就像是一个函数一样。

范围限制较少的模板中的灵活变量赋值

在 Jinja 中，您可以使用{% set %}标签来定义变量，使其在模板结束之前都具有有效的作用域。尽管 Jinja 也支持{% with %}标签——就像 Django 模板版本一样——{% with %}标签对于多个变量定义来说可能会变得很麻烦，因为它需要每次都用{% endwith %}来结束作用域。对于全局模板变量来说，{% set %}是一个很好的选择，因为您只需要初始定义，作用域传播到模板的末尾，而不必担心关闭作用域。

行语句

Jinja 在其所谓的行语句中支持逻辑语句的定义。默认情况下，line 语句前面有一个#符号，可以作为标记语法的替代。例如，{% for %}标记语句{% for item in items %}可以使用等价的行语句# for item in items，正如标记语句{% endfor %}可以使用等价的行语句# endfor.行语句，更重要的是，与使用需要{% %}语法的标记语句相比，给模板一种 Python 的感觉，可以使复杂的逻辑更容易破译。

Django 中的 Jinja 模板配置

在 Django 中使用 Jinja 的第一步是用命令pip install Jinja2安装核心包。请注意，安装的是版本 2(即 Jinja2)，这是最新的版本。虽然 Jinja 1 仍然可用，但是 Django 不提供对版本 1 的内置支持，所以要特别注意确保安装版本 2。

接下来，您需要在settings.py文件中的 Django 项目中配置 Jinja。清单 4-1 展示了 Django 的一个基本 Jinja 配置。

import os
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

TEMPLATES = [
    {
        'BACKEND':'django.template.backends.jinja2.Jinja2',
        'DIRS': ['%s/jinjatemplates/'% (PROJECT_DIR),],
        'APP_DIRS': True,
        },
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Listing 4-1.Jinja configuration in Django settings.py

正如您在清单 4-1 中看到的，在TEMPLATES中声明了两个配置，一个是 Jinja 模板配置的字典，另一个是默认 Django 模板配置的字典。由于 Django 模板仍然被诸如 Django admin 和许多第三方软件包使用，我强烈推荐你使用清单 4-1 中的基本配置，因为它可以防止你无法控制的其他东西被破坏。

清单 4-1 中的金贾配置是最基本的配置之一。在这种情况下，BACKEND变量使用django.template.backends.jinja2.Jinja2值来激活 Jinja 模板，紧接着是DIRS和APP_DIRS变量，它们告诉 Django 在哪里定位 Jinja 模板。

模板搜索路径

APP_DIRS变量允许在名为jinja2的特殊应用子目录中查找模板。如果您希望将 Jinja 模板包含到应用中，这是很有帮助的，但是要注意模板搜索路径并不知道应用的名称空间。例如，如果你有两个应用都依赖于一个名为index.html的模板——如清单 4-2 所示——并且两个应用都在views.py中有一个方法将控制权返回给index.html模板(例如render(request,'index.html'))，那么两个应用都将使用INSTALLED_APPS中最顶层声明的应用中的index.html，因此一个应用不会使用预期的index.html。

# Templates directly under jinja2 folder can cause loading conflicts
+---+-<PROJECT_DIR_project_name_conflict>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
    |
    +-about(app)-+
    |            +-__init__.py
    |            +-models.py
    |            +-tests.py
    |            +-views.py
    |            +-jinja2-+
    |                     |
    |                     +-index.html
    +-stores(app)-+
                 +-__init__.py
                 +-models.py
                 +-tests.py
                 +-views.py
                 +-jinja2-+
                          |
                          +-index.html

# Templates classified with additional namespace avoid loading conflicts
+---+-<PROJECT_DIR_project_name_namespace>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
    |
    +-about(app)-+
    |            +-__init__.py
    |            +-models.py
    |            +-tests.py
    |            +-views.py
    |            +-jinja2-+
    |                     |
    |                     +-about-+
    |                             |
    |                             +-index.html
    +-stores(app)-+
                 +-__init__.py
                 +-models.py
                 +-tests.py
                 +-views.py
                 +-jinja2-+
                          |
                          +-stores-+
                                   |
                                   +-index.html

Listing 4-2.Django apps with jinja2 dirs with potential conflict and namespace qualification

为了解决这个潜在的冲突，推荐的做法是在每个jinja2目录中添加一个额外的子文件夹作为名称空间，如清单 4-2 中的第二组文件夹所示。这样，您就可以使用这个额外的命名空间子文件夹将控件重定向到模板，以避免任何歧义。因此，要将控制权发送给about/index.html模板，您应该声明render(request,'about/index.html')，要将控制权发送给stores/index.html，您应该声明render(request,'about/index.html')。

如果您希望禁止这种允许从这些内部应用子文件夹加载模板的行为，您可以通过将APP_DIRS设置为FALSE来实现。

Jinja 模板更常见的方法是用一个或多个文件夹——位于应用结构之外——来保存 Jinja 模板。Django 首先在第一个DIRS值中寻找匹配的 Jinja 模板，然后在应用的jinja2文件夹中寻找——如果APP_DIRS是TRUE——直到找到匹配的模板或者抛出TemplateDoesNotExist错误。

对于清单 4-1 所示的情况，唯一的DIRS值依赖于一个名为jinjatemplates的目录，该目录相对于由PROJECT_DIR变量确定的路径。当在不同的机器上部署 Django 项目时，这种可变技术很有帮助，因为路径是相对于顶层 Django 项目目录的(即settings.py和主urls.py文件所在的位置)，并且不管 Django 项目安装在哪里(例如/var/www/、/opt/website、C://website/)，都会动态调整。

与 Django 模板OPTIONS变量类似，Jinja 也通过OPTIONS变量支持一系列定制。在 Jinja 的例子中，OPTIONS变量是一个键值字典，对应于 Jinja 环境的初始化参数。 ³

默认情况下，Django 在内部设置一系列 Jinja 环境初始化参数，以使 Jinja 的模板行为与 Django 模板的行为一致。然而，您可以很容易地用OPTIONS变量覆盖这些设置。接下来的部分描述了这些重要的设置。

自动转义行为

Django 默认启用 Jinja 模板自动转义，这种行为在 Jinja 引擎的开箱即用状态下实际上是禁用的。自动转义的症结在于，一方面，它在预防和安全性方面出错——限制了在 HTML 中破坏输出或引入 XSS(跨站点脚本)漏洞的可能性——但另一方面，它也在模板引擎中引入了额外的处理，这会导致性能问题。

默认情况下，Django 模板自动转义模板变量的所有输出——<被转换为< , >被转换为> , '(单引号)被转换为' , "(双引号)被转换为"并且&被转换为&amp –，除非您明确禁用此行为。Jinja 在开箱即用状态下不会自动转义任何东西，当您想要自动转义某些东西时，您需要明确地告诉它。

因为 Django 的 Jinja 模板集成是由 Django 设计者完成的，所以为了安全起见，Jinja 自动转义被启用，就像 Django 模板一样。但是，您可以使用OPTIONS中的autoescape参数禁用 Jinja 自动转义，如清单 4-3 所示。

import os
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

TEMPLATES = [
    {
        'BACKEND':'django.template.backends.jinja2.Jinja2',
        'DIRS': ['%s/jinjatemplates/'% (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'autoescape': False
        },
    }
]

Listing 4-3.Jinja disable auto-escaping in Django

正如你在清单 4-3 中看到的，autoescape被赋值为False，随着这一变化，Jinja 模板的行为就像 Jinja 设计者想要的那样(也就是说，你需要明确地检查哪里需要自动转义，而 Django 模板检查哪里不需要自动转义)。

自动重新加载模板行为和缓存

在开箱即用状态下，Jinja 的模板加载器会在每次请求模板时进行检查，以查看源代码是否发生了变化；如果已经更改，Jinja 会重新加载模板。这在模板的源代码不断变化的开发中很有帮助，但在生产中也会影响性能，因为模板的源代码很少变化，检查会导致延迟。

默认情况下，Django 框架 Jinja 集成采用了一种明智的方法，并基于settings.py中的DEBUG变量启用 Jinja 模板自动重载。如果DEBUG=True -开发中的常用设置- Jinja 模板自动重装设置为True，如果DEBUG=False -生产中的常用设置- Jinja 模板自动重装设置为False。然而，您可以用OPTIONS中的auto_reload参数显式设置 Jinja 的自动加载行为。

默认情况下，Jinja 引擎还可以缓存多达 400 个模板。这意味着当加载模板 401 时，Jinja 清除最近最少使用的模板，如果以后需要，后者必须从其原始位置重新加载。Jinja 缓存限制可通过OPTIONS中的cache_size参数进行调整(如cache_size=1000，设置 1000 个模板缓存)。将cache_size设置为 0(零)禁用缓存，将cache_size设置为-1 启用无限制缓存。

Jinja 模板中另一个可用的缓存机制是字节码缓存。当您创建 Python 源文件(即那些带有.py扩展名的文件)时，Python 会生成带有包含字节码的.pyc扩展名的镜像文件。生成这些字节码文件需要时间，但它们是 Python 运行时过程的自然组成部分。基于 Python 的 Jinja 模板也需要转换成字节码，但这是一个你可以用OPTIONS中的bytecode_cache参数定制的过程。

可以为bytecode_cache参数分配一个定制的字节缓存 ⁴ 或者 Jinja 的一个内置字节码缓存，它包括对标准文件系统缓存的支持或者使用 memcached 的更专门的缓存。

无效的模板变量

当在 Jinja 模板中遇到无效变量时，您可以设置各种行为。Django 为 Jinja 设置了两个默认行为，一个用于 whenDEBUG=True——开发中的常见设置——另一个用于 whenDEBUG=False——生产中的常见设置。

如果在 Jinja 模板中设置了DEBUG=True和一个无效变量，Jinja 使用jinja2.DebugUndefined类来处理它。jinja2.DebugUndefined类逐字输出变量进行呈现(例如，如果模板有{{foo}}语句，而变量在上下文中不存在，Jinja 输出{{foo}}，这样更容易发现无效变量)。

如果在 Jinja 模板中设置了DEBUG=False和一个无效变量，Jinja 使用jinja2.Undefined类来处理它。jinja2.Undefined类在变量的位置输出一个空格用于呈现(例如，如果模板有{{bar}}语句，而变量在上下文中不存在，Jinja 输出一个空格)。值得一提的是，最后一种行为符合 Django 模板中无效变量的默认行为。

除了jinja2.DebugUndefined和jinja2.Undefined类，Jinja 还支持jinja2.StrictUndefined类。jinja2.StrictUndefined类用于生成即时错误，而不是继续渲染，这有助于更快地诊断无效变量。然而，要注意最后一个类基于DEBUG变量改变了它的行为；它要么生成一个带有无效变量名的堆栈错误(即当DEBUG=True时)，要么生成一个标准的 HTTP 500 错误页面(即当DEBUG=False时)。

清单 4-4 展示了如何通过settings.py中的OPTIONS参数配置一个 Jinja 类来处理无效变量。

import os
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

import jinja2

TEMPLATES = [
   {
        'BACKEND':'django.template.backends.jinja2.Jinja2',
        'DIRS': ['%s/jinjatemplates/'% (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'undefined':jinja2.StrictUndefined
        },
    }
]

Listing 4-4.Generate error for invalid variables in Jinja with jinja2.StrictUndefined

正如你在清单 4-4 中看到的，我们首先声明import jinja2来访问settings.py中 Jinja 的类。接下来，我们在OPTIONS参数中声明了undefined键，并将其分配给 Jinja 类来处理无效变量。在这种情况下，当遇到无效模板变量时，我们使用jinja2.StrictUndefined类来获取错误，但是您同样可以使用其他两个 Jinja 类中的任何一个来处理无效变量(即jinja2.DebugUndefined或jinja2.Undefined)。

模板加载器

Jinja 模板加载器是 Python 类，它实现了搜索和加载模板所需的实际逻辑。在前面的“模板搜索路径”一节中，我描述了 Jinja 如何使用DIRS和APP_DIRS变量搜索模板，这是 Django 模板配置的一部分。然而，我有意忽略了与这个模板搜索过程相关的一个更深层的方面:每个搜索机制都由一个模板加载器支持。

在大多数情况下，你不需要处理 Jinja 模板加载器，因为 Jinja 加载器是在后台处理的，只需要依靠DIRS和APP_DIRS变量。但是如果您需要从这些位置之外的地方加载 Jinja 模板(例如，从内存结构或数据库)，您可以在OPTIONS参数中用loader键指定模板加载器。

像 Django 模板加载器一样，除了使用类似于 Django 模板提供的内置 Jinja 模板加载器(例如，从 Python 字典加载模板)，Jinja 还提供创建定制模板加载器、^【5】的能力。

Tip

您可以在选项中为任何 Jinja 环境初始化参数 ⁶ 设置自定义值。前面的部分只是四个最常见的 Jinja 模板参数；后面的部分描述了其他可用的选项。

Note

OPTIONS 仅用于 Jinja 环境的初始化参数；其他 Jinja 环境设置需要配置单独的 Jinja 环境类(例如，Jinja 全局、Jinja 自定义过滤器和测试以及 Jinja 策略)。

创建可重用的 Jinja 模板

使用可重用的 Jinja 模板，您可以在单独的模板上定义公共部分，并在其他模板中重用它们。此过程使创建和管理项目模板变得容易，因为单个模板更新会影响所有模板。

可重用的 Jinja 模板还允许您定义页面块来逐页覆盖内容。此过程使项目的模板更加模块化，因为您定义了顶级块来建立整体布局并逐页定义内容。

让我们通过探索 Jinja 内置的{% block %}标签，向构建可重用的 Jinja 模板迈出第一步。清单 4-5 展示了一个名为base.html的带有几个{% block %}标签的模板的第一行。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>{% block title%}Default title{% endblock title %}</title>
    <meta name="description" content="{% block metadescription%}{% endblock metadescription %}">
    <meta name="keywords" content="{% block metakeywords%}{% endblock metakeywords %}">
Listing 4-5.Jinja template with {% block %} tags

注意清单 4-5 中的语法{% block <name>%}{% endblock <name>%}。每个{% block %}标签都有一个引用名。其他 Jinja 模板使用该引用名称来覆盖每个块的内容。例如，HTML <title>标签中的{% block title %}标签定义了一个网页标题。如果另一个模板重用清单 4-5 中的模板，它可以通过覆盖标题块来定义自己的网页标题。如果未在模板上覆盖块，则块将接收块中的默认内容。对于标题栏，默认内容是Default title，对于metadescription和metakeywords栏，默认内容是一个空字符串。

清单 4-5 中所示的相同机制可以用来定义任意数量的块(例如，内容、菜单、页眉、页脚)。值得一提的是{% endblock <name> %}的<name>参数是可选的，仅使用{% endblock %}来结束一个 block 语句是有效的；但是，前一种技术使得 block 语句的结束位置更加清晰，这在一个模板有多个块时尤其有用。

尽管可以通过 Django 视图方法或 url 请求直接调用清单 4-5 中的模板，但这种模板的目的是将其用作其他模板的基础模板。要重用 Jinja 模板，您可以使用 Jinja 内置的{% extends %}标签。

{% extends %}标签使用语法{% extends <name> %}来重用另一个模板的布局。这意味着为了重用在文件base.html中定义的清单 4-5 中的布局，您使用语法{% extends "base.html" %}，如清单 4-6 所示。

{% if user %}{% extends "base.html" %}{% else %}{% extends "signup_base.html" %}{% endif %}
{% block title %}Coffeehouse home page{% endblock %}
Listing 4-6.Jinja template with {% extends %} and {% block %} tag

看看清单 4-6 如何使用包裹在{% if user %}语句周围的{% extends "base.html" %}。如果定义了user变量，Jinja 扩展了base.html模板；否则它扩展了signup_base.html模板。这种条件语法在 Django 模板中是不可能的。

此外，注意清单 4-6 是如何用内容Coffeehouse home page定义{% block title %}标签的。清单 4-6 中的块覆盖了base.html模板中的title块。那么清单 4-6 中的 HTML <title>标签在哪里呢？没有，你也不需要。Jinja 自动重用来自base.html或signup_base.html模板的布局，并在必要的地方替换块的内容。

重用其他模板的 Jinja 模板倾向于使用有限的布局元素(例如 HTML 标签)和更多的 Jinja 块语句来覆盖内容。这是有益的，因为正如我前面所概述的，它允许您一次建立整体布局，并在逐页的基础上定义内容。

Jinja 模板的可重用性可以多次出现。例如，你可以有模板 A、B 和 C，其中 B 需要重用 A，但是 C 需要重用 B 的一部分，唯一的区别是模板 C 需要使用{% extends "B" %}标签而不是{% extends "A"%}标签。但是由于模板 B 重用了 A，模板 C 也可以访问模板 A 中的相同元素。

当重用 Jinja 模板时，也可以从父模板访问块内容。Jinja 通过super()方法公开父模板中的块内容。清单 4-7 展示了三个模板，展示了包含网页路径或“面包屑”的块的这种机制。

# base.html template
<p>{% block breadcrumb %}Home{% endblock %}</p>

# index.html template
{% extends "base.html" %}
{% block breadcrumb %}Main{% endblock %}

# detail.html template
{% extends "index.html" %}
{% block breadcrumb %} {{super()}} : Detail {% endblock %}

Listing 4-7.Jinja templates use of super() with three reusable templates

清单 4-7 中的base.html模板用默认值Home定义了breadcrumb块。接下来，index.html模板重用base.html模板并用值Main覆盖面包屑块。最后，detail.html模板重用index.html模板并覆盖breadcrumb块值。但是，请注意最终块覆盖中的{{super()}}语句。因为{{super()}}在breadcrumb块中，{{super()}}告诉 Jinja 从父模板块中获取内容。

Jinja 模板支持的另一个可重用功能是将一个 Jinja 模板包含在另一个 Jinja 模板中。Jinja 通过{% include %}标签支持这一功能。

默认情况下，{% include %}标签需要一个模板的名称。例如，{% include "footer.html" %}在声明模板的位置插入footer.html模板的内容。{% include %}标签也让底层模板知道变量。这意味着footer.html模板可以有变量定义(例如{{year}}，如果调用模板有这些变量定义，{% include %}标签会自动替换这些值。

此外，还可以提供一个模板列表作为后备机制。例如，{% include ['special_sidebar.html', 'sidebar.html'] ignore missing %}告诉 Jinja 首先尝试定位special_sidebar.html模板，如果没有找到就尝试定位sidebar.html模板；如果两个模板都没有找到，最后一个参数ignore missing告诉 Jinja 不要渲染任何东西。注意ignore missing参数也可以用在单独的语句中(例如{% include "footer.html" ignore missing %}，以及列表)。此外，如果没有使用ignore missing语句，并且 Jinja 找不到在{% include %}中声明的匹配模板，Jinja 会引发一个异常。

标签允许跨模板定义可重用的内容片段。例如，如果您需要合并精细标记来显示具有共同特征的元素，您可以在一个{% macro %}语句中定义一次精细标记，然后重用这个{% macro %}来输出为每个元素实例定制的标记。

宏非常有用，因为如果您决定更改标记，只需在一个位置进行更改，更改就会传播到其他位置。清单 4-8 展示了{% macro %}语句的定义及其在模板中的用法。

# base.html template
{% macro coffeestore(name, id='', address='', city='San Diego', state='CA', email=None) -%}
    <a id="{{id}}"></a>
    <h4>{{name}}</h4>
    <p>{{address}} {{city}},{{state}}</p>
    {% if email %}<p><a href='mailto:{{email}}'>{{email}}</a></p>{% endif %}
{%- endmacro %}

# index.html template calls inherited macro directly
{% extends "base.html" %}
{{coffeestore('Downtown',1,'Horton Plaza','San Diego','CA','downtown@coffeehouse.com')}}
# detail.html template with no extends, uses {% import %} to access macro in base.html
{% import 'base.html' as base %}
{{base.coffeestore('Downtown',1,'Horton Plaza','San Diego','CA','downtown@coffeehouse.com')}}

# otherdetail.html template with no extends, uses {% from import %} to access macro in base.html
{% from 'base.html' import coffeestore as mycoffeestoremacro %}
{{mycoffeestoremacro('Downtown',1,'Horton Plaza','San Diego','CA','downtown@coffeehouse.com')}}

Listing 4-8.Jinja {% macro %} definition and use of {% import %}

清单 4-8 中做的第一件事是在base.html模板中声明的{% macro %}定义。注意，在{% macro片段之后，有一个名为coffeestore的常规方法，它对应于带有六个输入参数的宏的名称，其中五个有默认值。接下来，在{% macro %}和{% endmacro %}语句中，您可以看到一些精心制作的 HTML 标记，它们利用标准的{{ }}语法来输出在给定宏实例上传递的任何变量值。

由于清单 4-8 中的{% macro %}是在base.html模板中定义的，任何其他使用base.html模板的模板都可以访问该宏，并调用带有实例的宏(例如{{coffeestore('Downtown',1,'Horton Plaza','San Diego','CA','downtown@coffeehouse.com')}} -为简单起见是硬编码的值)来呈现用实例值定制的 HTML 标记。

如果你想在其他模板中访问一个{% macro %}，你有三个选择，也在清单 4-8 中给出。如果一个模板扩展了另一个模板(如{% extends "base.html" %})，那么默认情况下，它也将获得对父模板{% macro %}定义的访问权。也可以用{% import %}语句访问另一个模板的{% macro %}定义。例如，语句{% import 'base.html' as base %}将base.html定义导入到另一个具有基本名称空间的模板中，在这种情况下，要调用名为coffeestore的{% macro %}，您将使用{{base.coffeestore(...}}语法。最后，也可以用{% from import %}语句有选择地导入{% macro %}定义。例如，语句{% from 'base.html' import coffeestore as mycoffeestoremacro %}从base.html模板导入coffeestore定义，并将其放在mycoffeestoremacro名称下，在这种情况下，您将使用{{mycoffeehousemacro(...}}语法来调用{% macro %}。

{% call %}标签是另一个选项，与{% macro %}标签一起使用，有利于宏本身的可重用性。{% call %}标签的第一个使用场景是调用一个{% macro %}，它需要一个占位符，用于在调用宏之前定义的内容。清单 4-9 展示了{% call %}标签和{% macro %}标签的基本场景。

# macro definition
{% macro contentlist(adcolumn_width=3,contentcolumn_width=6) -%}
   <div class="col-md-{{adcolumn_width}}">
    Sidebar ads
   </div>
   <div class="col-md-{{contentcolumn_width}}">
      {{ caller() }}
   </div>
   <div class="col-md-{{adcolumn_width}}">
    Sidebar ads
   </div>
{%- endmacro %}

# macro call/invocation
{% call contentlist() %}
  <ul>
    <li>This is my list</li>
  </ul>
{% endcall %}

# rendering
<div class="col-md-3">
    Sidebar ads
</div>
<div class="col-md-6">
  <ul>
    <li>This is my list</li>
  </ul>
</div>
<div class="col-md-3">
    Sidebar ads
</div>

Listing 4-9.Jinja {% call %} and {% macro %}

use

在清单 4-9 中，我们首先定义一个与清单 4-8 结构相似的{% macro %}；但是，请注意在{% macro %}中的{{ caller() }}语句。{% macro %}中的caller()方法作为占位符被调用实体替换。

接下来，在清单 4-9 中，您可以看到{% call %}语句是用宏调用声明的——在本例中是contentlist()—{% call %}语句的主体包含一个 HTML 列表。当 Jinja 执行{% call %}语句时，{% call %}内容被放在{% macro %} {{caller()}}声明的位置。

带有{% macro %}的{% call %}标签的一个更高级的场景是让caller()语句使用引用，这个过程对于本质上是递归的数据来说更自然(例如，宏在宏之上)。清单 4-10 展示了{% call %}标签和{% macro %}的递归场景。

# macro definition
{% macro contentlist(itemlist,adcolumn_width=3,contentcolumn_width=6) -%}
   <div class="col-md-{{adcolumn_width}}">
    Sidebar ads
   </div>
   <div class="col-md-{{contentcolumn_width}}">
     {% for item in itemlist %}
      {{ caller(item) }}
     {% endfor %}
   </div>
   <div class="col-md-{{adcolumn_width}}">
    Sidebar ads
   </div>
{%- endmacro %}

# variable definition
{% set coffeestores=[{'id':0,'name':'Corporate','address':'624 Broadway','city':'San Diego','state':'CA','email':'corporate@coffeehouse.com'},{'id':1,'name':'Downtown','address':'Horton Plaza','city':'San Diego','state':'CA','email':'downtown@coffeehouse.com'},{'id':2,'name':'Uptown','address':'1240 University Ave','city':'San Diego','state':'CA','email':'uptown@coffeehouse.com'},{'id':3,'name':'Midtown','address':'784 W Washington St','city':'San Diego','state':'CA','email':'midtown@coffeehouse.com'}] %}

# macro call/invocation
{% call(item) contentlist(coffeestores) %}
    <a id="{{item.id}}"></a>
    <h4>{{item.name}}</h4>
    <p>{{item.address}} {{item.city}},{{item.state}}</p>
    {% if item.email %}<p><a href='mailto:{{item.email}}'>{{item.email}}</a></p>{% endif %}
{% endcall %}

# rendering
<div class="col-md-3">
    Sidebar ads
</div>
<div class="col-md-6">
    <a id="0"></a>
    <h4>Corporate</h4>
    <p>624 Broadway San Diego,CA</p>
    <p><a href="mailto:corporate@coffeehouse.com">corporate@coffeehouse.com</a></p>

    <a id="1"></a>
    <h4>Downtown</h4>
    <p>Horton Plaza San Diego,CA</p>
    <p><a href="mailto:downtown@coffeehouse.com">downtown@coffeehouse.com</a></p>

    <a id="2"></a>
    <h4>Uptown</h4>
    <p>1240 University Ave San Diego,CA</p>
    <p><a href="mailto:uptown@coffeehouse.com">uptown@coffeehouse.com</a></p>

    <a id="3"></a>
    <h4>Midtown</h4>
    <p>784 W Washington St San Diego,CA</p>
    <p><a href="mailto:midtown@coffeehouse.com">midtown@coffeehouse.com</a></p>
</div>
<div class="col-md-3">
    Sidebar ads
</div>

Listing 4-10.Jinja {% call %} and {% macro %} recursive calls

正如您在清单 4-10 中看到的，{% macro %}定义现在有了一个名为itemlist的参数，它在这个参数上创建了一个迭代，并为每个条目调用了{{caller(item)}}。还要注意清单 4-10 中的{% call %}语句现在是{% call(item) contentlist(coffeestores) %}，其中 item 表示从宏发送的回调项，而contentlist(coffeestores)是对名为contentlist的宏的实际调用及其输入coffeestores，这是一个字典列表。当 Jinja 执行{% call %}语句时，{% call %}内容在每一项上递归运行，结果输出显示在清单 4-10 的底部。

Tip

与使用变量的{% macro %}语句相比，Jinja 内置过滤器一节中描述的内置{% set %} statemen t 为静态内容块提供了更简单的重用功能。(如{ % set advertisement % }

< /div > {% endset %}创建广告变量，可以输出模板中任意位置{% set %}和{% endset %}之间的内容。

Jinja Globals:访问所有 Jinja 模板上的数据，比如 Django 上下文处理器

就像 Django 模板提供了上下文处理器来帮助访问所有 Django 模板上的数据一样，Jinja 也提供了自己版本的相同特性，称为 globals。Jinja 在它的开箱即用状态中没有全局变量，但是在它的 Django 集成模式中包括三个全局变量来模仿 Django 最常见的上下文处理器，这些全局变量是request、csrf_input和csrf_token。

这意味着您可以访问三个 Django 上下文处理器，比如 Django 项目中使用的所有 Jinja 模板中的变量。然而，要设置额外的全局变量，您需要使用 Jinja 的环境。

要设置 Jinja 全局变量，你需要访问 Jinja 的环境，全局变量存储在一个名为globals的变量中。默认情况下，Django-Jinja 配置使用 Jinja 的内置jinja2.Environment环境。为了在 Django 中访问 Jinja 的环境并设置全局变量，最简单的方法是创建自己的 Jinja 环境，并使用它来初始化 Django-Jinja 配置。清单 4-11 展示了一个定制的 Jinja 环境类，它设置了名为static和url的全局变量。

from jinja2.environment import Environment
from django.contrib.staticfiles.storage import staticfiles_storage
from django.core.urlresolvers import reverse

class JinjaEnvironment(Environment):
    def __init__(self,**kwargs):
        super(JinjaEnvironment, self).__init__(**kwargs)
        self.globals['static'] = staticfiles_storage.url
        self.globals['reverse'] = reverse

Listing 4-11.Custom Jinja environment with global variable

正如您在清单 4-11 中看到的，自定义JinjaEnvironment类是jinja2.Environment类的子类；这就是为什么定制类继承了 Jinja 提供的基类的大部分特性。接下来，你可以看到我们使用__init__方法来初始化基类。

在退出该类的初始化方法之前，您还可以看到我们访问了实例的globals变量。globals由一个字典组成，其中的键值分别对应于 Jinja 模板变量名和值。在这种情况下，我们创建静态变量，并将其赋给 Django 的django.contrib.staticfiles.storage.staticfiles_storage.url方法。这赋予了static全局变量与 Django 的 staticfiles 应用相同的行为，这样就可以像在 Django 中一样声明静态资源(例如，Jinja 可以做<img src="{{ static('images/background.png') }}" alt="Background">)——这个主题在关于静态资源管理的第五章中有更详细的描述，但这里提到这一点很重要，因为它填补了 Jinja 在这方面缺乏功能的空白。

清单 4-11 中的第二个全局变量创建了 url 变量，并将其赋给 Django 的django.core.urlresolvers.reverse方法。这使得url全局变量具有与 Django 的{% url %}标签相同的行为，因此可以基于名称解析 URL——如第二章 Django url 管理和反向匹配中所述——就像在 Django 中完成的一样(例如，Jinja 可以做<a href="{{ url('homepage') }}">Go to homepage</a>)—注意这是另一个重要的空白，因为 Jinja 在这方面缺乏功能。

正如您可以添加这最后两个全局变量来模拟 Jinja 模板中缺少的 Django 应用和标签的行为一样，您可以以相同的方式添加更多的全局变量，或者根据需要增加 Jinja 全局变量的复杂性。

一旦定制的 Jinja 环境准备好了，您需要在 Django 的settings.py文件中设置它，这样就可以用它来初始化 Jinja。清单 4-12 展示了如何在 Django 中设置一个定制的 Jinja 环境。

TEMPLATES = [
    {
        'BACKEND':'django.template.backends.jinja2.Jinja2',
        'DIRS': ['%s/templates/'% (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'environment': 'coffeehouse.jinja.env.JinjaEnvironment'
            }
        },
    ]
Listing 4-12.Configure custom Jinja environment in Django setttings.py

Jinja 环境通过environment键设置，作为OPTIONS变量的一部分。环境键的值是一个带有点符号的字符串，它指向一个定制的 Jinja 环境类。在这种情况下，可以看到值对应于coffeehouse.jinja.env.JinjaEnvironment，其中JinjaEnvironment是类，env是文件/模块名，coffeehouse.jinja是目录路径。

为了更好地展示包含定制 Jinja 环境的env.py文件的位置，清单 4-13 展示了一个包含额外 Django 项目文件的目录结构以供参考。

+---+-<PROJECT_DIR_coffeehouse>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
    |
    +-jinja-+
            +-__init__.py
            +-env.py
Listing 4-13.Directory structure and location of custom Jinja environment

Jinja 内置的语句/标签和函数(如 Django 模板标签)

Jinja 提供了几个内置的语句/标签，可以直接访问 Jinja 模板上的复杂操作。我将把这些内置的语句/标签和函数分成几个部分，这样更容易识别它们；注意，我将添加引用(Function)来表明它引用了一个 Jinja 函数。我将使用的类别是比较操作、循环、Python 和过滤器操作、空格和特殊字符以及模板结构。

比较操作

{% if %}同{% elif %} {% else %}。-{% if %}语句是评估条件的主要构件。{% if %}语句通常与{% elif %}和{% else %}语句结合使用，以评估多个条件。如果变量存在且不为空，或者变量包含真布尔值，则带有自变量变量的{% if %}语句计算为真。清单 4-14 展示了一系列{% if %}语句示例。

{% if drinks %}             {% if drinks %}              {% if drinks %}
  We have drinks!                We have drinks              We have drinks
{% endif %}                 {% else %}                   {% elif drinks_on_sale %}
                                No drinks,sorry              We have drinks on sale!
                            {% endif %}                  {% else %}
                                                             No drinks, sorry
                                                         {% endif %}
Listing 4-14.Jinja {% if %} statement with {% elif %} and {% else %}

Note

变量必须既存在又不为空才能匹配条件。只存在且为空的变量不符合条件。

{% if %}带and、or和not操作符。-{% if %}语句还支持and、or和not操作符来创建更复杂的条件。这些运算符允许您比较多个变量是否为非空(如{% if drinks and drinks_on_sale %})、一个或另一个变量是否为非空(如{% if drinks or drinks_on_sale %})或一个变量是否为空(如{% if not drinks %})。
{% if %}带==、!=、<、>、<=和>=操作符。-{% if %}语句还支持等于、不等于、大于和小于运算符，以创建将变量与固定字符串或数字进行比较的条件。这些运算符允许您比较变量是否等于字符串或数字(如{% if drink == "mocha" %})、变量是否不等于变量或数字(如{% if store_id != 2 %})或变量是否大于或小于数字(如{% if store_id > 5 %})。
{% if <value> in %}和{% if <value> not in %}。-{% if %}语句还支持in和not in操作符来验证常量或变量的存在。例如，{% if "mocha" in drinks %}测试值"mocha"是否在drinks列表变量中，或者{% if 2 not in stores %}测试值2是否不在stores列表变量中。虽然in和not in操作符通常用于测试列表变量，但是也可以测试字符串中是否存在字符(例如{% if "m" in drink %})。此外，还可以比较一个变量的值是否出现在另一个变量中(如{% if order_drink in drinks %})。

环

{% for %}和{% for %}同{% else %}。-{% for %}语句迭代字典、列表、元组或字符串变量上的项目。{% for %}语句语法是{% for <reference> in <variable> %}，其中<reference>在每次迭代中被赋予一个来自<variable>的新值。根据变量的性质，可以有一个或多个引用(例如，对于列表有一个引用，对于字典有两个引用)。{% for %}语句还支持{% else %}语句，该语句在循环中没有迭代的情况下被处理(即主变量为空)。清单 4-15 展示了一个{% for %}和一个{% for %}和{% else %}循环示例。

<ul>                                  <ul>
{% for drink in drinks %}              {% for storeid,store in stores %}
 <li>{{ drink.name }}</li>               <li><a href="/stores/{{storeid}}/">{{store.name}}</a></li>
{% else %}                             {% endfor %}
 <li>No drinks, sorry</li>            </ul>
{% endfor %}
</ul>
Listing 4-15.Jinja {% for %} statement and {% for %} with {% else %}

{% for %}语句还生成一系列变量来管理迭代过程，例如迭代计数器、第一次迭代标志和最后一次迭代标志。表 4-1 说明了{% for %}语句变量。

表 4-1。

Jinja {% for %} statement variables

| 可变的 | 描述 | | --- | --- | | 循环索引 | 循环的当前迭代(1 索引)。 | | 循环.索引 0 | 循环的当前迭代(索引为 0)。 | | walk.revindex | 从循环结束开始的迭代次数(以 1 为索引)。 | | loop.revindex0 | 从循环结束开始的迭代次数(以 0 为索引)。 | | 循环优先 | 如果是第一次通过循环，则为 True。 | | loop.last | 如果是最后一次循环，则为 True。 | | 循环长度 | 序列中的项目数。 | | 循环 | 在序列列表之间循环的辅助函数。 | | 循环深度 | 指示当前渲染在递归循环中的深度，从级别 1 开始 | | 循环深度 0 | 指示当前渲染在递归循环中的深度，从级别 0 开始。 |

Nested Jinja Loops: Use Reference Variable and Cycle Variable

在某些情况下，您可能需要嵌套多个{% for %}语句并访问父循环项。在 Django 模板中，这很容易，因为有一个专门用于这个目的的变量。然而，正如你在表 4-1 中看到的，Jinja 模板没有这个变量。Jinja 模板中的一个解决方案是在进入子循环以访问父循环之前用{% set %}定义一个引用变量，如下面的代码片段所示。

<ul>

{% for chapter in chapters %}

  {% set chapterloop = loop %}

  {% for section in chapter %}

    <li> {{ chapterloop.index }}.{{ loop.index }}">{{ section }}</li>

  {% endfor %}

{% endfor %}

</ul>

Jinja 模板中的另一个嵌套循环特性是 cycle，这在 Django 模板中是不存在的(至少作为一个变量，它作为一个标签存在)。cycle 的主要用途是定义 CSS 类，以便每次迭代接收不同的 CSS 类，并且在渲染时每次迭代以不同的颜色显示。下面的代码片段说明了循环变量的用法。

{% for drink in drinks %}

 <li class="{{ loop.cycle('odd', 'even') }}">{{ drink.name }}</li>

{% endfor %}

Note cycle 可以顺序迭代任意数量的字符串或变量(如{{ loop.cycle('red' 'white' 'blue') }})。

{% for %}同if。-{% for %}语句还支持包含if语句来过滤字典、列表、元组或字符串变量的迭代。通过这种方式，您可以将迭代限制为通过或未通过某个标准的元素。带有if子句的{% for %}语句语法是{% for <reference> in <variable> if <test_for_reference>%}(例如{% for drink in drinks if drink not in ['Cappuccino'] %})

{% for %}带recursive关键字。-{% for %}语句还支持嵌套字典、列表、元组或字符串变量的递归。您可以使用递归在每个嵌套结构上重用相同的布局，而不是创建多个嵌套的{% for %}语句。清单 4-16 展示了 Jinja 中一个递归循环的例子。

# Dictionary definition
coffees={
    'espresso':
         {'nothing else':'Espresso',
          'water': 'Americano',
          'steamed milk': {'more steamed milk than milk foam': 'Latte',
                           'chocolate syrup': {'Whipped cream': 'Mocha'}
           },
           'more milk foam than steamed milk': 'Capuccino'
     }
}

# Template definition with for and recursive
{% for ingredient,result in coffees.iteritems() recursive %}
    <li>{{ ingredient }}
    {% if result is mapping %}
        <ul>{{ loop(result.iteritems()) }}</ul>
    {% else %}
         YOU GET:  {{ result }}
    {% endif %}</li>
{% endfor %}

# Output
espresso
     water YOU GET: Americano
     steamed milk
          more steamed milk than milk foam YOU GET: Latte
          chocolate syrup
               Whipped cream YOU GET: Mocha
     more milk foam than steamed milk YOU GET: Capuccino
     nothing else YOU GET: Espresso

Listing 4-16.Jinja {% for %} statement with recursive keyword

{% break %}和{% continue %}。-{% break %}和{% continue %}语句在{% for %}语句中可用，允许你跳出循环或继续下一次迭代，就像常规 Python 循环中可用的相同关键字一样。

Note

{% break %}和{% continue %}需要启用内置的 jinja2.ext.loopcontrols 扩展。请参阅本章倒数第二节，了解如何启用 Jinja 扩展。

range(功能)。-range函数的工作方式就像 Python 的标准函数一样，当您想要在从 I 到 j-1 的给定数字范围内生成一个循环时非常有用。例如，range(0,5)生成范围[0,1,2,3,4]。此外，range 功能还支持在第三个位置覆盖步数-默认为 1(例如，range(0,11,2)生成[0,2,4,6,8,10])。

cycler(函数))。-cycler功能允许您在一系列值之间循环。它的工作就像在{% for %}循环中可用的loop.cycle变量，除了cycler函数可以在循环外使用。cycler函数使用其next()方法前进一项，使用reset()方法循环到第一项，使用当前属性返回当前项。清单 4-17 展示了一个带有 CSS 类的 cycler 方法定义，然后在多个{% for %}循环中使用它来定义一个列表，其中每个项目基于循环迭代被分配一个不同的 CSS 类。

{% set row_class = cycler('white','lightgrey','grey') %}

<ul>
{% for item in items %}
  <li class="{{ row_class.next() }}">{{ item }}</li>
{% endfor %}
{% for otheritem in moreitems %}
  <li class="{{ row_class.next() }}">{{ otheritem }}</li>
{% endfor %}

# Output
<ul>
  <li class="white">Item 1</li>
  <li class="lightgrey">Item 2 </li>
  <li class="grey">Item 3 </li>
  <li class="white">Item 4</li>
  <li class="lightgrey">Item 5</li>
  <li class="grey">Other item 1</li>
  <li class="white">Other item 2</li>
</ul>

Listing 4-17.Jinja cycler function

joiner(功能)。-joiner函数允许您将一系列不同的部分连接起来，并用给定的分隔符将它们连接起来，分隔符默认为逗号空格(“”)。joiner 函数的一个特性是，除了第一次在部分依赖于条件的情况下给出正确的外观之外，它在每次调用时都返回分隔符字符串。清单 4-18 展示了一个 joiner 方法定义，用斜杠空格(“/”)作为分隔符，然后用它来连接一列部分。

{% set slash_joiner = joiner("/ ") %}

User: {% if username %} {{ slash_joiner() }}
    {{username}}
{% endif %}
{% if alias %} {{ slash_joiner() }}
    {{alias}}
{% endif %}
{% if nickname %} {{ slash_joiner() }}
    {{nickname}}
{% endif %}

# Output
# If all variables are defined
User: username / alias / nickname
# If only nickname is defined
User: nickname
# If only username and alias is defined
User: username / alias
# Etc, the joiner function avoids any unnecessary preceding slash because it doesn't print anything the first time its called

Listing 4-18.Jinja joiner function

Python 和过滤器操作

{% set %}。-{% set %}语句允许您在 Jinja 模板的上下文中定义变量。当您需要为 Django view 方法没有公开的值创建变量时，或者当一个变量与一个重量级操作相关联时，这很有用。下面是这个声明{% set drinkwithtax=drink.cost*1.07 %}的一个示例声明。在{% set %}语句中定义的变量的范围是从它的声明开始直到模板结束。{% set %}语句也可以定义内容块。例如，语句{% set advertisement %}<div class'banner'><img src=.....></div>{% endset %}创建变量advertisement，其内容包含在{% set %}和{% endset %}之间，以后可以在模板的其他部分重用(例如{{advertisement}})。内置的{% macro %}语句——在模板结构一节中描述——为内容块提供了更高级的重用功能。
{% do %}(该语句需要启用内置的 jinja2.ext.do 扩展；有关更多详细信息，请参见启用 Jinja 扩展一节)。-{% do %}语句是一个表达式求值器，其工作方式类似于{{ }}变量语法，只是它不产生输出。例如，要增加一个变量的值或添加一个新元素而不产生任何输出，可以使用{% do %}语句(例如，{ % do itemlist.append('Forgot to add this other item') %})。

Note

{% break %}和{% continue %}需要启用内置的 jinja2.ext.loopcontrols 扩展。请参阅本章倒数第二节，了解如何启用 Jinja 扩展。

{% with %}。-{% with %}语句类似于{% set %}语句；唯一的区别是{% with %}语句用{% endwith %}语句限制了变量的范围(例如，{% with myvar=1 %}...{% endwith %}中声明的任何元素...可以访问myvar变量)。在{% with %}和{% endwith %}语句中声明{% set %}语句来限制变量的范围也是有效的(例如{% with %}{% set myvar=1 %}...{% endwith %})。

Note

{% with %}需要启用内置的 jinja2.ext.with_ extension。请参阅本章倒数第二节，了解如何启用 Jinja 扩展。

{% filter %}。-{% filter %}语句用于将 Jinja 过滤器应用于模板部分。默认情况下，Jinja 过滤器单独应用于模板变量，但有时将 Jinja 过滤器应用于整个模板部分会很有帮助。例如，如果您声明了{% filter lower %}，那么lower过滤器将应用于该语句和{% endfilter %}语句之间的所有内容——注意lower过滤器语句将所有内容转换为小写；本章的下一个主要部分描述了 Jinja 的内置过滤器。
dict(功能)。-dict函数提供了一种不用文字定义字典的方法(例如，{'id':1}相当于dict(id=1))。

间距和特殊字符

默认情况下，Jinja 保持模板中定义的所有间距(例如制表符、空格、换行符)不变。图 4-1 展示了 Jinja 中模板片段的默认呈现。

图 4-1。

Default space rendering in Jinja template

在图 4-1 中可以看到，{% for %}和{% if %}语句本身的前后空格是按原样生成的。虽然这种间距是自然的，但它有利于使用处理大量数据的模板创建更紧凑的输出。附加在语句开头或结尾的减号-(例如{%- <statement> -%})告诉 Jinja 去掉它后面的新行。这在图 4-2 和图 4-3 中的例子中得到最好的说明。

图 4-3。

Space rendering in Jinja template with double -

图 4-2。

Space rendering in Jinja template with single -

如图 4-2 所示，关闭{% for %}语句前的-符号使 Jinja 在每次迭代后消除新行。在图 4-2 中的{% if %}语句中，-符号没有影响，因为没有与该语句相关的换行符。在图 4-3 中，你可以看到在{% endfor %}语句的开始处有一个额外的-符号，它让 Jinja 在每次迭代开始前消除换行符。在{% if %}语句也是图 4-3 的情况下，额外的-符号没有影响，因为没有与该语句相关联的换行符。

因为向每个 Jinja 语句添加-符号会变得令人厌烦，所以可以配置 Jinja，使其默认使用这种行为(即，就像添加了-)。要改变 Jinja 的默认间距行为，您可以使用两个 Jinja 环境参数:trim_blocks和lstrip_blocks，它们都默认为False。请注意，在 Django 中，您将 Jinja 环境参数设置为settings.py中的OPTIONS变量的一部分，如前面关于在 Django 中设置 Jinja 模板配置的部分所述。

图 4-4 展示了当trim_blocks设置为True时代码片段的渲染，而图 4-5 展示了当trim_blocks和lstrip_blocks都设置为True时代码片段的渲染。

图 4-5。

Space rendering in Jinja template with both trim_blocks and lstrip_blocks set to True

图 4-4。

Space rendering in Jinja template with trim_blocks

正如您在图 4-4 和 4-5 中看到的，通过改变trim_blocks和lstrip_blocks Jinja 环境变量产生的渲染与使用-符号开始和结束 Jinja 语句非常相似。值得一提的是，如果您将lstrip_blocks设置为True,并希望省略它在某些部分的行为，您可以通过在语句的开头或结尾添加加号+来做到这一点——就像您使用减号-来实现其相反的行为一样。

{% raw %}。-{% raw %}语句用于逐字输出任何 Jinja 保留字符，直到到达{% endraw %}语句。如果您想要呈现大块的 Jinja 模板代码，或者如果您有许多包含特殊 Jinja 模板字符(例如，{{，{%)的文本，那么{% raw %}语句是理想的。

Tip

您可以单独输出特殊的 Jinja 模板字符，方法是将它们作为硬编码字符串变量的一部分(例如，输出{{ use {{ '{{' }})而不是使用{% raw %}语句。

{% autoescape %}。-{% autoescape %}语句让您从模板部分转义 HTML 字符，有效地覆盖 Django 的 Jinja 默认自动转义行为。{% autoescape %}接受两个参数true或false中的一个。使用{% autoescape true %}时，该语句和{% endautoescape %}语句之间的所有模板内容都被 HTML 转义，使用{% autoescape false %}时，该语句和{% endautoescape %}语句之间没有模板内容被 HTML 转义。

Note

{% autoescape %}需要启用内置的 jinja2.ext.auto-escape 扩展。请参阅本章倒数第二节，了解如何启用 Jinja 扩展。

lipsum(功能)。-lipsum函数用于显示随机的拉丁文本，这对模板上的填充符很有用。调用lipsum函数有四个参数:lipsum(n=5, html=True, min=20, max=100)。其中n是要生成的段落数，如果未提供，默认n为5；html默认为True返回 HTML 或者你可以设置为False返回常规文本；而min和max代表每段随机词的最小和最大数量。要使用 lipsum 函数，您只需用它和输出定义一个变量来生成随机拉丁文本(例如，{% set latinblurb=lipsum() %}然后{{latinblurb}}输出随机拉丁文本)。

模板结构

{% block %}。-{% block %}语句用于定义可以在不同的 Jinja 模板上覆盖的页面部分。请参阅上一节关于创建可重用 Jinja 模板的内容，以获得该语句的详细示例。
{# #}。-{# #}语句用于包含 Jinja 模板上的注释。放置在{#和#}之间的任何内容都会被 Jinja 绕过，不会出现在最终呈现的网页中。
{% extends %}。-{% extends %}语句用于重用另一个 Jinja 模板的布局。请参阅上一节关于创建可重用 Jinja 模板的内容，以获得该语句的详细示例。
{% include %}。-{% include %}语句用于将一个 Jinja 模板嵌入到另一个 Jinja 模板中。注意，默认情况下，{% include %}语句可以访问当前的模板实例值(即它的上下文)。如果你想禁止访问模板的上下文，你可以使用{% import %}语句或者将关键字without context传递到{% include %}语句的末尾(例如{% from 'footer.html' without context %})。此外，{% include %}语句还接受ignore missing关键字，它告诉 Jinja 如果要包含的模板不存在，就忽略该语句。请参阅上一节关于创建可重用 Jinja 模板的内容，以获得该语句的详细示例。
{% macro %}。-{% macro %}语句是一个模板函数，用于输出内容。它非常适合重复的内容片段，在这里你定义一个{% macro %}语句，然后在任何模板上用不同的变量多次执行它——就像一个函数。请参阅上一节关于创建可重用 Jinja 模板的内容，以获得该语句的详细示例。还值得一提的是内置的{% set %}语句——在 Python 和过滤器操作一节中描述——为内容块提供了更简单的重用功能。
{% call %}。-{% call %}语句与{% macro %}语句结合使用，以引用{% macro %}语句中的caller()方法。如果您定义了一个带有caller()引用的{% macro %}语句作为其内容的一部分，那么您可以依靠{% call %}语句来调用{% macro %}，并用{% call %}语句的内容替换caller()方法。请参阅上一节关于创建可重用 Jinja 模板的内容，以获得该语句的详细示例。
{% import %}和{% from ... import %}。-{% import %}语句用于从其他模板中访问元素。与 Python 的标准导入类似，您也可以使用from和as关键字来限制或重命名导入到模板中的元素。注意，默认情况下，由于其缓存行为，{% import %}语句不能访问当前模板实例值(即其上下文)，它只能访问全局变量(如变量和宏)。如果你想访问一个模板的上下文，你可以使用{% include %}语句或者将关键字with context传递到{% import %}语句的末尾来禁用缓存并访问一个模板的上下文(例如{% from 'footer.html' with context %})。请参阅上一节关于创建可重用 Jinja 模板的内容，以获得该语句的详细示例。

Jinja 内置过滤器和测试(如 Django 过滤器)

Jinja 文档明确区分了过滤器和测试。唯一的区别是 Jinja 测试用于评估条件，而 Jinja 过滤器用于格式化或转换值。在 Django 中没有这样的命名差异，在 Django 中等价的 Jinja 测试被简单地称为 Django 过滤器。

将 Jinja 过滤器应用于模板变量的语法是竖线字符|，在 Unix 环境中也称为“管道”(例如{{variable|filter}})。值得一提的是，您可以对同一个变量应用多个过滤器(例如，{{variable|filter|filter}})。应用 Jinja 测试的语法使用is关键字和常规条件来评估测试的有效性(例如{% if variable is divisibleby 10 %}do something{% endif %})。

在接下来的部分中，我将添加引用(Test ),以表明它指的是 Jinja 测试与 Jinja 滤波器。我还将把每个 Django 内置过滤器和测试分类到功能部分，这样它们更容易识别。我将为适用于大多数场景的过滤器和测试定义最广泛的类别“字符串、列表、字典、数字和对象”，然后为每种数据类型定义更专业的部分，包括“字符串和列表”、“字典和对象”、字符串、数字、空格和特殊字符、开发和测试以及 URL。

字符串、列表、词典、数字和对象

default或d。-default或d过滤器用于在变量未定义或为假(即不存在或为空)时指定默认值。例如，只有当变量未定义时，过滤语句{{variable|default("no value")}}才输出no value；否则它输出变量值。此外，如果您想要为评估为 false、无或是空字符串的变量提供默认值，您必须添加true作为第二个过滤器参数(例如，如果变量未定义、为 false、为无或是空字符串，则{{variable|default("no value",true)}}输出no value)。
defined(测试)。-defined测试用于检查变量是否已定义，如果变量已定义，则该测试返回 true。清单 4-19 展示了一个defined测试的例子。
```
{% if variable is defined %}
    value of variable: {{ variable }}
{% else %}
    variable is not defined
{% endif %}
Listing 4-19.Jinja defined test
```
none(测试)。-none测试用于检查变量是否为 none，如果变量为 None，该测试返回 true。
length或count。-length过滤器用于获取值的长度。例如，如果变量包含latte，过滤语句{{variable|length}}输出 5。对于包含['a','e','i']的列表变量，过滤语句{{variable|length}}输出 3。
equalto(测试)。-equalto测试检查一个对象是否与另一个对象具有相同的值。比如说{% if coffee.price is equalto 1.99 %} coffee prices equals 1.99 {% endif %}。这就像==一样工作，但当与其他过滤器如selectattr一起使用时更有帮助(例如{{ users|selectattr("email", "equalto", "webmaster@coffeehouse.com") }}，让用户收到电子邮件webmaster@coffeehouse.com)。
string(测试)。-string测试检查变量是否是一个字符串(例如，{% if variable is string %}Yes, the variable is a string!{% endif %})。
number(测试)。-number如果变量是一个数字，测试返回 true。
iterable(测试)。-iterable测试检查是否有可能迭代一个对象。
sequence(测试)。-sequence测试检查对象是否是一个序列(如发电机)。
mapping(测试)。-mapping测试检查对象是否是映射(例如，字典)。
callable(测试)。-callable 测试验证对象是否可调用。在 Python 中，带有 call 方法的函数、类和对象实例是可调用的。
sameas(测试)。-sameas测试验证一个对象是否指向与另一个对象相同的内存地址。

字符串和列表

reverse。-反向过滤器用于获取值的反向表示。例如，如果一个变量包含latte，过滤语句{{variable|reverse}}生成ettal。
first。-first过滤器返回列表或字符串中的第一项。例如，对于包含['a','e','i','o','u']的列表变量，过滤语句{{variable|first}}输出a。
join。-join过滤器用一个字符串连接一个列表。join滤镜的工作方式就像 Python 的str.join(list)一样。例如，对于包含['a','e','i','o','u']的列表变量，过滤语句{{variable|join("--)}}输出a--e--i--o--u。join过滤器也支持连接对象的某些属性(例如{{ users|join(', ', attribute='username') }}).
last。-last过滤器返回列表或字符串中的最后一项。例如，对于包含['a','e','i','o','u']的列表变量，过滤语句{{variable|last}}输出u。
map。-map过滤器允许你应用过滤器或者查找属性，就像标准的 Python map方法一样。例如，如果您有用户列表，但只对输出用户名列表感兴趣，那么地图就很有帮助(例如{{ users|map(attribute='username')|join(', ') }})。此外，还可以通过传递过滤器的名称和参数来调用过滤器(例如，{{ titles|map('lower')|join(', ') }}将lower过滤器应用于titles中的所有元素，然后连接由逗号分隔的项目)。
random。-random过滤器返回一个列表中的随机项目。例如，对于包含['a','e','i','o','u']的列表变量，过滤语句{{variable|random}}可以输出a、e、i、o或u。
reject。-reject过滤器移除通过特定测试的元素--参见本章中标有(测试)的小节中的项目符号，了解可接受的值。例如，对于一个包含[1,2,3,4,5]的列表变量，带有这个过滤器{% for var in variable|reject("odd") %}{{var}}{% endfor %}的循环语句——其中odd是 Jinja 测试——拒绝奇数元素，因此它的输出是2和4。
select。-select过滤器选择通过特定测试的元素-参见本章中标有(测试)的章节中的项目符号，了解可接受的值。例如，对于一个包含[1,2,3,4,5]的列表变量，带有这个过滤器{% for var in variable|select("odd") %}{{var}}{% endfor %}的循环语句——其中odd是 Jinja 测试——选择奇数的元素，因此它的输出是1、3和5。
slice。-slice过滤器返回列表的一部分。例如，对于包含["Capuccino"]的变量，过滤语句{% for var in variable|slice(4) %}{{var}}{% endfor %}输出['C', 'a', 'p'],['u', 'c'],['c', 'i'], ['n', 'o']。可以使用fill_with作为第二个参数——默认为 None——所以所有段都包含相同数量的元素，并填充给定值。比如{% for var in variable|slice(4,'FILLER') %}{{var}}{% endfor %}输出:['C', 'a', 'p'],['u', 'c','FILLER'],['c', 'i','FILLER'], ['n', 'o','FILLER']。
batch。-batch过滤器返回一批列表。例如，包含["Capuccino"]的变量过滤语句{% for var in variable|batch(4) %}{{var}}{% endfor %}输出['C', 'a', 'p', 'u'],['c', 'c', 'i', 'n'],['o']。可以使用fill_with作为第二个参数——默认为 None——所以所有段都包含相同数量的元素，并填充给定值。比如{% for var in variable|slice(4,'FILLER') %}{{var}}{% endfor %}输出:['C', 'a', 'p', 'u'],['c', 'c', 'i', 'n'],['o','FILLER','FILLER','FILLER']。
sort。-sort过滤器按升序对元素进行排序。例如，如果一个变量包含['e','u','a','i','o']，语句{{variable|sort}}输出['a','e','i','o','u']。可以通过将第一个参数设置为 true 来指示降序(例如，{{variable|sort(true)}}输出['u','o','i','e','a'])。此外，如果一个列表是由字符串组成的，那么第二个参数可以用来表示区分大小写——默认情况下是禁用的——以执行排序操作(例如，{{variable|sort(true,true)}})。最后，如果一个列表是由对象组成的，也可以在给定的属性上指定排序操作(例如，variable|sort(attribute='date')根据date属性对元素进行排序)。

字典和对象

dictsort。-dictsort过滤器按关键字对字典排序，不区分大小写。例如，如果一个变量包含{'name':'Downtown','city':'San Diego','state':'CA'}过滤器{% with newdict=variable|dictsort %}，那么newdict变量被赋予字典{'city':'San Diego','name':'Downtown','state':'CA'}。此外，dictsort可以接受两个参数，区分大小写和按键/值排序。默认行为是不区分大小写的按键排序(如variable|dictsort)，使用区分大小写的按键排序使用 true 作为第一个参数(如variable|dictsort(true))，使用按值排序是值作为第二个参数(如variable|dictsort(false,'value')执行不区分大小写的按值排序)。
attr。-attr过滤器返回一个对象的属性(例如，{{coffeehouse.city}}输出coffeehouse对象的city属性值)。注意attr过滤器只试图查找一个属性，而不是一个条目(例如，如果coffeehouse是一个字典而city是一个关键条目，那么它就不会被找到)。或者，您可以只使用标准 Python 语法variable.name——它首先尝试在variable上定位一个名为name的属性，然后返回variable上的name项，或者如果没有任何内容匹配一个未定义的对象——或者variable['name']——它首先尝试在variable上定位name项，然后返回一个名为variable的属性，或者如果没有任何内容匹配一个未定义的对象。
rejectattr。—rejectattr过滤器删除不包含属性的对象或某个属性未通过测试的对象——有关可接受的值，请参阅本章中标有(测试)一节中的项目符号。例如，{% for ch in coffeehouses|rejectattr("closedon") %}为没有closedon属性的coffeehouse对象生成一个循环，或者{% for u in users|rejectattr("email", "none") %}为没有email None 的user对象生成一个循环——注意第二个参数none代表测试。
selectattr。-selectattr过滤器选择包含某一属性的对象或某一属性通过测试的对象——有关可接受的值，请参阅本章中标有(测试)一节中的项目符号。例如，{% for u in users|selectattr("superuser") %}为具有superuser属性的user对象生成一个循环，或者{% for u in users|selectattr("email", "none") %}为具有email None 属性的user对象生成一个循环——注意第二个参数none代表测试。

groupby。-groupby过滤器用于根据公共属性将字典或对象列表的内容重新排列到不同的组对象序列中。清单 4-20 展示了一个groupby过滤器的例子。

# Dictionary definition
stores = [
    {'name': 'Downtown', 'street': '385 Main Street', 'city': 'San Diego'},
    {'name': 'Uptown', 'street': '231 Highland Avenue', 'city': 'San Diego'},
    {'name': 'Midtown', 'street': '85 Balboa Street', 'city': 'San Diego'},
    {'name': 'Downtown', 'street': '639 Spring Street', 'city': 'Los Angeles'},
    {'name': 'Midtown', 'street': '1407 Broadway Street', 'city': 'Los Angeles'},
    {'name': 'Downton', 'street': '50 1st Street', 'city': 'San Francisco'},
]

<ul>
{% for group in stores|groupby('city') %}
    <li>{{ group.grouper }}
    <ul>
        {% for item in group.list %}
          <li>{{ item.name }}: {{ item.street }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

# Output
Los Angeles
    Downtown: 639 Spring Street
    Midtown: 1407 Broadway Street
San Diego
    Downtown : 385 Main Street
    Uptown : 231 Highland Avenue
    Midtown : 85 Balboa Street
San Francisco
    Downtown: 50 1st Street

# Alternate shortcut syntax, produces same output
<ul>
{% for grouper, list in stores|groupby('city') %}
    <li>{{ grouper }}
    <ul>
        {% for item in list %}
          <li>{{ item.name }}: {{ item.street }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Listing 4-20.Jinja groupby filter

tojson。-tojson过滤器将数据结构输出到 JavaScript 对象符号(JSON)(例如{{variable|tojson}})。tojson过滤器接受indent参数——该参数被设置为None—以生成给定数量空格的漂亮输出(例如，{{variable|tojson(indent=2)}}生成缩进两个空格的输出)。

Tip

您可以通过 Jinja 策略全局设置 tojson 过滤器的选项，如本章最后一节所述。

用线串

capitalize。-capitalize过滤器将字符串变量的第一个字符大写。例如，如果一个变量包含hello world，过滤语句{{variable|capitalize}}输出Hello world。
list。-list过滤器用于返回字符列表。例如，如果一个变量包含latte，那么过滤语句{{variable|list}}将生成['l','a','t','t','e']。
lower。-lower过滤器将字符串变量的所有值转换成小写。例如，如果变量包含Hello World，过滤语句{{variable|lower}}输出hello world。
lower(测试)。-lower如果变量是小写的，测试返回 true。例如，如果variable是小写的，则{% if variable is lower %}Yes, the variable is lowercase!{% endif %}输出该语句。
replace。-replace过滤器就像 Python 的标准replace字符串一样工作。第一个参数是应该被替换的子字符串，第二个参数是替换字符串。如果给定了可选的第三个参数数量，则只替换出现的数量。例如{{ "Django 1.8"|replace("1.8", "1.9") }}输出Django 1.9，而{{"oooh Django!"|replace("o", "",2) }}输出oh Django!。
string。-string过滤器将一个字符串转换成 unicode，如果它还不是。
title。-title过滤器将字符串变量的所有第一个字符值转换为大写。例如，如果一个变量包含hello world，过滤语句{{variable|title}}输出Hello World。
upper。-upper过滤器将字符串变量的所有值转换为大写。例如，如果一个变量包含Hello World，过滤语句{{variable|upper}}输出HELLO WORLD。
upper(测试)。-upper测试返回 true，如果变量是大写的。例如，如果variable是大写的，则{% if variable is upper %}Yes, the variable is uppercase!{% endif %}输出该语句。
wordcount。-wordcount过滤器对字符串中的单词进行计数。例如，如果变量包含Coffeehouse started as a small store，过滤语句{{variable|wordcount}}输出 6。

民数记

abs。-abs返回数字自变量的绝对值。例如，如果一个变量包含-5，过滤语句{{variable|abs}}输出5。
filesizeformat。-filesizeformat过滤器将多个字节转换成友好的文件大小字符串。例如，如果一个变量包含 250，过滤语句{{variable|filesizeformat}}输出 250 字节，如果它包含 2048，输出是 2 kB，如果它包含 2000000000，输出是 2.0 GB。默认情况下，使用十进制前缀(例如 Giga、Mega、Kilo)，如果您传递一个带有 true 的附加布尔参数(例如{{variable|filesizeformat(true)}}，则使用二进制前缀(例如 Gibi、Mebi、Kibi)。
float。-float过滤器将值转换成浮点数。如果转换不成功，它将返回 0.0 或自定义值参数(例如，如果variable不能转换为浮点数，variable|float("It didn't work")将返回"It didn't work")。
int。-int过滤器将值转换成整数。如果转换不成功，它返回 0 或一个自定义值作为过滤器的第一个参数——就像float过滤器一样。您还可以用第二个 filter 参数覆盖默认的基数 10，该参数分别为基数 2、8 和 16 处理带有前缀 0b、0o 和 0x 的输入(例如，{{'0b001111'|int(0,2)}}基数 2 的数字输出 15。
round。-round过滤器将数字舍入到给定的精度，其中第一个参数是精度——默认为 0——第二个参数是舍入方法——默认为“common”向上或向下舍入。例如，{{ 33.55|round }}假设“common”舍入到输出34.0。除了']'之外，还可以使用'ceil'始终向上舍入或'floor'始终向下舍入(例如，{{ 33.55|round(1,'floor') }}输出33.5)。请注意，即使舍入到默认的 0 精度，也会返回一个浮点数。如果您需要一个整数，您可以应用int过滤器(例如{{ 33.55|round|int }}输出34)。
sum。-sum过滤器返回一系列数字的和，加上 start 参数提供的值，缺省值为 0。此外，还可以对一系列对象的某些属性求和{{ items|sum(attribute='price') }}。
divisibleby(测试)。-divisibleby测试检查变量是否能被给定的数整除。例如，如果一个变量包含 20，过滤语句{% if variable is divisibleby(5) %}Variable is divisible by 5!{% endif %}输出条件语句。
even(测试)。-even测试检查数字是否为偶数。
odd(测试)。-odd测试检查数字是否为奇数。

间距和特殊字符

center。-center过滤器中心对齐一个值并用额外的空白字符填充它，直到它到达给定的字符参数。例如，如果变量包含mocha，过滤语句{{variable|center(width="15")}}输出" mocha "。
escape或e。-escape或e过滤器从一个值中转义 HTML 字符。具体用escape滤镜:<转换为<,>转换为>，'(单引号)转换为'，"(双引号)转换为"，&转换为&amp。
escaped(测试)。-转义测试检查值是否被转义。
forceescape。-forceescape过滤器像转义过滤器一样对值中的 HTML 字符进行转义。两个过滤器的区别在于forceescape过滤器被立即应用，并返回一个新的转义字符串。在极少数情况下，当您需要多次转义或想要对转义结果应用其他过滤器时，这很有用。通常，您会使用escape滤镜。
format。-format过滤器用于将 Python 字符串格式应用于变量。例如，语句{{ "%s and %s"|format("Python", "Django!") }}输出Python and Django!。
indent。-indent过滤器用于输出一个字符串，除了缩进四个空格的第一行。可以用额外的过滤器参数改变空格数和首行缩进(例如，{{ textvariable|indent(2, true) }}``2表示两个空格，true表示首行缩进)。
safe。-safe过滤器将一个字符串标记为不需要进一步的 HTML 转义。当此过滤器与没有自动转义的环境一起使用时，它不起作用。
striptags。-striptags过滤器从一个值中删除所有 HTML 标签。例如，如果一个变量包含<b>Coffee</b>house, the <i>best</i> <span>drinks</span>，过滤语句{{variable|striptags}}输出Coffeehouse, the best drinks。
trim。-trim过滤器用于去除开头和结尾的空白，就像 Python 的字符串strip()方法一样。
truncate。-truncate过滤器将字符串截断成给定的字符数——默认为 255 个字符——并附加一个省略号序列。例如，如果变量包含Coffeehouse started as a small store，过滤语句{{variable|truncate(20)}}输出Coffeehouse ...，一直到第 20 个字符，然后丢弃最后一个完整的单词，最后添加省略号。您可以添加true作为第二个参数，这样字符串就会被精确地切割(例如，{{variable|truncate(20,true)}}输出Coffeehouse start...包括省略号)。可以提供不同于传递第二个参数的省略号的符号(例如，{{variable|truncate(20,true,"!!!")}}将输出！！！而不是椭圆形)。最后，truncate过滤器接受第四个参数leeway来指定字符的字符串容差——默认为 5——以避免截断字符串(例如，这可以避免截断少于 5 个字符的单词)。

Tip

如本章最后一节所述，您可以通过 Jinja 策略全局设置截断过滤器的偏航值。

wordwrap。-wordwrap过滤器在给定的字符行长度参数处换行。默认情况下，换行发生在 79 个字符之后，这可以通过提供带有字符数的第一个参数来覆盖。如果将第二个参数设置为 false，Jinja 不会拆分超过换行字符长度的单词。此外，换行生成一个在环境中定义的换行符——通常是\n 字符——但是这可以通过指定wrapstring关键字参数来改变(例如，{{variable|wordwrap(40,true,'-')使用连字符作为换行字符)。清单 4-21 展示了一个wordwrap过滤器的例子。
```
# Variable definition
Coffeehouse started as a small store

# Template definition with wordwrap filter for every 12 characters
{{variable|wordwrap(12)}}

# Output
Coffeehouse
started as a
small store

Listing 4-21.Jinja wordwrap filter
```

xmlattr。-xmlattr过滤器用于根据字典或对象中的项目创建 SGML/XML 属性字符串。一旦创建了包含属性名和引用值的字典结构，就可以通过xmlattr过滤器来生成属性字符串。默认情况下，所有既不是 none 也不是 undefined 的值都会被自动转义，但是您可以通过将 false 作为第一个筛选器参数来覆盖这种行为。清单 4-22 展示了一个xmlattr过滤器的例子。

# Variable definition
{% set stores = [
    {'id':123,'name': 'Downtown', 'street': '385 Main Street', 'city': 'San Diego'},
    {'id':243,'name': 'Uptown', 'street': '231 Highland Avenue', 'city': 'San Diego'},
    {'id':357,'name': 'Midtown', 'street': '85 Balboa Street', 'city': 'San Diego'},
    {'id':478,'name': 'Downtown', 'street': '639 Spring Street', 'city': 'Los Angeles'},
    {'id':529,'name': 'Midtown', 'street': '1407 Broadway Street', 'city': 'Los Angeles'},
    {'id':653,'name': 'Downton', 'street': '50 1st Street', 'city': 'San Francisco'},
] %}

# Template definition
<ul>
{% for store in stores %}
  <li {{ {'id':'%d'|format(store.id),'class':'%s'|format(store.city|lower|replace(' ','-')) }|xmlattr }}> {{store.city}} {{store.name}}</li>
{% endfor %}
</ul>

# Output
<ul>
  <li id="123" class="san-diego"> San Diego Downtown</li>
  <li id="243" class="san-diego"> San Diego Uptown</li>
  <li id="357" class="san-diego"> San Diego Midtown</li>
  <li id="478" class="los-angeles"> Los Angeles Downtown</li>
  <li id="529" class="los-angeles"> Los Angeles Midtown</li>
  <li id="653" class="san-francisco"> San Francisco Downton</li>
</ul>

Listing 4-22.Django xmlattr filter

开发和测试

pprint。-pprint过滤器是 Python 的pprint.pprint()的包装器。pprint过滤器在开发和测试期间很有用，因为它输出对象的格式化表示。默认情况下，pprint过滤器并不冗长，但是您可以通过向其传递 true 参数(例如，{{variable|pprint(true)}})来使其冗长。

资源定位符

urlencode。urlencode 筛选器转义用于 URL 的值。例如，如果变量包含 http://localhost/drinks？type = cold & size = large the filter 语句{{variable|urlencode}}输出 http % 3A//localhost/drinks % 3f type % 3d cold % 26 size % 3d large。
urlize。urlize 过滤器将文本 URL 转换为可点击的 HTML 链接。您可以向过滤器传递一个额外的整数来缩短可见的 url(例如，{{ variable|urlize(40)}}链接被缩短为 40 个字符加一个省略号)。还可以添加第二个参数作为布尔值，使 URL“no follow”(例如，{{ variable|urlize(40，true)}}链接被缩短为 40 个字符，并用 rel="nofollow "定义)。最后，还可以添加 target 参数来定义链接目标(例如，{{ variable|urlize(40，target="_blank")}}链接被缩短为 40 个字符，并在新窗口中打开)。

Tip

您可以通过 Jinja 策略为 urlize 过滤器全局设置 rel 和 target 值，如本章最后一节所述。

Jinja 中的自定义过滤器和测试

定制的 Jinja 过滤器和测试很容易创建，因为它们由常规的 Python 方法支持。对于定制的 Jinja 过滤器，方法应该返回期望的格式化值，对于 Jinja 测试，方法应该包含返回布尔值的逻辑。

结构

自定义 Jinja 过滤器或测试的支持方法具有对应于变量本身的参数——作为第一个参数——以及由过滤器或测试作为其他方法参数传递的任何剩余值(例如，variable|mycustomfilter("<div>")由类似 def mycustomfilter(variable,htmltag="<p>"):的方法支持——注意，htmltag参数具有默认值，以防过滤器没有用类似variable|mycustomfilter的语句指定该值)。

在创建支持 Python 方法时，您需要考虑的唯一 Jinja 特定逻辑与 Jinja 过滤器中的字符安全有关。默认情况下，如果 Jinja 过滤器的支持方法返回一个字符串，它被认为是不安全的，因此会被转义(例如，如果过滤器的结果返回<div>，Jinja 会将结果呈现为<div>)——这与自定义 Django 过滤器的行为相同。

为了将结果标记为安全的字符串，Jinja 过滤器使用的后备 Python 方法必须返回一个jinja2.Markup类型，这个过程在清单 4-23 中的一个示例过滤器中进行了说明。清单 4-23 展示了定制 Jinja 过滤器和测试的各种支持方法。

import jinja2

def customcoffee(value,arg="muted"):
    return jinja2.Markup('%s' % (arg,value))

import math

def squarerootintext(value):
    return "The square root of %s is %s" % (value,math.sqrt(value))

def startswithvowel(value):
    if value.lower().startswith(("a", "e", "i", "o","u")):
        return True
    else:
        return False

Listing 4-23.Backing Python methods for Jinja custom filters and tests.

清单 4-23 中的第一个方法返回包装在 HTML <span>标签中的value参数，并附加一个带有arg参数的 CSS 类——注意，在没有提供值的情况下，方法定义中的arg参数默认为muted值。还要注意的是，customcoffee方法返回了一个jinja2.Markup类型；这样做是为了让 Jinja 将输出呈现为安全字符串，并将<span>标签解释为 HTML。

清单 4-23 中的第二个方法计算给定值的平方根并返回标准字符串"The square root of %s is %s"，其中第一个%s表示传入的value，第二个%s表示计算的平方根。清单 4-23 中的第三个方法采用value参数，将其转换为小写，并检查value是否以元音开头；如果是，则返回布尔值 True，否则返回布尔值 False。

安装和进入

一旦您为定制的 Jinja 过滤器和测试创建了支持方法，您需要在 Jinja 的环境配置中将它们声明为过滤器和/或测试变量的一部分，这将在下一节中描述。注意，这里假设清单 4-23 中的支持方法放在目录路径coffeehouse.jinja下名为 filters 的文件/模块中。

为了更好地展示包含定制 Jinja 扩展的文件filters.py的位置，清单 4-24 展示了一个包含额外 Django 项目文件的目录结构以供参考。

+---+-<PROJECT_DIR_coffeehouse>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
    |
    +-jinja-+
            +-__init__.py
            +-env.py
            +-filters.py
Listing 4-24.Directory structure and location of custom Jinja filters and tests

Jinja 过滤器和测试是作为 Jinja 环境配置的一部分设置的。清单 4-25 展示了一个定制的 Jinja 环境定义，它通过名为 filters 和 tests 的变量来设置一系列定制的 Jinja 过滤器。

from jinja2.environment import Environment
from coffeehouse.jinja.filters import customcoffee, squarerootintext, startswithvowel

class JinjaEnvironment(Environment):
    def __init__(self,**kwargs):
        super(JinjaEnvironment, self).__init__(**kwargs)
        self.filters['customcoffee'] = customcoffee
        self.filters['squarerootintext'] = squarerootintext
        self.filters['startswithvowel'] = startswithvowel
        self.tests['startswithvowel'] = startswithvowel

Listing 4-25.Custom Jinja environment with custom filters and tests

正如您在清单 4-25 中看到的，每个支持 Python 方法首先被导入到定制的 Jinja 环境中。接下来，要注册定制的 Jinja 过滤器，你需要访问self.filters并给它分配一个变量键名——对应于过滤器名称——以及过滤器的支持方法。为了注册定制的 Jinja 测试，您可以访问self.tests,并为它分配一个变量键名——对应于测试名——以及测试的支持方法。

清单 4-25 的一个有趣的方面是将startswithvowel注册为过滤器和测试，这意味着相同的支持方法——返回 True 或 False——可以用于这两种情况。这种双重注册允许startswithvowel使用管道(即作为过滤器{{variable|startwithvowel}}逐字输出真或假)或条件关键字is(即作为测试{% if variable is startswithvowel %}variable starts with vowel{% endif %})。

一旦定制的 Jinja 环境被创建，你需要在settings.py的OPTIONS变量中设置它作为 Django 配置的一部分，如清单 4-26 所示。

TEMPLATES = [
    {
        'BACKEND':'django.template.backends.jinja2.Jinja2',
        'DIRS': ['%s/templates/'% (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'environment': 'coffeehouse.jinja.env.JinjaEnvironment'
            }
        },
    ]
Listing 4-26.Configure custom Jinja environment in Django setttings.py

在这种情况下，您可以在清单 4-26 中看到环境值对应于coffeehouse.jinja.env.JinjaEnvironment，其中JinjaEnvironment是类入清单 4-25 - env是文件/模块名，coffeehouse.jinja是目录路径。为了更好地说明env.py文件的位置，请看一下清单 4-24 中的目录结构。

一旦您完成了最后的注册步骤，所有声明的自定义 Jinja 过滤器和测试在所有 Jinja 模板上都变得可用，就像上一节中描述的常规内置过滤器和标签一样。

Note

清单 4-25 中用于自定义 Jinja 过滤器和测试的自定义 Jinja 环境与清单 4-11 中用于声明 Jinja 全局变量的技术相同。

Jinja 扩展

Jinja 扩展对于 Jinja 模板来说就像一个库对于编程语言来说一样:包含在特定格式中的一组可重用的特性，从而不必不断地“重新发明轮子”。

Jinja 本身包括各种需要启用才能使用的扩展。此外，还有各种第三方的 Jinja 扩展，在某些情况下会对你有所帮助(例如，模仿 Django 模板标签的 Jinja 语句)。表 4-2 包含一个扩展列表，包括用于启用它们的技术名称。

正如您在表 4-2 中看到的，每个扩展提供的功能各不相同，如果您在互联网上搜索“Jinja2 扩展”，您一定会找到更多选项，可以节省您的时间并在各方面开展工作。

表 4-2。

Jinja extensions with description and technical name

| 扩展功能 | 描述 | 技术名称 | | --- | --- | --- | | {% break %}和{% continue %}语句 | 提供在模板循环中中断和继续的能力，就像标准的中断和继续 Python 关键字一样。 | jinja2.ext.loopcontrols | | {% do %}语句 | 提供在不产生输出的情况下计算表达式的能力。 | jinja2.ext.do | | {% with %}语句 | 提供定义变量和限制变量范围的能力。 | jinja2.ext.with_ | | {% autoescape %}语句 | 提供启用/禁用 HTML 字符从模板部分转义的功能。 | 金贾 2 号车 | | {% csrf_token %}、{% trans %}、{% blocktrans %}、{% static %}和{% url %}语句 | 提供了使用同名 Django 标签提供的等效功能的能力。 | * jdj _ tags . extensions . django compat(对于所有标记)请参阅扩展文档以了解更详细的语句导入名称。 |

All extensions with the exception of jdj_tags.extensions.DjangoCompat are part of Jinja itself, so they require no additional installation. To install jdj_tags.extensions.DjangoCompat use pip install jinja2-django-tags.

要创建一个定制的 Jinja 扩展，你需要重用 Jinja 的jinja2.ext.Extension类提供的功能，并使用 Jinja 的 API 来创建你所追求的定制逻辑。一旦您创建了一个定制的 Jinja 扩展并将其添加到您的 Django 项目中，您还必须使用settings.py中的OPTIONS变量的extensions键来启用它。

启用 Jinja 扩展

Jinja 扩展是作为 Jinja 环境配置的一部分设置的，在 Django 中，它是在settings.py的OPTIONS变量中配置的，如前一节在 Django 中配置 Jinja 模板所述。清单 4-27 展示了一个支持一系列 Jinja 扩展的 Django 配置示例。

TEMPLATES = [
    {
        'BACKEND':'django.template.backends.jinja2.Jinja2',
        'DIRS': ['%s/templates/'% (PROJECT_DIR),],
        'APP_DIRS': True,
        'OPTIONS': {
            'extensions': [
                'jinja2.ext.loopcontrols',
                'jdj_tags.extensions.DjangoCompat',
                'coffeehouse.jinja.extensions.DjangoNow',
                ],
        }
   }
]
Listing 4-27.Jinja extension configuration

in Django

正如你在清单 4-27 中看到的，我们使用了 Jinja 扩展的名称——如表 4-2 中所描述的——并将其添加到一个列表中，该列表被分配给OPTIONS变量的extensions键，该变量本身是 Jinja 在settings.py中的TEMPLATES Django 配置的一部分。注意清单 4-27 中的第三个扩展coffeehouse.jinja.extensions.DjangoNow是一个自定义的 Jinja 扩展，我将在本章的下一节也是最后一节创建它。

这是在所有 Jinja 模板上启用 Jinja 扩展所必需的。现在您已经知道了如何启用 Jinja 扩展，下一节将探索如何创建定制的 Jinja 扩展。

创建 Jinja 扩展

Jinja 有自己的扩展 API，它被完整地记录在 ⁷ 中，可以处理所有你可能需要扩展的情况。我不会尝试使用 API 的所有功能，因为在一个例子中几乎不可能做到这一点；相反，我将专注于创建一个实用的扩展，并在这个过程中演示定制 Jinja 扩展的布局和部署过程。

在 Django 模板中，当您想要输出当前日期或时间时，有一个名为{% now %}的标签就是为了这个目的；Jinja 没有这样的声明，所以我将创建一个 Jinja 扩展来模拟与 Django 模板{% now %}标签相同的行为。Jinja {% now %}语句的功能就像 Django 模板版本一样，接受一个格式字符串，也可以使用as关键字定义一个带有值的变量。

清单 4-28 展示了生成 Jinja {% now %}语句的定制 Jinja 扩展的源代码。

from jinja2 import lexer, nodes
from jinja2.ext import Extension
from django.utils import timezone
from django.template.defaultfilters import date
from django.conf import settings
from datetime import datetime

class DjangoNow(Extension):
    tags = set(['now'])

    def _now(self, date_format):
        tzinfo = timezone.get_current_timezone() if settings.USE_TZ else None
        formatted = date(datetime.now(tz=tzinfo),date_format)
        return formatted

    def parse(self, parser):
        lineno = next(parser.stream).lineno
        token = parser.stream.expect(lexer.TOKEN_STRING)
        date_format = nodes.Const(token.value)
        call = self.call_method('_now', [date_format], lineno=lineno)
        token = parser.stream.current
        if token.test('name:as'):
            next(parser.stream)
            as_var = parser.stream.expect(lexer.TOKEN_NAME)
            as_var = nodes.Name(as_var.value, 'store', lineno=as_var.lineno)
            return nodes.Assign(as_var, call, lineno=lineno)
        else:
            return nodes.Output([call], lineno=lineno)

Listing 4-28.Jinja custom extension for Jinja {% now %} statement

在清单 4-28 中的各种导入语句之后，您可以看到我们创建了从jinja2.ext.Extension类继承其行为的DjangoNow类，后者是 Jinja 的一部分，用于所有定制扩展。接下来，您可以看到我们用set(['now'])值定义了 tags 字段，这是设置语句/标记名所必需的。如果您希望自定义语句/标签被称为{% mytimer %}，那么您应该声明tags = set(['mytimer'])。

接下来在清单 4-28 中你可以看到_now和parse方法。_now方法执行实际的当前日期或时间计算，并在settings.py中检查 Django 项目的时区配置——这个过程就像 Django 的{% now %}标记。parse方法表示执行定制{% now %}语句/标签的入口点，在这里它使用 Jinja 扩展 API 来分析输入，并根据{% now %}声明(例如{% now "F jS o" %}、{% now "F jS o" as today %})执行_now方法并返回结果。

一旦创建了定制的 Jinja 扩展，就需要在 Jinja 的环境配置中将它声明为extensions变量的一部分，如清单 4-27 所示。

为了更好地展示包含定制 Jinja 扩展的文件extensions.py的位置，清单 4-29 展示了一个包含额外 Django 项目文件的目录结构以供参考。

+---+-<PROJECT_DIR_coffeehouse>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
    |
    +-jinja-+
            +-__init__.py
            +-extensions.py
Listing 4-29.Directory structure and location of custom Jinja extension

注意，基于清单 4-27 - coffeehouse.jinja.extensions.DjangoNow中导入自定义 Jinja 扩展的语句，假设清单 4-28 中的DjangoNow类被放置在coffeehouse.jinja目录路径下名为extensions.py的文件/模块中。

金贾政策

Jinja 策略用于设置 Jinja 内置过滤器和其他模板构造的全局行为。Jinja 策略是在 Jinja 环境中设置的——就像清单 4-11 中的 Jinja globals 或清单 4-25 中的自定义 Jinja 过滤器和测试一样。

例如，您可以使用 Jinja 策略来改变默认情况下json或urlize内置过滤器的运行方式。清单 4-30 展示了一个定制的 Jinja 环境，它改变了 Jinja 内置的truncate过滤器，并将leeway选项设置为0。

from jinja2.environment import Environment
from coffeehouse.jinja.filters import customcoffee, squarerootintext, startswithvowel

class JinjaEnvironment(Environment):
    def __init__(self,**kwargs):
        super(JinjaEnvironment, self).__init__(**kwargs)
        self.policies['truncate.leeway'] = 0

Listing 4-30.Custom Jinja environment with policies

正如您在清单 4-30 中看到的，要注册 Jinja 策略，您需要访问self.policies，并为其分配策略键名⁸——在本例中对应于truncate.leeway——以及策略值——在本例中对应于0。通过设置清单 4-30 中的 Jinja 策略，在 Jinja 模板中使用truncate过滤器时，leeway将被设置为0，而不是默认的5。

Footnotes 1

http://jinja.pocoo.org/

https://www.python.org/dev/peps/pep-0525/

http://jinja.pocoo.org/docs/dev/api/#jinja2.Environment

http://jinja.pocoo.org/docs/2.9/api/#bytecode-cache

http://jinja.pocoo.org/docs/2.9/api/#loaders

http://jinja.pocoo.org/docs/dev/api/#jinja2.Environment

http://jinja.pocoo.org/docs/2.9/extensions/

http://jinja.pocoo.org/docs/2.9/api/#policies

五、Django 应用管理

像所有现代应用开发框架一样，Django 要求您最终管理任务来支持项目的核心操作。这可以从有效地设置 Django 应用以在现实世界中运行，到管理应用的静态资源(例如 CSS、JavaScript、图像文件)。

此外，其他例行应用管理任务可以包括以下内容:建立日志记录策略以实施问题检测，为应用用户和/或管理员设置电子邮件传递，以及调试任务以检查复杂操作的结果。在这一章中，您将了解这些以及其他与 Django 应用管理相关的常见主题。

Django settings.py 用于真实世界

settings. py是所有 Django 项目的中心配置。在前面的章节中，您已经使用了这个文件中的一系列变量来配置 Django 应用、数据库、模板和中间件等等。

尽管settings.py文件对几乎所有变量都使用了合理的默认值，但是当 Django 应用过渡到现实世界时，您需要考虑一系列调整，以便高效地运行 Django 应用，为最终用户提供简化的体验，并控制潜在的恶意攻击者。

将调试切换到 False

在现实世界中启动 Django 应用首先要做的事情之一是将变量DEBUG改为False。我在前面的章节中已经简单地提到了 Django 在从DEBUG=False切换到DEBUG=True时的行为变化。所有这些与DEBUG变量相关的行为变化都是为了增强项目的安全性。表 5-1 说明了使用DEBUG=False和DEBUG=True运行项目的区别。

表 5-1。

Django behavior differences between DEBUG=True and DEBUG=False

| 功能 | 调试=真实行为 | 调试=错误行为 | | --- | --- | --- | | 错误处理和通知 | 在请求页面上显示完整的错误堆栈，以便快速分析。 | 显示默认的“普通”或自定义错误页面，没有任何堆栈详细信息，以限制安全威胁或尴尬。向项目管理员发送错误电子邮件。(有关电子邮件通知的更多详细信息，请参见本节中的“为管理员和管理者定义管理员”一节。) | | 静态资源 | 为简单起见，默认设置在项目的/static/ URL 上。 | 禁用自动安装以避免安全漏洞，并要求整合到单独的目录中，以便在单独的 web 服务器上运行静态资源。(请参阅下一节中的设置静态网页资源-图像、CSS、JavaScript。)。) | | 主机/站点限定符 | 接受对所有主机/站点的请求进行处理。 | 有必要确定项目可以处理请求的主机/站点。如果站点/主机不合格，所有请求都会被拒绝。(有关更多详细信息，请参见本节中的“定义允许的主机”一节。) |

正如您在表 5-1 中所看到的，通过将DEBUG=True更改为DEBUG=False而实施的更改旨在用于可公开访问的应用(即生产环境)。您可能不喜欢适应这些变化的麻烦，但是它们是为了在现实世界中运行的所有 Django 项目上保持更高的安全性而强制实施的。

定义允许的主机

默认情况下，settings.py中的ALLOWED_HOSTS变量为空。ALLOWED_HOSTS的目的是验证请求的 HTTP Host报头。进行验证是为了防止恶意用户发送伪造的 HTTP Host报头，这些报头可能会毒害缓存和带有恶意主机链接的密码重置电子邮件。由于该问题只能在不受控制的用户环境下出现(即公共/生产服务器)，因此仅在DEBUG=False时进行验证。

如果切换到DEBUG=False而ALLOWED_HOSTS为空，Django 拒绝服务请求，而是用 HTTP 400 错误请求页面来响应，因为它不能验证传入的 HTTP Host头。清单 5-1 展示了ALLOWED_HOSTS的示例定义。

ALLOWED_HOSTS = [
    '.coffeehouse.com',
    '.bestcoffeehouse.com',
]
Listing 5-1.Django ALLOWED_HOSTS definition

正如您在清单 5-1 中看到的，ALLOWED_HOSTS值是一个字符串列表。在这种情况下，它定义了两个主机域，允许bestcoffeehouse.com充当coffeehouse.com的别名。领头的。(点)表示子域也是允许的主机域(例如，static.coffeehouse.com或shop.coffeehouse.com对.coffeehouse.com有效)。

如果您想接受一个完全限定的域(FQDN)，您可以定义ALLOWED_HOSTS=[' www.coffeehouse.com ']，它只接受带有 HTTP Host www.coffeehouse.com 的请求。类似地，如果您想接受任何 HTTP 主机——有效地绕过验证——您可以定义ALLOWED_HOSTS=['*'],它表示一个通配符。

小心使用 SECRET_KEY 值

settings.py中的SECRET_KEY值是另一个与安全相关的变量，如ALLOWED_HOSTS。然而，与ALLOWED_HOSTS不同的是，SECRET_KEY被赋予一个默认值和一个很长的值(例如'oubrz5ado&%+t(qu^fqo_#uhn7*+q*#9b3gje0-yj7^#g#ronn')。

SECRET_KEY值的目的是对某些易被篡改的数据结构进行数字签名。具体来说，Django 默认使用敏感数据结构上的SECRET_KEY,比如会话标识符、cookies 和密码重置标记。但是您可以依靠SECRET_KEY值来加密保护 Django 项目中的任何敏感数据结构。 ¹

用SECRET_KEY签名的默认数据结构的一个共同点是，它们被发送给更广泛的互联网上的用户，然后被发送回应用以代表用户触发动作。正是在这种情况下，我们进入了信任问题。发回应用的数据可信吗？如果恶意用户试图模拟另一个用户的 cookie 或会话数据来劫持他的访问，该怎么办？这是数字签名数据所阻止的。

在 Django 向互联网上的用户发送任何这些敏感的数据结构之前，它会用项目的SECRET_KEY给它们签名。当数据结构返回来完成一个动作时，Django 再次对照SECRET_KEY检查这些敏感的数据结构。如果对数据结构有任何篡改，签名检查就会失败，Django 会中止这个过程。

流氓用户成功发动这种攻击的唯一可能性是SECRET_KEY被破坏——因为攻击者可能会创建一个与项目的SECRET_KEY相匹配的修改过的数据结构。因此，你应该小心暴露你的项目的SECRET_KEY。如果您怀疑某个项目的SECRET_KEY由于任何原因已经被破坏，您应该立即替换它——只有少数短暂的数据结构(即会话、cookies)会随着这种改变而变得无效，直到用户再次重新登录，新的SECRET_KEY用于重新生成这些数据结构。

为管理员和经理定义管理员

一旦最终用户可以访问 Django 项目，您就会希望通过某种方式接收与安全或其他关键因素相关的重要事件的通知。Django 有两套管理组，分别在settings.py : ADMINS和MANAGERS中定义。默认情况下，ADMINS和MANAGERS都是空的。分配给这两个变量的值必须是元组，其中元组的第一个值是一个名称，元组的第二部分是一封电子邮件。清单 5-2 显示了ADMINS和MANAGERS的示例定义。

ADMINS = (('Webmaster','webmaster@coffeehouse.com'),('Administrator','admin@coffeehouse.com'))

MANAGERS = ADMINS

Listing 5-2.Django ADMINS and MANAGERS definition

正如您在清单 5-2 中看到的，变量ADMINS被赋予了两个具有不同管理员的元组。接下来，你可以看到ADMINS的值被赋给了MANAGERS变量。当然，您可以使用与ADMINS相同的语法为MANAGERS定义不同的值，但是在这种情况下，为了简单起见，我给了两个变量相同的值。

在settings.py中有这两个管理组的目的是让 Django 发送项目事件的电子邮件通知。默认情况下，这些事件是有限的，并且在特定情况下发生。毕竟，你不希望每分钟 24/7 向管理员发送 10 封电子邮件通知。

默认情况下，当且仅当DEBUG=False出现与django.request或django.security包相关的错误时，会向ADMINS发送电子邮件通知。这是一个非常狭窄的标准，因为它只打算通知最严重的错误——对于请求和安全性——并且只针对生产环境，也就是当DEBUG=False出现时。因为没有其他事件或条件，所以ADMINS通过电子邮件通知。

默认情况下，当且仅当DEBUG=False和 Django 中间件django.middleware.common.BrokenLinkEmailsMiddleware启用时，才会向MANAGERS发送断开链接的电子邮件通知(即 HTTP 404 页面请求)。因为 HTTP 404 页面请求不是一个严重的问题，默认情况下BrokenLinkEmailsMiddleware是禁用的。这是一个比ADMINS更窄的标准，因为不管项目是在开发中(DEBUG=True)还是在生产中(DEBUG=False)，都需要将BrokenLinkEmailsMiddleware类添加到settings.py中的MIDDLEWARE变量中，以便MANAGERS获得通知。因为没有其他事件或条件，所以MANAGERS通过电子邮件通知。

既然您已经知道了ADMINS和MANAGERS的用途，那么就在您的项目中添加您认为合适的用户和电子邮件。记住，对于 Django 项目中的其他定制逻辑，您总是可以利用ADMINS和MANAGERS中的值(例如，通知管理员用户注册)。

Modify Logging to Stop Email Notifications to Admins

默认情况下，一旦您切换到 DEBUG=False，ADMINS 中的用户就开始收到错误电子邮件——这与管理器不同，管理器永远不会收到电子邮件，除非您将 BrokenLinkEmailsMiddleware 添加到 MIDDLEWARE_CLASSES。

要在 DEBUG=False 时停止向管理员发送电子邮件通知，您可以修改 Django 的日志设置，这将在本章的日志一节中介绍。您也可以不定义 ADMINS，这样就不会发送电子邮件，但这会使您的项目没有可能对其他用途有用的 ADMINS 定义。

使用动态绝对路径

在settings.py中有一些依赖于目录位置的 Django 变量，例如STATIC_ROOT，它为项目的静态文件定义了一个合并目录，或者TEMPLATES变量的DIRS列表，它定义了项目模板的位置，等等。

依赖于目录位置的变量的问题是，如果您在不同的服务器上运行项目或者与其他用户共享项目，那么很难在一系列环境中跟踪或保留相同的目录。要解决这个问题，您可以定义变量来动态确定项目的绝对路径。清单 5-3 展示了一个 Django 项目目录结构，部署到/www/系统目录中。

+-/www/+
       |
       +--STORE--+
                 |
                 +---manage.py
                 |
                 +---coffeestatic--+
                 |                 |
                 |                 +-(Consolidated static resources)
                 |
                 +---coffeehouse--+
                                  |
                                  +-__init__.py
                                  +-settings.py
                                  +-urls.py
                                  +-wsgi.py
                                  |
                                  +---templates---+
                                                  +-app_base_template.html
                                                  +-app_header_template.html
                                                  +-app_footer_template.html
Listing 5-3.Django project structure deployed to /www/

通常 Django settings.py文件会定义TEMPLATES中STATIC_ROOT和DIRS的值，如清单 5-4 所示。

# Other configuration variables omitted for brevity
STATIC_ROOT = '/www/STORE/coffeestatic/'

# Other configuration variables omitted for brevity
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': ['/www/STORE/coffeehouse/templates/',],
}
]

Listing 5-4.Django settings.py with absolute path values

清单 5-4 中设置的问题是，如果您将 Django 应用部署到一个没有/www/目录的服务器上，它将需要编辑(例如，由于限制或 Windows 操作系统中目录以字母 C:/开头)。

清单 5-5 中展示的一种更简单的方法是定义变量来动态确定项目的绝对路径。

import os
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

# Other configuration variables omitted for brevity
STATIC_ROOT = '%s/coffeestatic/' % (BASE_DIR)

# Other configuration variables omitted for brevity
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': ['%s/templates/'% (PROJECT_DIR),],
}
]

Listing 5-5.Django settings.py with dynamically determined absolute path

清单 5-5 顶部定义的变量依赖于 Python os模块来动态确定相对于settings.py文件的绝对系统路径。PROJECT_DIR=os.path.dirname(os.path.abspath(__file__))语句被翻译成/www/STORE/coffeehouse/值，这是像settings.py这样的文件的绝对系统目录。要访问/www/STORE/coffeehouse/的父级，只需用另一个对os.path.dirname的调用包装相同的语句，并定义BASE_DIR变量，这样它就被转换成/www/STORE/值。

清单 5-5 中的其余语句使用标准的 Python 字符串替换来使用PROJECT_DIR和BASE_DIR来设置STATIC_ROOT和TEMPLATE_DIRS变量中的绝对路径。通过这种方式，您不需要为任何 Django 配置变量硬编码绝对路径；不管应用部署目录如何，变量都会自动调整到任何绝对目录。

为 Django 使用多个环境或配置文件

在每个 Django 项目中，你最终会意识到你必须将settings.py分成多个环境或文件。这可能是因为settings.py中的值需要在开发和生产服务器之间进行更改，有许多人在不同的需求下工作于同一个项目(例如，Windows 和 Linux)，或者您需要将敏感的settings.py信息(例如，密码)保存在不与他人共享的本地文件中。

在 Django 中，没有最好的或标准的方法将settings.py分割成多个环境或文件。事实上，有许多技术和库可以让 Django 项目用一个分割的settings.py文件运行。接下来，我将展示我在项目中使用的三个最流行的选项。根据您的需求，您可能会觉得使用一种方法比使用另一种方法更合适，或者混合使用两种或所有三种方法来实现最终解决方案。

选项 1)同一个 settings.py 文件中的多个环境，带有一个控制变量

settings.py文件被视为普通的 Python 文件，因此使用 Python 库或条件来获得某些行为没有限制。这意味着您可以基于固定值(例如，服务器主机名)轻松引入控制变量，以有条件地设置某些变量值。

例如，更改DATABASES变量——因为密码和数据库名称在开发和生产之间会发生变化——更改EMAIL_BACKEND变量——因为您不需要像在生产中那样在开发中发送实际的电子邮件——或者更改CACHES变量——因为您不需要像在生产中那样在开发中使用缓存来提高性能。

清单 5-6 展示了基于 Python 的socket模块设置一个名为DJANGO_HOST的控制变量；然后，该变量用于根据服务器的主机名加载不同组的 Django 变量。

# Import socket to read host name
import socket
# If the host name starts with 'live', DJANGO_HOST = "production"
if socket.gethostname().startswith('live'):
    DJANGO_HOST = "production"
# Else if host name starts with 'test', set DJANGO_HOST = "test"
elif socket.gethostname().startswith('test'):
    DJANGO_HOST = "testing"
else:
# If host doesn't match, assume it's a development server, set DJANGO_HOST = "development"
    DJANGO_HOST = "development"

# Define general behavior variables for DJANGO_HOST and all others
if DJANGO_HOST == "production":
    DEBUG = False
    STATIC_URL = 'http://static.coffeehouse.com/'
else:
    DEBUG = True
    STATIC_URL = '/static/'

# Define DATABASES variable for DJANGO_HOST and all others
if DJANGO_HOST == "production":
   # Use mysql for live host
   DATABASES = {
    'default': {
        'NAME': 'housecoffee',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'coffee',
        'PASSWORD': 'secretpass'
    }
  }
else:
   # Use sqlite for non live host
   DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'coffee.sqlite3'),
    }
  }

# Define EMAIL_BACKEND variable for DJANGO_HOST
if DJANGO_HOST == "production":
    # Output to SMTP server on DJANGO_HOST production
    EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
elif DJANGO_HOST == "testing":
    # Nullify output on DJANGO_HOST test
    EMAIL_BACKEND = 'django.core.mail.backends.dummy.EmailBackend'
else:
    # Output to console for all others
    EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

# Define CACHES variable for DJANGO_HOST production and all other hosts
if DJANGO_HOST == "production":
   # Set cache
   CACHES = {
        'default': {
            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
            'LOCATION': '127.0.0.1:11211',
            'TIMEOUT':'1800',
            }
        }
   CACHE_MIDDLEWARE_SECONDS = 1800
else:
   # No cache for all other hosts
   pass

Listing 5-6.Django settings.py with control variable with host name to load different sets of variables

清单 5-6 中的第一行导入 Python socket模块来访问主机名。接下来，使用socket.gethostname()声明一系列条件，以确定控制变量DJANGO_HOST的值。如果主机名以字母live开头，则DJANGO_HOST变量被设置为"production"，如果主机名以test开头，则DJANGO_HOST被设置为"testing"，如果主机名不是以前面的选项开头，则DJANGO_HOST被设置为"development"。

在这个场景中，字符串方法startswith用于确定如何根据主机名设置控制变量。然而，您可以轻松地使用任何其他 Python 库甚至标准(例如，IP 地址)来设置控制变量。此外，由于控制变量是基于字符串的，您可以根据需要引入任意多的配置变量。在这种情况下，我们使用三种不同的变量来设置settings.py变量——"production"、"testing"和"development"——但是如果你需要如此多的不同设置，你可以很容易地定义五个或十几个变量。

选项 2)使用 configparser 的多个环境文件

split settings.py的另一个变化是依赖 Python 内置的 configparser 模块。configparser 允许 Django 从文件中读取配置变量，这些文件使用的数据结构类似于 Microsoft Windows INI 文件中使用的数据结构。清单 5-7 展示了一个样本 configparser 文件。

[general]
DEBUG: false
STATIC_URL: http://static.coffeehouse.com/

[databases]
NAME: housecoffee
ENGINE: django.db.backends.mysql
USER: coffee
PASSWORD: secretpass

[security]
SECRET_KEY: %%ea)cjy@v9(7!b(20gl+4-6iur28dy=tc4f$-zbm-v=!t

Listing 5-7.Python configparser sample file production.cfg

正如您在清单 5-7 中看到的，configparser 文件的格式由括号中声明的各个部分构成(例如，[general]，[databases])，每个部分下面是不同的键和值。清单 5-7 中的变量代表了一个放置在名为production.cfg的文件中的生产环境。我为这个文件选择了.cfg扩展名，但是如果你愿意，你也可以使用.config或.ini扩展名；扩展名与 Python 无关——唯一重要的是文件本身的数据格式。

类似于production.cfg中的内容，您可以为其他环境创建不同变量的其他文件(如testing.cfg、development.cfg)。一旦有了 configparser 文件，就可以将它们导入到 Django settings.py中。清单 5-8 显示了一个使用 configparser 文件中的值的示例settings.py。

import os

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
PROJECT_DIR = os.path.dirname(os.path.abspath(__file__))

# Access configparser to load variable values
from django.utils.six.moves import configparser
config = configparser.SafeConfigParser(allow_no_value=True)

# Import socket to read host name
import socket
# If the host name starts with 'live', load configparser from "production.cfg"
if socket.gethostname().startswith('live'):
    config.read('%s/production.cfg' % (PROJECT_DIR))
# Else if host name starts with 'test', load configparser from "testing.cfg"
elif socket.gethostname().startswith('test'):
    config.read('%s/testing.cfg' % (PROJECT_DIR))
else:
# If host doesn't match, assume it's a development server, load configparser from "development.cfg"
    config.read('%s/development.cfg' % (PROJECT_DIR))

DEBUG = config.get('general', 'DEBUG')
STATIC_URL = config.get('general', 'STATIC_URL')

DATABASES = {
    'default': {
        'NAME': config.get('databases', 'NAME'),
        'ENGINE': config.get('databases', 'ENGINE'),
        'USER': config.get('databases', 'USER'),
        'PASSWORD': config.get('databases', 'PASSWORD')
    }
  }

SECRET_KEY = config.get('security', 'SECRET_KEY')

Listing 5-8.Django settings.py with configparser import

Note

清单 5-8 中的配置假设主机名以名称 live 开始，以便加载清单 5-7 中的 configparser production.cfg。调整清单 5-8 开头的条件以匹配主机名并加载适当的 configparser 文件。

正如您在清单 5-8 中看到的，configparser 通过django.utils.six.moves加载到 Django 中，这是一个允许 Python 2 和 Python 3 之间交叉导入的实用程序。在 Python 2 中，configparser 包实际上被命名为ConfigParser，但是这个实用程序允许我们在 Python 2 或 Python 3 中使用相同的 import 语句。导入之后，我们使用带有参数allow_no_value=True的SafeConfigParser类来允许处理 configparser 键中的空值。

然后，我们依靠相同的现有技术，使用 Python 的socket模块来访问主机名，并确定要加载哪个 configparser 文件。使用SafeConfigParser实例的 read 方法加载 configparser 文件。此时，所有 configparser 变量都已加载并准备好供访问。清单 5-8 的剩余部分显示了一系列标准 Django settings.py变量，这些变量使用SafeConfigParser实例的get方法赋值，其中第一个参数是 configparser 部分，第二个参数是 key 变量。

因此，在如何将settings.py中的变量拆分到多个环境中，您有了另一种选择。正如我在开始时提到的，做这件事没有最好或标准的方法。有些人更喜欢 configparser，因为它将值拆分到单独的文件中，避免了选项 1 的许多条件，但其他人可能讨厌 configparser，因为需要处理特殊的语法和单独的文件。选择最适合你的项目的。

选项 3)每个环境有多个不同名称的 settings.py 文件

最后，将 Django 变量拆分到多个环境的另一个选项是创建多个不同名称的settings.py文件。默认情况下，Django 会在项目基本目录的settings.py文件中查找配置变量。

然而，可以告诉 Django 加载一个不同名称的配置文件。Django 为此使用了操作系统变量DJANGO_SETTINGS_MODULE。默认情况下，Django 将这个 OS 变量设置为位于任何 Django 项目的基目录下的manage.py文件中的<project_name>.settings。由于manage.py文件用于引导 Django 应用，该文件中的DJANGO_SETTINGS_MODULE值保证配置变量总是从<project_name>子目录中的settings.py文件加载。

所以让我们假设您为 Django 应用创建了不同的settings.py文件——与settings.py放在同一个目录中——命名为production.py、testing.py和development.py。您有两种选择来加载这些不同的文件。

一种选择是将项目的manage.py文件中的DJANGO_SETTINGS_MODULE定义更改为具有所需配置的文件(例如，os.environ.setdefault("DJANGO_SETTINGS_MODULE", "coffeehouse.production")加载production.py配置文件)。然而，硬编码这个值是不灵活的，因为您需要根据期望的配置不断地改变manage.py中的值。这里，您可以在manage.py中使用一个控制变量，根据主机名动态确定DJANGO_SETTINGS_MODULE的值——类似于前面选项 1 中针对settings.py描述的过程。

设置DJANGO_SETTINGS_MODULE而不改变manage.py的另一种可能性是在操作系统级别定义DJANGO_SETTINGS_MODULE，这样它会覆盖manage.py中的定义。清单 5-9 展示了如何在 Linux/Unix 操作系统上设置DJANGO_SETTINGS_MODULE变量，以便使用testing.py文件中的应用变量来代替settings.py文件。

$ export DJANGO_SETTINGS_MODULE=coffeehouse.load_testing
$ python manage.py runserver
Validating models...

0 errors found
Django version 1.11, using settings 'coffeehouse.load_testing'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Listing 5-9.Override DJANGO_SETTINGS_MODULE to load application variables from a file called testing.py and not the default settings.py

在清单 5-9 中，我们使用标准的 Linux/Unix 语法export variable_name=variable_value来设置环境变量。一旦完成，注意使用开发服务器的 Django 应用显示启动消息"using settings 'coffeehouse.load_testing'"。

如果您计划在操作系统级别覆盖DJANGO_SETTINGS_MODULE来加载不同的 Django 应用变量，请注意默认情况下操作系统变量不是永久的或继承的。这意味着您可能需要为启动 Django 的每个 shell 定义DJANGO_SETTINGS_MODULE,并将其定义为运行时环境(例如 Apache)的一个局部变量。

设置静态网页资源——图像、CSS、JavaScript

如果项目使用DEBUG=True或DEBUG=False运行，Django 项目中静态资源的设置过程会有很大的不同。这意味着静态资源部署取决于您是在开发环境中工作——通常使用DEBUG=True——还是在生产环境中工作——通常使用DEBUG=False。

考虑到您总是在开发环境中启动 Django 项目，然后迁移到生产环境，我将首先描述开发设置过程，然后描述生产设置过程。

在开发环境中设置静态资源(DEBUG=False)

默认情况下，当DEBUG=False时，Django 自动从两个主要位置设置静态资源。第一个位置是所有 Django 应用中的static文件夹，第二个位置是在settings.py的STATICFILES_DIR变量中声明的文件夹。

虽然您需要在 Django apps 中手动创建static文件夹，但是在项目中设置静态资源非常容易。因为 Django 为每个项目应用设置了所有的static文件夹，所以建议在static文件夹中进一步添加一个子目录(例如<app_folder>/static/<app_name>/<static_files_here>)，以限定静态资源并避免潜在的命名冲突。清单 5-10 展示了一个静态资源的样本目录结构。

+-<BASE_DIR_project_name>
|
+-manage.py
|
+-bootstrap-3.1.1-dist+
|                     +-bootstrap.min.js
|
+-jquery-1-11-1-dist+
|                   +jquery.min.js
|
+-jquery-ui-1.10.4+
|                 +jquery-ui.min.js
|
+-website-static-default+
|                       +-favicon.ico
|                       +-robots.txt
|
|
+---+-<PROJECT_DIR_project_name>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
    |
    +-about(app)-+
    |            +-__init__.py
    |            +-models.py
    |            +-tests.py
    |            +-views.py
    |            +-static-+
    |                     |
    |                     +-about-+
    |                             +-img-+
    |                             |     +-logo.png
    |                             |
    |                             +-css-+
    |                                   +-custom.css
    +-stores(app)-+
                 +-__init__.py
                 +-models.py
                 +-tests.py
                 +-views.py
                 +-static-+
                          |
                          +-stores-+
                                   +-img-+
                                   |     +-coffee.gif
                                   |
                                   +-css-+
                                         +-custom.css
Listing 5-10.Django app structure with static directories

如清单 5-10 所示，所有 Django 应用目录都有一个包含静态资源的static子目录。这些静态子目录下的任何内容都是为访问而设置的。

还要注意清单 5-10 中的应用名称子目录在static子目录中作为名称空间的重要性。如果静态资源直接放在所有应用中的static文件夹下，在这种情况下，会导致两个相同的文件路径名为/static/css/custom.css，在这种情况下，调用加载这个静态资源会导致冲突。从技术上讲，Django 总是使用它找到的第一个文件，但是第一个文件是正确的吗？通过使用static内的应用名称子目录，它避免了任何潜在的冲突，一个静态资源设置在/static/about/css/custom.css而另一个设置在/static/stores/css/custom.css。

因为可能存在不一定属于特定项目应用的静态资源，所以 Django 还支持设置存储在任何子目录中的静态资源的能力。

如果您再次查看清单 5-10 ，在BASE_DIR和PROJECT_DIR之间，您将会看到包含流行静态资源库- jquery、jquery-ui和bootstrap的各种子文件夹，以及包含网站标准静态资源-robots.txt & favicon.ico的子文件夹website-static-default。

为了设置这些额外的静态资源，您在settings.py的STATICFILES_DIR变量中定义这些目录的位置。清单 5-11 展示了一个STATICFILES_DIR定义的例子。

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

STATICFILES_DIRS = ('%s/website-static-default/'% (BASE_DIR),
                    ('bootstrap','%s/bootstrap-3.1.1-dist/'% (BASE_DIR)),
                    ('jquery','%s/jquery-1-11-1-dist/'% (BASE_DIR)),
                    ('jquery-ui','%s/jquery-ui-1.10.4/'% (BASE_DIR)),)

Listing 5-11.Django STATICFILES_DIR definition with namespaces in settings.py

正如您在清单 5-11 中看到的，STATICFILES_DIRS接受一个目录列表。在这种情况下，所有目录都在 Django 项目的BASE_DIR下，所以它使用了动态确定父目录的BASE_DIR变量。清单 5-11 中目录列表的另一个方面是你可以选择声明一个名称空间，类似于应用的static子目录中使用的方法。

清单 5-11 中的第一个目录定义是一个简单的字符串(也就是说，它没有名称空间)，这意味着website-static-default中的静态资源是用直接访问模式建立的。其余的目录定义是元组而不是字符串。通过使用元组，它将元组的第一部分定义为名称空间，第二部分定义为包含静态资源的目录。带有名称空间的定义意味着给定目录下的所有静态资源将在其访问模式中使用前缀名称空间(例如，要访问bootstrap-3.1.1-dist上的静态资源，访问模式应该以bootstrap为前缀)。

现在您已经知道了在哪里以及如何设置所有静态资源，让我们快速看一下 Django 如何可视化这些静态资源，以理解静态资源的最终访问模式是什么样子的。清单 5-12 展示了前面清单中呈现的静态资源的可视化。

+-favicon.ico
+-robots.txt
|
+-jquery+
|       +jquery.min.js
|
+-jquery-ui+
|          +jquery-ui.min.js
|
+-bootstrap+
|          +-bootstrap.css
|
+-about-+
|       +-img-+
|       |     +-logo.png
|       |
|       +-css-+
|             +-custom.css
|
+-stores-+
         +-img-+
         |     +-coffee.gif
         |
         +-css-+
               +-custom.css
Listing 5-12.Django visualization of static resources in apps and STATICFILES_DIRS

清单 5-12 中的文件favicon.ico和robots.txt位于可视化的顶层，因为它们的源目录website-static-default在STATICFILES_DIRS中没有命名空间。

其余的静态资源都分组在子文件夹中，因为我们要么在STATICFILES_DIRS中为它们定义了一个名称空间，要么在应用的static子目录中将子文件夹定义为名称空间。

现在您已经理解了 Django 如何将静态资源可视化为一个组，以及这如何决定静态资源的最终访问模式，让我们将注意力转向settings.py中的STATIC_URL变量。

STATIC_URL用于定义清单 5-12 中显示的 Django 静态资源可视化的 URL 入口点。默认情况下，STATIC_URL被赋予/static/值。这意味着如果STATIC_URL='/static/'，静态资源robots.txt在 URL /static/robots.txt变得可访问，就像stores/img/coffee.gif在 URL /static/stores/img/coffee.gif变得可访问一样。

这意味着您在/static/ URL 上访问静态资源，或者如果您更改了STATIC_URL值，则在不同的 URL 上访问静态资源。但是，不要在模板上硬编码这些静态资源路径！(如<img src="/static/stores/img/coffee.gif"/>)。您应该使用一个变量，以便在STATIC_URL改变的情况下动态确定最终路径。下一节将描述如何在 Django 模板中做到这一点。

Caution

对静态资源的自动访问只适用于 Django 的内置 web 服务器，并且 DEBUG=True。

之前静态资源的设置过程有 Django 的“幕后”帮助。它只与 Django 的内置 web 服务器(即python manage.py runserver)一起工作，并且只有在DEBUG=True的情况下。一旦你换到一个不同的 web 服务器或者切换DEBUG=False甚至使用 Django 的内置 web 服务器，就没有静态资源可用，如清单 5-12 所示。

这种行为背后的主要原因是因为从应用的主 web 服务器/URL 结构(例如，/static/)保留和调度静态资源是非常低效的。所以这只是为了方便使用 Django 的内置 web 服务器进行开发。当然，您可以将一个完整的 URL 域分配给STATIC_URL(例如 http://static.coffeehouse.com/ )，但是这假设您已经在一个类似生产的环境中设置了项目的静态资源，在我描述如何访问 Django 和 Jinja 模板中的静态资源时，我将很快讨论这个问题。

访问 Django 模板中的静态资源

推荐在 Django 模板中引用静态资源的方法是通过 staticfiles 应用，通过{% static %}标签。清单 5-13 展示了 staticfiles 应用语法的各种例子。

{% load static %}

# For static resource at about/img/logo.png
<img src="{% static 'about/img/logo.gif' %}">

# For static resource at bootstrap/bootstrap.css
<link href="{% static 'bootstrap/bootstrap.css' %}" rel="stylesheet">

# For static resource at jquery/jquery.min.js
<script src="{% static 'jquery/jquery.min.js' %}"></script>

Listing 5-13.Django {% static %} tag to reference static resources

首先，重要的是要注意清单 5-13 中的{% load static %}标签可以通过 staticfiles 应用获得，该应用默认安装在所有 Django 项目的INSTALLED_APPS变量中。如果出于某种原因，你修改了INSTALLED_APPS中的默认值，确保你在INSTALLED_APPS变量中有django.contrib.staticfiles的值，否则接下来的都不会起作用。

正如您在清单 5-13 中看到的，在模板的顶部，您总是声明{% load static %}语句。一旦完成，模板就可以使用{% static %}标签为静态资源生成动态路径。在大多数情况下，{% static %}标签依赖于settings.py中的STATIC_URL变量来生成静态资源的适当路径。

对于更高级的情况，{% static %}标签使用相同的STATIC_URL变量和后备存储技术(例如，CDN-‘内容交付网络’)配置的组合来生成静态资源的适当路径。

例如，请注意清单 5-13 中的{% static %}标签后面总是跟有一个文件路径，该路径与清单 5-12 中静态资源的 Django 可视化相同。由于STATIC_URL变量的值为/static/，这意味着清单 5-13 中的{% static %}语句被替换为该值(例如{% static 'bootstrap/bootstrap.css' %}变成了/static/bootstrap/bootstrap.css)。

当 Django 项目使用非标准的后端来提供静态资源时,{% static %}标签被替换为不同于STATIC_URL变量的东西——最后一种情况将在下面的侧栏中简要讨论。

Why Use the Staticfiles {% Static %} Tag Vs. Using the Static_Url Variable Directly in Templates?

在 Django 的早期版本中，Django 模板在模板中直接使用了 STATIC_URL 变量(例如)。事实上，您仍然可以通过 Django . template . context _ processors . STATIC 上下文处理器访问所有 Django 模板上的 STATIC_URL 变量。

然而，随着服务静态资源的底层技术变得越来越复杂，STATIC_URL 变量本身被证明是不够的。例如，像 CDNs 或亚马逊 S3 这样的静态服务技术经常使用特殊的令牌来实施认证或缓存策略。这意味着类似于的语句需要转换成类似于![](https://gitee.com/OpenDocCN/vkdoc-pythonweb-zh/raw/master/docs/begin-dj/img/<span class=) http://cdnprovider.com/about/img/logo.gif?token=e354534566 " >或< img src=" http://staticresources.com/about/img/logo32AzTB9r5.gif " >的语句。虽然可以将 STATIC_URL 变量更改为完整的域，但是很难修改静态资源的路径本身。

用像{% static %}这样的标签重写静态资源的路径很容易。因为{% static %}可以接受静态资源的基本字符串(例如，about/img/logo.gif ),并使用 STATIC_URL 变量和底层静态服务技术所需的任何特殊标记动态生成完整路径。这个过程是通过使用一个定制的存储类来实现的，该存储类是为静态服务技术而设计的。

当然，并不是所有的项目都需要使用先进的静态服务技术。但是通过使用 staticfiles 应用的{% static %}标记来声明 Django 模板中的静态资源，您可以确保 Django 项目能够使用任何静态服务技术，从最基本的到最高级的。

访问 Jinja 模板中的静态资源

如前一章所述，Jinja 模板提供了 Django 自己的模板的替代品。但是与 Django 模板不同，你必须遵循不同的设置来使用 Jinja 模板中 staticfiles 应用的 Django 的{% static %}标签。

为了能够在 Jinja 模板中使用相同的 staticfiles app / {% static %}标记行为，您需要设置一个名为 static 的全局变量来挂钩这个功能。在前面关于 Jinja 模板的章节中,“在 Django 中为所有 Jinja 模板(如 Django 上下文处理器)上的访问设置数据”一节描述了如何用这个功能创建一个全局变量。

在生产环境中设置静态资源(DEBUG=True)

当您将 Django 项目的DEBUG变量切换到True或者切换到不同的 web 服务器(例如 Apache、Nginx)时，您会惊讶地发现项目中不再出现任何静态资源。不要惊慌，这是故意的。当DEBUG=True使用 Django 的内置 web 服务器或者如果你切换到第三方 web 服务器时，设置 Django 来服务静态资源并不太困难。

Tip

您可以访问静态资源，使 Django 的内置 web 服务器在实际设置为 DEBUG=True 时提供静态资源，就像 DEBUG=False 一样。使用- insecure 标志运行 web 服务器:python manage . py run server–insecure。

Caution

虽然前面的解决方法是可用的，但我建议您不要使用它，以防标志名本身不安全不足以阻止您使用它。

Django 的内置 web 服务器(即python manage.py runserver)确实是一个快速启动和运行的便利工具，作为这种便利的一部分，它还在DEBUG=False时提供静态资源。

然而，允许同一个 web 服务器进程同时处理动态内容(Django web 页面)和静态资源(图像、CSS、JavaScript)确实是一种浪费。推荐的方法是完全使用一个单独的 web 服务器来服务静态资源，这就是为什么 Django 在切换DEBUG=True时打破了内置 web 服务器的便利性。

当DEBUG=True出现时，您需要做的第一件事是创建一个目录来保存 Django 可视化为静态资源的所有静态资源的副本。之前你已经了解到当DEBUG=False时，Django 将来自几个位置和子目录的静态资源可视化在一个单独的树中——如清单 5-12 所示。Django 设想的正是这一棵树，您需要创建一个副本来在生产环境中运行。

你需要在settings.py.中定义STATIC_ROOT变量，你分配给STATIC_ROOT的值应该是一个目录，Django 将在那里复制你项目的所有静态资源——与 Django 在清单 5-12 中展示的DEBUG=True时可视化它们的方式相同。请注意，此目录应该为空，因为每次执行同步过程时，它都会被不断覆盖。根据您的需要，该目录的位置可以是系统中的任何位置。为了简单起见，我将把 Django 项目的BASE_DIR下的STATIC_ROOT目录保留为STATIC_ROOT = '%s/coffeestatic/'% (BASE_DIR。

要触发同步过程(即，将所有静态资源复制到STATIC_ROOT，您需要使用manage.py脚本中可用的collectstatic命令。清单 5-14 展示了同步过程的示例输出。

[user@coffeehouse ∼]$ python manage.py collectstatic

You have requested to collect static files at the destination
location as specified in your settings:

    /www/STORE/coffeestatic

This will overwrite existing files!
Are you sure you want to do this?

Type 'yes' to continue, or 'no' to cancel: yes
yes
Copying '/www/STORE/website-static-default/sitemap.xml'
Copying '/www/STORE/website-static-default/robots.txt'
Copying '/www/STORE/website-static-default/favicon.ico'
....
....
....
Copying '/www/STORE/coffeehouse/about/static/css/custom.css'

732 static files copied to '/www/STORE/coffeestatic'.

Listing 5-14.Django collectstatic command to copy all static resources

一旦你将所有项目的静态资源收集到一个单独的文件夹中——在这个例子中是/www/STORE/coffeestatic——它们就可以在一个生产服务器上进行设置了(例如，Apache、Nginx 或 AWS S3)。请记住，collectstatic生成的目录/文件结构与清单 5-12 中展示的上一节中 Django 可视化的目录/文件结构相同。

您需要做的最后一步是更新settings.py中的STATIC_URL值，以反映静态资源的新位置。例如，如果您在 Apache 或 Nginx 上的 http://static.coffeehouse.com/ 域下挂载/www/STORE/coffeestatic/目录，您将设置STATIC_URL=' http://static.coffeehouse.com '。类似地，如果您将/www/STORE/coffeestatic/中的静态资源复制到一个名为 http://coffeehouse.s3.amazonaws.com 的 Amazon AWS S3 存储桶，您将设置STATIC_URL=' http://coffeehouse.s3.amazonaws.com '

一旦进行了最后的修改，Django 模板中所有使用{% static %}标签的语句都将更新为新的全域 URL，在这种情况下，像/www/STORE/coffeestatic/bootstrap/bootstrap.css这样的资源将在http://static.coffeehouse.com/bootstrap/bootstrap.css?? 或 http://coffeehouse.s3.amazonaws.com/bootstrap/bootstrap.css 可用。

Django 伐木公司

日志是最有用的应用管理实践之一，也是使用最少的应用管理实践之一。如果您仍然没有在 Django 项目中使用日志，或者使用 Python print()语句来深入了解应用正在做什么，那么您就错过了很多功能。接下来，您将学习 Python 核心日志概念，如何设置 Django 定制日志，以及如何使用监控服务来跟踪日志消息。

Python 核心日志记录概念

Django 构建在 Python 的日志包之上。Python 日志包提供了一种健壮而灵活的方法来设置应用日志。如果您从未使用过 Python 的日志包，我将简要概述它的核心概念。Python 日志记录中有四个核心概念:

伐木工人。-提供日志消息分组的初始入口点。通常，每个 Python 模块(即，py 文件)有一个单独的日志记录器来分配它的日志消息。然而，也可以在同一个模块中定义多个记录器(例如，一个记录器用于业务逻辑，另一个记录器用于数据库逻辑，等等)。).此外，还可以在多个 Python 模块之间使用同一个日志记录器。py 文件。
经手人。-用于将日志消息(由记录器创建)重定向到目标。目的地可以包括平面文件、服务器控制台、电子邮件或 SMS 消息以及其他目的地。可以在多个记录器中使用同一个处理程序，就像一个记录器可以使用多个处理程序一样。
过滤器。-提供一种对日志消息应用规则的方法。例如，您可以使用过滤器将同一记录器生成的日志消息发送到不同的处理程序。
格式化程序。-用于指定日志消息的最终格式。

简要概述了 Python 日志概念之后，让我们直接开始探索 Django 的默认日志功能。

Django 默认日志记录

Django 项目的日志配置在settings.py的LOGGING变量中定义。目前，甚至不要麻烦打开你的项目的settings.py文件，因为你不会在其中看到LOGGING。当您创建一个项目时，这个变量不是硬编码的，但是如果它没有被声明，它确实有一些有效的日志记录值。清单 5-15 显示默认的LOGGING值，如果它没有在settings.py中声明的话。

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'filters': {
        'require_debug_false': {
            '()': 'django.utils.log.RequireDebugFalse',
        },
        'require_debug_true': {
            '()': 'django.utils.log.RequireDebugTrue',
        },
    },
    'handlers': {
        'console': {
            'level': 'INFO',
            'filters': ['require_debug_true'],
            'class': 'logging.StreamHandler',
        },
        'null': {
            'class': 'logging.NullHandler',
        },
        'mail_admins': {
            'level': 'ERROR',
            'filters': ['require_debug_false'],
            'class': 'django.utils.log.AdminEmailHandler'
        }
    },
    'loggers': {
        'django': {
            'handlers': ['console'],
        },
        'django.request': {
            'handlers': ['mail_admins'],
            'level': 'ERROR',
            'propagate': False,
        },
        'django.security': {
            'handlers': ['mail_admins'],
            'level': 'ERROR',
            'propagate': False,
        },
        'py.warnings': {
            'handlers': ['console'],
        },
    }
}
Listing 5-15.Default LOGGING in Django projects

总之，清单 5-15 中所示的默认 Django 日志记录设置具有以下日志记录行为:

控制台日志记录或console处理程序仅在DEBUG=True时完成，对于比INFO更差的日志消息(含)且仅针对 Python 包django -及其子包(如django.request、django.contrib ) -以及 Python 包py.warnings。
管理日志或mail_admins处理程序——向ADMINS发送电子邮件——仅在DEBUG=False时完成，用于比ERROR更糟糕的日志消息(包括 ?? ),并且仅用于 Python 包django.request和django.security。

我们先来分解一下清单 5-14 中的handlers部分。处理程序定义发送日志消息的位置，清单 5-14 中有三个位置:console、null和mail_admins。处理程序名本身什么也不做——它们只是引用名——相关的操作在相关的属性字典中定义。所有的处理程序都有一个class属性，该属性定义了执行实际工作的支持 Python 类。

console处理程序被分配了logging.StreamHandler类，它是核心 Python 日志包的一部分。这个类将日志输出发送到流，如标准输入和标准错误，正如处理程序名称所暗示的，从技术上讲，这是 Django 运行的系统控制台或屏幕。

null处理程序被分配了 l ogging.NullHandler类，它也是核心 Python 日志包的一部分，不生成任何输出。

mail_admins处理程序被分配了django.utils.log.AdminEmailHandler类，这是一个 Django 定制处理程序实用程序，它将日志输出作为电子邮件发送给在settings.py中被定义为ADMINS的人——有关ADMINS变量的更多信息，请参见上一节关于为真实世界设置settings.py的内容。

处理程序中的另一个属性是level，它定义了处理程序必须接受日志消息的阈值级别。Python 日志记录有五个阈值级别，从最差到最差依次是CRITICAL、ERROR、WARNING、INFO和DEBUG。console处理程序的INFO级别表示所有差于或等于INFO的日志消息——除了DEBUG之外的每个级别——都应该由处理程序处理，这是一个合理的设置，因为控制台可以处理许多消息。mail_admins处理程序的ERROR级别表示只有比ERROR(也就是CRITICAL)更差或相同的消息才应该由处理程序处理，这是一个合理的设置，因为只有两种最差类型的错误消息才应该触发给管理员的电子邮件。

处理程序中的另一个属性是filters，它定义了一个额外的层来限制处理程序的日志消息。处理程序可以接受多个过滤器，这就是为什么filters属性接受 Python 列表的原因。console处理器有一个过滤器require_debug_true，而mail_admins处理器有一个过滤器require_debug_false。

正如您在清单 5-15 中所看到的，过滤器是在它们自己的块中定义的。require_debug_false过滤器由django.utils.log.RequireDebugFalse类支持，该类检查 Django 项目是否有DEBUG=False，而require_debug_true过滤器由django.utils.log.RequireDebugTrue类支持，该类检查项目是否有DEBUG=True。这意味着如果 Django 项目有DEBUG=True，那么console处理程序只接受日志消息，如果 Django 项目有DEBUG=False，那么mail_admins处理程序只接受日志消息。

现在您已经理解了处理程序和过滤器，让我们来看看loggers部分。记录器定义通常直接映射到 Python 包，并且具有父子关系。例如，属于名为coffeehouse的包的 Python 模块(即.py文件)一般有一个名为coffeehouse的记录器，属于coffeehouse.about的包的 Python 模块一般有一个名为coffeehouse.about的记录器。记录器名称中的点符号也代表父子关系，因此coffeehouse.about记录器被认为是coffeehouse记录器的子记录器。

在清单 5-15 中有四个记录器:django、django.request、django.security和py.warnings。django日志记录器指示所有与其相关的日志消息及其子代都由console处理程序处理。

django.request logger 表示所有与其相关的日志消息及其子代都由mail_admins处理程序处理。django.request日志记录器还有'level':'ERROR'属性来提供日志记录器应该接受日志消息的阈值级别——这个属性覆盖了handler级别属性。此外，django.request记录器还具有'propagate':'False'语句，用于指示记录器不应将消息传播给父记录器(例如，django是django.request的父记录器)。

接下来，我们有一个与django.request记录器功能相同的django.security记录器。以及py.warnings,表示所有与其相关的日志消息及其子节点都将由console处理程序处理。

最后，清单 5-15 中的前两行通常与 Python 日志记录相关。version键将配置版本标识为1，这是目前唯一的 Python 日志版本。而disable_existing_loggers键用于禁用所有现有的 Python 记录器。如果disable_existing_loggers为False，则保持先前存在的记录器值，如果设置为True，则禁用所有先前存在的记录器值。请注意，即使您在自己的LOGGING变量中使用了'disable_existing_loggers': False，您也可以重新定义/覆盖一些或所有预先存在的记录器值。

现在您已经对 Django 日志记录在默认状态下的功能有了很好的理解，我将描述如何在 Django 项目中创建日志消息，然后描述如何创建定制的LOGGING配置。

创建日志消息

在任何 Python 模块或.py文件的顶部，你可以通过使用 Python logging包的getLogger方法来创建记录器。getLogger方法接收记录器的名称作为其输入参数。清单 5-16 展示了使用__name__和硬编码的dba名称创建两个记录器实例。

# Python logging package
import logging

# Standard instance of a logger with __name__
stdlogger = logging.getLogger(__name__)

# Custom instance logging with explicit name
dbalogger = logging.getLogger('dba')

Listing 5-16.Define loggers in a Python module

清单 5-16 中用于getLogger的 Python __name__语法自动将包名指定为记录器名。这意味着，如果在应用目录coffeehouse/about/views.py下的模块中定义了记录器，记录器将获得名称coffeehouse.about.views。因此，依靠__name__语法，基于日志消息的来源自动创建记录器。

不要担心 Django 项目中的每个模块或.py文件都有几十或几百个记录器。如前一节所述，Python 日志记录与继承一起工作，因此您可以为父日志记录器(例如，coffeehouse)定义一个处理程序来处理所有子日志记录器(例如，coffeehouse.about、coffeehouse.about.views、coffeehouse.drinks、coffeehouse.drinks.models)。

有时，定义一个带有明确名称的日志记录器来对某些类型的消息进行分类是很方便的。在清单 5-16 中，您可以看到一个名为dba的日志记录器，用于记录与数据库问题相关的消息。这样，数据库管理员可以查阅自己的日志流，而不需要查看来自应用其他部分的日志消息。

一旦模块或.py文件中有了记录器，就可以根据需要报告的消息的严重程度，用几种方法中的一种来定义日志消息。下面的列表说明了这些方法:

<logger_name>。关键()。-最严重的日志记录级别。使用它来报告潜在的灾难性应用事件(例如，可能导致应用暂停或崩溃的事件)。</logger_name>
<logger_name>。错误()。-第二严重的日志记录级别。使用它来报告重要事件(例如，导致最终用户看到错误的意外行为或情况)。</logger_name>
<logger_name>。警告()。-中级日志级别。使用它来报告相对重要的事件(例如，不应该发生的意外行为或情况，但不会导致最终用户注意到该问题)。</logger_name>
<logger_name>。信息()。-信息记录级别。使用它来报告应用中的信息性事件(例如，应用里程碑或用户活动)。</logger_name>
<logger_name>。调试()。-调试日志记录级别。使用它来报告难以编写的分步逻辑(例如，复杂的业务逻辑或数据库查询)。</logger_name>
<logger_name>。日志()。-使用它手动发出特定日志级别的日志消息。</logger_name>
<logger_name>。异常()。-使用它来创建错误级别日志记录消息，用当前异常堆栈包装。</logger_name>

您使用什么方法来记录项目中的消息完全取决于您自己。就日志记录级别而言，只要尽量与选择标准保持一致即可。您可以随时调整运行时日志记录级别，以停用特定级别的日志消息。

此外，我还建议您尽可能使用最具描述性的日志消息来最大化日志记录的好处。清单 5-17 展示了使用几种日志记录方法和消息的一系列例子。

# Python logging package
import logging

# Standard instance of a logger with __name__
stdlogger = logging.getLogger(__name__)

# Custom instance logging with explicit name
dbalogger = logging.getLogger('dba')

def index(request):
    stdlogger.debug("Entering index method")

def contactform(request):
    stdlogger.info("Call to contactform method")

    try:
         stdlogger.debug("Entering store_id conditional block")
         # Logic to handle store_id
    except Exception, e:
         stdlogger.exception(e)

    stdlogger.info("Starting search on DB")
    try:
         stdlogger.info("About to search db")
         # Loging to search db
    except Exception, e:
         stdlogger.error("Error in searchdb method")
         dbalogger.error("Error in searchdb method, stack %s" % (e))

Listing 5-17.Define log messages in a Python module

正如您在清单 5-17 中看到的，使用清单 5-16 中描述的两个日志记录器，有不同级别的各种日志消息。日志消息根据它们在方法体或 try/except 块中的级别展开。

如果您将清单 5-17 中的记录器和日志语句放在 Django 项目中，您会发现在日志方面什么也没有发生！事实上，您将在控制台中看到的是形式为'No handlers could be found for logger ...<logger_name>'的消息。

这是因为默认情况下 Django 不知道任何关于你的记录器的事情！它只知道清单 5-15 中描述的默认记录器。在下一节中，我将描述如何创建一个定制的LOGGING配置，这样您就可以看到您的项目日志消息。

自定义日志记录

由于 Django 日志中有四种不同的组件可以混合使用(即日志记录器、处理程序、过滤器和格式化程序)，因此创建定制日志配置的变化几乎是无穷无尽的。

在接下来的部分中，我将描述 Django 项目的一些最常见的定制日志配置，包括覆盖默认的 Django 日志行为(例如，不发送电子邮件)，定制日志消息的格式，以及将日志输出发送到不同的记录器(例如，文件)。

清单 5-18 展示了一个定制的LOGGING配置，您可以将它放在一个项目的settings.py文件中，涵盖了这些常见的需求。接下来的部分解释了每个配置选项。

LOGGING = {
    'version': 1,
    'disable_existing_loggers': True,
    'filters': {
        'require_debug_false': {
            '()': 'django.utils.log.RequireDebugFalse',
        },
        'require_debug_true': {
            '()': 'django.utils.log.RequireDebugTrue',
        },
    },
    'formatters': {
        'simple': {
            'format': '[%(asctime)s] %(levelname)s %(message)s',
            'datefmt': '%Y-%m-%d %H:%M:%S'
        },
        'verbose': {
            'format': '[%(asctime)s] %(levelname)s [%(name)s.%(funcName)s:%(lineno)d] %(message)s',
            'datefmt': '%Y-%m-%d %H:%M:%S'
        },
    },
    'handlers': {
        'console': {
            'level': 'DEBUG',
            'filters': ['require_debug_true'],
            'class': 'logging.StreamHandler',
            'formatter': 'simple'
        },
        'development_logfile': {
            'level': 'DEBUG',
            'filters': ['require_debug_true'],
            'class': 'logging.FileHandler',
            'filename': '/tmp/django_dev.log',
            'formatter': 'verbose'
        },
        'production_logfile': {
            'level': 'ERROR',
            'filters': ['require_debug_false'],
            'class': 'logging.handlers.RotatingFileHandler',
            'filename': '/var/log/django/django_production.log',
            'maxBytes' : 1024*1024*100, # 100MB
            'backupCount' : 5,
            'formatter': 'simple'
        },
        'dba_logfile': {
            'level': 'DEBUG',
            'filters': ['require_debug_false','require_debug_true'],
            'class': 'logging.handlers.WatchedFileHandler',
            'filename': '/var/log/dba/django_dba.log',
            'formatter': 'simple'
        },
    },
    'root': {
        'level': 'DEBUG',
        'handlers': ['console'],
    },
    'loggers': {
        'coffeehouse': {
            'handlers': ['development_logfile','production_logfile'],
         },
        'dba': {
            'handlers': ['dba_logfile'],
        },
        'django': {
            'handlers': ['development_logfile','production_logfile'],
        },
        'py.warnings': {
            'handlers': ['development_logfile'],
        },
    }
}
Listing 5-18.Custom LOGGING Django configuration

Caution

使用日志文件时，请确保目标文件夹存在(例如/var/log/dba/)，并且 Django 进程的所有者拥有文件访问权限。

禁用默认 Django 日志记录配置

清单 5-18 顶部的' disable_existing_loggers' :True语句禁用清单 5-15 中 Django 的默认日志配置。这保证了没有默认的日志行为被应用到 Django 项目中。

禁用 Django 默认日志记录行为的另一种方法是在单个基础上覆盖默认日志记录定义，因为settings.py中的任何显式LOGGING配置优先于 Django 默认配置，即使在'disable_existing_loggers':False时也是如此。例如，要对console记录器应用不同的行为(例如，输出debug级别的消息，而不是默认的info级别),您可以在settings.py中为具有debug级别的console定义一个处理程序——如清单 5-18 所示。

但是，如果您想确保没有默认的日志配置意外地出现在 Django 项目中，您必须将'disable_existing_loggers'设置为True。因为清单 5-18 设置了'disable_existing_loggers':True，注意清单 5-15 中相同的默认过滤器被重新声明，因为默认过滤器由于'disable_existing_loggers':True.而丢失

日志格式化程序:消息输出

默认情况下，Django 没有定义一个日志记录formatters部分，您可以在清单 5-15 中确认。然而，清单 5-18 声明了一个formatters部分来生成带有更简单或更详细输出的日志消息。

默认情况下，所有 Python 日志消息都遵循格式%(levelname)s:%(name)s:%(message)s，这意味着“输出日志消息级别，后跟日志记录器的名称和日志消息本身。”

然而，通过 Python 日志记录可以获得更多的信息，从而使日志消息更加全面。正如您在清单 5-18 中看到的，simple和verbose格式化程序使用了一种特殊的语法和一系列不同于默认的字段。表 5-2 说明了不同的 Python 格式化程序字段，包括它们的语法和含义。

表 5-2。

Python logging formatter fields

| 字段语法 | 描述 | | --- | --- | | %(名称)s | 记录器的名称(记录通道) | | %（级别）s | 消息的数字日志记录级别(调试、信息、警告、错误、严重) | | %(levelname)s | 消息的文本日志记录级别(“调试”、“信息”、“警告”、“错误”、“严重”) | | %(路径名)s | 发出日志记录调用的源文件的完整路径名(如果可用) | | %(文件名)s | 路径名的文件名部分 | | %(模块)s | 模块(文件名的名称部分) | | %（lineno）d | 发出日志记录调用的源代码行号(如果可用) | | %(funcName)s | 函数名 | | %(已创建)f | 创建日志记录的时间(time.time()返回值) | | %（asctime）s | 创建日志记录的文本时间 | | %(毫秒)d | 创建时间的毫秒部分 | | %(相对创建的)d | 创建日志记录的时间(以毫秒为单位)，相对于加载日志记录模块的时间(通常在应用启动时) | | %(线程)d | 线程 ID(如果可用) | | %（线程名称） | 线程名称(如果可用) | | %(流程)d | 流程 ID(如果可用) | | %(消息)s | record.getMessage()的结果，在发出记录时进行计算 |

您可以根据表 5-2 中的字段向每个formatter的format字段添加或删除字段。除了每个formatter的format字段之外，还有一个datefmt字段，允许您定制formatter中%(asctime)s格式字段的输出(例如，当datefmt字段设置为%Y-%m-%d %H:%M:%S时，如果在 2018 年午夜出现日志消息，%(asctime)输出 2018-01-01 00:00:00)。

Note

datefmt字段的语法遵循 Python 的 strftime()格式。 ²

日志处理程序:位置、类、过滤器和日志阈值

清单 5-18 中的第一个处理程序是console处理程序，它提供了默认console处理程序清单 5-15 的定制行为。清单 5-18 中的console处理程序将日志级别提升到DEBUG级别，以处理所有日志消息，而不考虑它们的级别。此外，console处理程序使用定制的simple格式化程序——在上一节中已经介绍过——并使用相同的默认console过滤器和类，它告诉 Django 在DEBUG=True(即'filters': ['require_debug_true'])时处理日志消息，并将日志输出发送到一个流(即'class': 'logging.StreamHandler')。

在清单 5-18 中，您还可以看到其余每个处理程序都有三个不同的class值:logging.FileHandler，它将日志消息发送到一个标准文件；logging.handlers.RotatingFileHandler，向根据给定阈值大小变化的文件发送日志消息；以及logging.handlers.WatchedFileHandler，它将日志消息发送到由第三方工具管理的文件中(例如，logrotate)。

development_logfile处理程序被配置为处理比DEBUG(包含)更差的日志消息——从技术上讲是所有日志消息——并且由于require_debug_true过滤器，只有当DEBUG=True时才工作。此外，development_logfile处理程序被设置为使用自定义的verbose格式化程序，并将输出发送到/tmp/django_dev.log文件。

production_logfile处理程序被配置为处理比ERROR(含)更差的日志消息——这只是ERROR和CRITICAL日志消息——并且由于require_debug_false过滤器，只有当DEBUG=False时才工作。此外，该处理程序使用自定义的simple格式化程序，并被设置为将输出发送到文件/var/log/django_production.log。每当日志文件达到 100 MB(即maxBytes)时，日志文件就会旋转，旧的日志文件会通过附加一个数字(例如django_production.log.1,django_production.log.2)备份到backupCount。

由于使用了require_debug_true和require_debug_false过滤器，dba_logfile被配置为处理比DEBUG(包括 ??)更差的日志消息——从技术上讲，?? 是所有日志消息——以及当DEBUG=True或DEBUG=False出现时。此外，该处理程序使用自定义的simple格式化程序，并被设置为将输出发送到文件/var/log/django_dba.log。

dba_logfile处理程序由WatchedFileHandler类管理，它比development_logfile处理程序使用的基本FileHandler类功能多一点。WatchedFileHandler类被设计用来检查一个文件是否改变，如果它改变了一个文件被重新打开；这反过来允许日志文件由 logrotate 之类的 Linux 日志实用程序管理/更改。像 logrotate 这样的日志实用程序的好处是，它允许 Django 使用更复杂的日志文件特性(例如，压缩、日期旋转)。注意，如果不使用像 logrotate 这样的第三方工具来管理使用WatchedFileHandler的日志文件，日志文件会无限增长。

Caution/Tip

清单 5-18 中的 RotatingFileHandler 日志处理类对于多进程应用来说是不安全的。使用 ConcurrentLogHandler 日志处理程序类 ³ 在多进程应用上运行。

Tip

核心 Python 日志包包括许多其他日志处理程序类，用于处理 Unix 系统日志、电子邮件(SMTP)和 HTTP 之类的消息。 ⁴

日志记录器:使用日志记录的 Python 包

清单 5-18 中的loggers部分定义了附加到 Python 包的处理程序——从技术上来说，附件是附加到记录器名称上的，但是我使用这个术语是因为记录器通常以 Python 包命名。我将很快提供这个“Python 包=记录器名称”的一个例外，这样您可以更好地理解这个概念。

第一个日志记录器coffeehouse告诉 Django 将自己及其子节点(例如coffeehouse.about、coffeehouse.about.views和coffeehouse.drinks)的所有日志消息附加到development_logfile和production_logfile处理程序。通过分配两个处理程序，来自coffeehouse记录器(及其子进程)的日志消息被发送到两个地方。

回想一下，通过使用 Python 的__name__语法来定义记录器——参见清单 5-16 和 5-17——记录器的名称最终基于 Python 包结构。

接下来，您可以看到dba记录器将其所有日志消息链接到dba_logfile处理程序。在这种情况下，记录器以 Python 包命名的规则是一个例外。正如你在清单 5-17 中看到的，一个日志记录器可以被特意命名为dba，而放弃使用__name__或其他与 Python 包相关的约定。

接下来，django和py.warnings记录器被重新声明以获得 Django 的一些默认行为，假设清单 5-18 使用了'disable_existing_loggers': True。django日志记录器将其所有日志消息链接到development_logfile和production_logfile处理程序，因为我们希望与django包/日志记录器及其子项(例如django.request、django.security)相关的日志消息进入两个日志文件。

注意清单 5-18 没有为django.request和django.security声明显式的记录器，不像清单 5-15 中的 Django 默认值。因为django记录器自动处理其子代，我们不需要每个记录器有不同的处理程序——就像默认的日志行为——清单 5-18 只声明了django记录器。

在清单 5-18 的末尾，py.warnings记录器将其所有日志消息链接到development_logfile处理器，以避免py.warnings日志消息在生产日志中留下任何痕迹。

最后，清单 5-18 中有一个root键，虽然它是在loggers部分之外声明的，但实际上是所有记录器的根记录器。root键告诉 Django 处理来自所有记录器的消息——无论在配置中是否声明——并以给定的方式处理它们。在这种情况下，root告诉 Django 所有日志消息——因为DEBUG级别包括所有消息——由任何日志记录器(coffeehouse, dba, django, py.warnings或任何其他)生成，由console处理程序处理。

出错时禁止向管理员发送电子邮件

您可能会感到惊讶，清单 5-18 没有使用清单 5-15 中默认定义的mail_admins处理程序。正如我在上一节关于 Django 默认日志记录中提到的，对于由django.request或django.security包/记录器生成的日志消息，mail_admins处理程序发送一个电子邮件错误通知。

虽然这看起来是一个令人惊奇的特性——避免了查看日志文件的麻烦——但是一旦项目开始增长，它就会变得非常不方便。默认日志电子邮件错误通知机制或mail_admins处理程序的问题是，每当触发与django.request或django.security软件包/日志程序相关的错误时，它都会发送一封电子邮件。

如果一个 Django 站点每小时有 100 个访问者，并且他们都遇到了同样的错误，这意味着在同一小时内发送了 100 封电子邮件通知。如果你在ADMINS有 3 个人，那么就意味着每小时至少有 300 封邮件通知。所有这些很快就会累积起来，所以几个不同的错误和一天几千个访问者会导致电子邮件超载。因此，尽管获取电子邮件日志错误通知看起来很方便，但您应该关闭此功能。

我建议您坚持使用老方法来持续检查日志文件，或者如果您需要通过电子邮件提供相同的实时日志错误通知，您可以使用专用的报告系统，如 Sentry，这将在下一节中介绍。

哨兵伐木

尽管日志记录是一种强大的发现机制，但检查和理解日志消息可能是一项艰巨的任务。Django 和 Python 项目在这方面没有什么不同。如前一节所述，依赖核心日志记录包仍然会导致日志消息被发送到应用控制台或文件，其中理解日志消息(例如，最相关或最常见的日志消息)可能会导致数小时的分析。

进入 Sentry，一个报告和聚合应用。Sentry 通过一个基于 web 的界面方便了日志消息的检查，在这里您可以快速确定最相关和最常见的日志消息。

要使用 Sentry，您需要遵循两个步骤:设置 Sentry 接收您的项目日志消息，并设置您的 Django 项目向 Sentry 发送日志消息。

Why Sentry?

尽管有替代产品提供与 Sentry 类似的日志监控功能(例如 OverOps、Airbrake、Raygun)，但让 Sentry 与众不同的是它是作为 Django 应用构建的！

尽管 Sentry 已经发展到了非常复杂的 Django 应用的地步，但 Sentry 是基于 Django 的开源项目这一事实使得它几乎成为监控 Django 项目的自然选择，因为您可以使用您的 Django 知识来安装和扩展它——尽管有软件即服务 Sentry 的替代方案。

设置岗哨的申请

您可以通过两种方式设置 Sentry:自己安装或使用软件即服务 Sentry 提供商。

Sentry 是一个 Django 开源项目，因此所有人都可以免费获得完整的源代码。 ⁵ 但是在你直接下载 Sentry 并继续安装之前， ⁶ 当心 Sentry 已经从它的 Django 根成长了相当大。Sentry 现在需要一个 Docker 环境、关系 Postgres 数据库和 NoSQL Redis 数据库。不幸的是，Sentry 发展到支持各种各样的编程语言和平台，它变得越来越复杂，不再是一个简单的 Django 应用安装。因此，如果你从头开始安装 Sentry，预计要花几个小时来设置它。

Tip

早期的 Sentry 版本(例如，v. 5.0 ⁷ )没有这样严格的依赖关系，可以像基本的 Django 应用一样运行(例如，任何 Django 关系数据库，没有 Docker，没有 NoSQL 数据库)。对于简单的哨兵安装来说，它们是一个很好的选择，尽管它们需要过时的 Django 版本(例如 v. Django 1.4)。

哨兵创建者和维护者运行软件即服务: https://sentry.io 。Sentry 软件即服务提供三种不同的计划:爱好者计划，每月免费参加多达 10，000 次活动，专为一个用户设计；每月 12 美元的专业计划，从每月 50，000 次活动开始，为无限用户设计；以及针对数百万事件和无限用户的定制定价的企业计划。

由于你可以在几分钟内免费设置 Sentry，只需你的电子邮件——无需信用卡——来自 https://sentry.io 的 Sentry 软件即服务是试用 Sentry 的一个好选择。即使在试用后，每月 50，000 次活动的成本为 12 美元，每次额外活动的成本为 0.00034 美元，这也是一个很好的价值-考虑到一个每月生成 50，000 次活动的应用应该有相当多的受众来证明这个价格是合理的。

一旦你创建了一个 sentry.io 帐户，你将进入主仪表板。创建新的 Django 项目。注意客户端密钥或 DSN，它是一个包含@sentry.io 片段的长 url 这是配置 Django 项目向这个特定的 Sentry Django 项目发送日志消息所必需的。如果您错过了项目客户端密钥或 DSN，请点击图 5-1 中所示的右上角“项目设置”按钮，并选择左下角选项“客户端密钥(DSN)”以查看该值。

图 5-1。

Sentry SaaS project dashboard

正如你在图 5-1 中所看到的，哨兵 SaaS 项目仪表板作为一个中央存储库来查阅所有的项目日志记录活动。在图 5-1 中，您还可以看到各种操作按钮，这些按钮允许不同用户对日志消息进行分类、搜索、绘制图表以及管理。所有这些创建了一个非常高效的环境，可以在其中实时分析任何 Django 日志记录活动。

一旦设置了 Sentry，就可以配置 Django 项目向 Django 项目发送日志消息。

设置 Django 应用来使用 Sentry

要在 Django 项目中使用 Sentry，您需要一个名为 Raven 的包来建立双方之间的通信。简单地做pip install raven来安装最新的 Raven 版本。

一旦安装了 Raven，就必须在项目的settings.py文件的INSTALLED_APPS列表中声明它，如清单 5-19 所示。此外，还需要通过清单 5-19 中显示的RAVEN_CONFIG变量，配置 Raven 通过 DSN 值与特定的 Sentry 项目通信。

INSTALLED_APPS = [
    ...
    'raven.contrib.django.raven_compat',
    ...
]

RAVEN_CONFIG = {
    'dsn': '<your_dsn_value>@sentry.io/<your_dsn_value>',
}

Listing 5-19.Django project configuration to communicate

with Sentry via Raven

正如您在清单 5-19 中所看到的，RAVEN_CONFIG变量应该声明一个dsn键，其值对应于 Sentry 项目中接收日志消息的 DSN 值。

在设置了这个最低限度的 Raven 配置之后，您可以从 Django 项目的命令行发送运行python manage.py raven test命令的测试消息。如果测试成功，您将在如图 5-1 所示的 Sentry 仪表盘中看到一条测试消息。

一旦您确认 Django 项目和 Sentry 之间的通信成功，您就可以设置 Django 日志来向 Sentry 发送日志消息。对于 Django 的日志记录机制，Sentry 被视为任何其他处理程序(例如文件、流)，因此您必须首先使用raven.contrib.django.handlers.SentryHandler类将 Sentry 声明为日志记录处理程序，如清单 5-20 所示。

LOGGING = {
...
'handlers': {
       ....
        'sentry': {
            'level': 'ERROR',
            'class': 'raven.contrib.django.handlers.SentryHandler',
        },
       ...
  }
Listing 5-20.Django logging handler

for Sentry/Raven

清单 5-20 中的sentry处理程序告诉 Django 通过 Sentry 处理具有ERROR级别的日志消息。一旦有了 Sentry 处理程序，最后一步是使用 loggers 上的sentry处理程序来分配哪些包/loggers 通过 Sentry 处理(例如，django.request或root logger，如前面的“日志记录器”一节所述)。

Django 电子邮件服务

电子邮件已经成为生活在网络上的几乎所有应用的主要部分。无论应用是否需要发送电子邮件来注册、通知或确认购买，很难想象 web 应用不需要某种电子邮件功能。

对于 Django 项目，设置电子邮件有两个主要方面。第一步是建立与电子邮件服务器的连接，第二步是撰写电子邮件。

设置到电子邮件服务器的默认连接

Django 支持连接到任何电子邮件服务器，还提供了各种选项来模拟电子邮件服务器连接。电子邮件模拟在开发和测试期间尤其强大，因为在这期间发送真实的电子邮件是不必要的。Django 电子邮件服务器的设置在settings.py中完成。根据电子邮件服务器的连接，您可能需要在settings.py中设置几个变量。表 5-3 显示了 Django 的各种电子邮件服务器选项。

表 5-3。

Django email server configurations

| Django 电子邮件后端 | 配置 | 描述/注释 | | --- | --- | --- | | 用于开发(调试=真) | | 控制台电子邮件 | EMAIL _ back end = ' django . core . mail . back ends . console . EMAIL back end ' | 将所有电子邮件输出发送到运行 Django 的控制台。 | | 文件电子邮件 | ' EMAIL _ back end = ' django . core . mail . backends . FILE based . EMAIL back end ' EMAIL _ FILE _ PATH = '/tmp/django-EMAIL-dev ' | 将所有电子邮件输出发送到电子邮件文件路径中指定的平面文件。 | | 内存电子邮件 | EMAIL _ back end = ' django . core . mail . backends . locmem . EMAIL back end ' | 将所有电子邮件输出发送到 django.core.mail.outbox 中的内存属性。 | | 取消电子邮件 | EMAIL _ back end = ' django . core . mail . backends . dummy . EMAIL back end ' | 不处理所有电子邮件输出。 | | Python 电子邮件服务器模拟器 | EMAIL _ back end = ' django . core . mail . backends . SMTP . EMAIL back end ' EMAIL _ HOST = 127 . 0 . 0 . 1 EMAIL _ PORT = 2525 还需要 Python 命令行电子邮件服务器:Python-m smtpd-n-c debuggings server localhost:2525 | 将所有电子邮件输出发送到通过命令行设置的 Python 电子邮件服务器。这类似于控制台电子邮件选项，因为 Python 电子邮件服务器将内容输出到控制台。 | | 用于生产(调试=假) | | SMTP 电子邮件服务器(标准) | EMAIL _ back end = ' django . core . mail . backends . SMTP . EMAIL back ends '¹EMAIL _ HOST = 127 . 0 . 0 . 1¹EMAIL _ PORT = 25²EMAIL _ HOST _ USER =²EMAIL _ HOST _ PASSWORD = | 将所有电子邮件输出发送到 SMTP 电子邮件服务器。 | | SMTP 电子邮件服务器( ^* Secure-TLS) | EMAIL _ back end = ' django . core . mail . backends . SMTP . EMAIL back ends '¹EMAIL _ HOST = 127 . 0 . 0 . 1¹EMAIL _ PORT = 587²EMAIL _ HOST _ USER =²EMAIL _ HOST _ PASSWORD =EMAIL _ USE _ TLS = True | 将所有电子邮件输出发送到安全的 SMTP (TLS)电子邮件服务器。 | | SMTP 电子邮件服务器( ^* 安全-SSL) | EMAIL _ back end = ' django . core . mail . backends . SMTP . EMAIL back ends '¹EMAIL _ HOST = 127 . 0 . 0 . 1¹EMAIL _ PORT = 465²EMAIL _ HOST _ USER =²EMAIL _ HOST _ PASSWORD =EMAIL _ USE _ SSL = True | 将所有电子邮件输出发送到安全的 SMTP (SSL)电子邮件服务器。 |

¹ If the SMTP email server is running on a network or a different port than the default, adjust EMAIL_HOST and EMAIL_PORT accordingly. ² In today’s email, spam-infested Internet, nearly all SMTP email servers require authentication to send email. If your SMTP server doesn’t require authentication you can omit EMAIL_HOST_USER and EMAIL_HOST_PASSWORD. ^* The terms SSL and TLS are often used interchangeably or in conjunction with each other (TLS/SSL). There are differences, though, in terms of their underlying protocol. From a Django setup prescriptive, you only need to ensure what type of secure email server you connect to, as they operate differently and on different ports.

您在settings.py中的表格 5-3 中设置的任何电子邮件连接都被视为 Django 项目的默认连接，并在执行任何与电子邮件相关的任务时使用——除非您在执行电子邮件任务时另外指定。

设置到第三方电子邮件提供商的默认连接

上一节提供了在 Django 中设置到电子邮件服务器的默认连接的最通用的方法。然而，由于当今世界运行电子邮件服务器的复杂性——即垃圾邮件过滤和安全问题——使用第三方服务将来自 Django 项目的电子邮件转发给外界可能会更容易、更实用。

尽管您可以使用上一节的配置连接到任何第三方电子邮件服务，但是设置第三方电子邮件服务的配置还是有一些微妙之处。在这一节中，我将提供我认为最流行的三种第三方电子邮件服务的 Django 配置细节。

Django with Exim, Postfix, or Sendmail

虽然您可以设置 Django 将电子邮件发送到本地电子邮件应用(即运行在 127.0.0.1 上)，如 Exim、Postfix 或 Sendmail，然后这些应用将电子邮件发送到第三方提供商。我个人不推荐这种替代方案，因为它增加了另一个组件来设置、维护和担心。更不用说这超出了 Django 的范围，因为它涉及到用第三方电子邮件服务设置不同的电子邮件应用。

以下部分描述了如何设置 Django 直接与第三方电子邮件提供商连接。

使用 Google Gmail/Google Apps 发送电子邮件

谷歌提供通过 Gmail 或谷歌应用发送电子邮件的能力，最后一个是用于定制域(如 coffeehouse.com)的 Gmail 版本。一旦你有了 Gmail 或 Google Apps 帐户，你需要在settings.py中设置帐户的用户名/密码凭证。

如果不在你的应用中的某个地方硬编码你的账户凭证，你将无法使用谷歌的电子邮件服务。如果您厌倦了对settings.py中的用户名/密码凭证进行硬编码，我建议您为此创建一个单独的帐户来限制漏洞，考虑使用 Django 的多个环境或配置文件来将用户名/密码保存在不同的文件中，或者使用前一个侧栏中描述的凭证设置一个本地电子邮件服务器。

清单 5-21 展示了设置 Django 通过 Gmail 或 Google Apps 账户发送电子邮件所需的配置。

EMAIL_BACKEND='django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST='smtp.gmail.com'
EMAIL_PORT=587
EMAIL_HOST_USER='username@gmail.com/OR/username@coffeehouse.com'
EMAIL_HOST_PASSWORD='password'
EMAIL_USE_TLS=True
Listing 5-21.Django email configuration for Gmail or Google Apps account

正如你在清单 5-21 中看到的，配置参数与表 5-3 中描述的非常相似。这就是在 Django 中设置 Gmail 或 Google Apps 的默认电子邮件连接所需的全部内容。

Caution

当心用谷歌发太多邮件。由于谷歌的电子邮件服务是免费的，它不是为转发太多电子邮件而设计的。如果你的 Django 应用每小时发送几封电子邮件，你可能不会有问题，但如果你的应用每秒发送一封电子邮件，或者在几分钟内发送数百封电子邮件，该帐户可能会被封。如果帐户被阻止，您将需要等待几个小时或手动登录帐户(例如，通过浏览器)以解除阻止。如果该帐户由于您发送的电子邮件数量而不断被阻止，您应该尝试另一个电子邮件服务提供商。

Note

Google 会用 Google 帐户值覆盖 From: email 字段，除非它是作为别名添加的。Django 允许您将电子邮件的 From:字段设置为您想要的任何值，并默认为 settings.py 中的 EMAIL_HOST_USER 值。但是，为了避免欺骗，如果 From: email 值不是 Gmail 或 Google App 帐户中的别名，Google 会将该字段覆盖到 Google 帐户电子邮件中。这意味着，如果你在 Django 中发送一封发件人:support@coffeehouse.com 的电子邮件，并且该电子邮件没有在 Gmail 或谷歌应用帐户中设置为别名，则最终的电子邮件会显示为谷歌帐户的主电子邮件。

使用亚马逊简单电子邮件服务(SES)发送电子邮件

SES 是由 Amazon.com 运营的 AWS 提供的另一项电子邮件服务。与谷歌的电子邮件服务不同，SES 是一项付费服务，每封电子邮件的平均成本为 0.0001 美分(每 1000 封电子邮件 10 美分)。用 SES 设置 Django 最简单的方法是通过 Python 库 boto 和一个名为 django-ses 的自定义 Django 电子邮件后端。

清单 5-22 说明了安装 boto 的 pip 要求，boto 是一个使用 Python 和 django-ses 集成多个 AWS 服务的库，django-ses 是一个开源项目，专门设计用于使用 Django 运行 SES。

pip install boto
pip install django-ses
Listing 5-22.Python pip requirements for Amazon.com SES with Django

一旦您使用 pip 安装了清单 5-22 中的 Python 包，您就可以继续在settings.py中配置 SES。清单 5-23 展示了设置 Django 使用 SES 的必要变量。

EMAIL_BACKEND = 'django_ses.SESBackend'
AWS_ACCESS_KEY_ID = 'FZINISSZ3542DPIO32CQ'
AWS_SECRET_ACCESS_KEY = '3Nto4vknl+xeZR+1tF3L645EUyOS+zZy/uPJ1rN'
Listing 5-23.Django email configuration for Amazon.com SES

正如您在清单 5-23 中看到的，变量EMAIL_BACKEND被设置为自定义类django_ses.SESBackend，它提供了连接 SES 所需的所有钩子。

要连接到 SES，您还需要提供变量AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY，这是与您的 AWS 帐户相关的访问凭证。这些最后的值在您的 AWS 帐户中提供.. ⁸

这就是你需要设置一个默认的电子邮件连接到亚马逊简单电子邮件服务(SES)的全部内容。不需要在settings.py中设置任何其他变量，例如EMAIL_HOST或EMAIL_HOST_USER——一切都由自定义电子邮件后端处理。

带有 SparkPost 的电子邮件

SparkPost 是 Twitter、Oracle 和 PayPal 等大公司使用的另一种第三方电子邮件服务。Pricing wise SparkPost 是前两种服务的混合体；每月前 100，000 封电子邮件是免费服务，但在此之后，这是一项付费服务，平均每封电子邮件的费用为 0.0002 美分(每月接下来的 1000 封电子邮件为 20 美分)，一旦每月发送 100 万封电子邮件，每封电子邮件的费用会更低。

用 SparkPost 设置 Django 最简单的方法是直接在清单settings.py.中 5-24 展示了设置 Django 使用 SparkPost 的必要变量。

EMAIL_BACKEND='django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'smtp.sparkpostmail.com'
EMAIL_PORT = 587
EMAIL_HOST_USER = 'SMTP_Injection'
EMAIL_HOST_PASSWORD = '<sparkpost_api_key>'
EMAIL_USE_TLS = True
Listing 5-24.Django email configuration for SparkPost

正如您在清单 5-24 中看到的，配置参数与表 5-3 中描述的标准电子邮件连接非常相似。请注意，除了EMAIL_HOST_USER值为SMTP_Injection——SparkPost 的要求——您还需要为EMAIL_HOST_PASSWORD分配一个 SparkPost API 键。SparkPost API 密钥是在您的 SparkPost 帐户中创建的。 ⁹

既然您已经了解了在 Django 项目中建立电子邮件连接的各种方法，那么让我们来研究一下电子邮件的实际组成。

内置助手发送电子邮件

发送电子邮件可能涉及许多选项和步骤。为了简化这个过程，Django 提供了四种快捷方法，您可以在应用的任何地方使用(例如，注册时、购买时、出现严重错误时)。表 5-4 说明了各种电子邮件快捷方式。

表 5-4。

Django email shortcut methods

| 快捷方式和描述 | 带所有参数的快捷方式* | 参数描述和注释 | | --- | --- | --- | | send_mail 是发送电子邮件最常见的选项。 | send_mail(主题，消息，from _ email =设置。DEFAULT_FROM_EMAIL，recipient_list，fail _ silently = False，auth_user=None，auth_password=None，connection=None，html_message=None) | 主题。-电子邮件主题字符串。消息。-电子邮件消息字符串。from_email。-电子邮件发件人:字段。如果没有提供，它会从 settings.py 设置为 DEFAULT_FROM_EMAIL，默认情况下是 webmaster@localhost。收件人 _ 列表。-字符串列表形式的电子邮件收件人。无声地失败。-能够在无法发送电子邮件时绕过错误。默认情况下设置为 False，这意味着任何试图发送电子邮件的错误都会引发一个 smtplib。SMTPException 异常。auth_user。SMTP 服务器的身份验证用户。如果提供，它将覆盖 settings.py. auth_password 中的变量 EMAIL_HOST_USER。SMTP 服务器的身份验证密码。如果提供，它将覆盖 settings.py. connection 中的变量 EMAIL_HOST_PASSWORD。- Django 电子邮件后端发送邮件。如果提供，它会覆盖 settings.py 中的变量 EMAIL_BACKEND。有关选项，请参见表 5-3 。html_message。-发送 HTML 和文本电子邮件消息的 HTML 字符串。如果提供，生成的电子邮件是多部分/替代电子邮件，其中 message 为文本/纯文本内容类型，html_message 为文本/html 内容类型。 | | send_mass_mail 比 send_mail 方法效率更高。这是发送多封电子邮件时的首选，因为它会打开到电子邮件服务器的单个连接，并发送元组中包含的所有消息。请注意，send_mass_mail 不支持 send_mail 这样的 HTML 消息。 | send_mass_mail(datatuple，fail _ silently = False，auth_user=None，auth_password=None，connection=None) | 数据元组。-是一个元组，包含以(subject，message，from_email=settings)形式表示电子邮件结构的元组。DEFAULT_FROM_EMAIL，recipient_list)。 | | mail_admins 向 settings.py 的 admins 变量中定义的所有用户发送电子邮件。 | mail_admins(subject，message，fail _ silently = False，connection=None，html_message=None) | 发送电子邮件时，会将 From:字段设置为 settings.py 中的变量 SERVER_EMAIL，默认情况下是 root@localhost。电子邮件主题的前缀是 settings.py 中的变量 EMAIL_SUBJECT_PREFIX，默认情况下是'[Django]'。 | | mail_managers 向 settings.py 的 managers 变量中定义的所有用户发送电子邮件。 | mail_managers(subject，message，fail _ silently = False，connection=None，html_message=None) | 发送电子邮件时，会将 From:字段设置为 settings.py 中的变量 SERVER_EMAIL，默认情况下是 root@localhost。电子邮件主题的前缀是 settings.py 中的变量 EMAIL_SUBJECT_PREFIX，默认情况下是'[Django]'。 |

Method arguments without a default value (e.g. subject,message) must always be provided. Method arguments with a default value (e.g. fail_silently=False, connection=None) are optional. Note

如果一旦项目进入生产阶段，你就开始收到带有错误信息的电子邮件(例如，DEBUG=False)，这是因为 mail_admins 快捷方式是自动连接的。这是由于 Django 的默认日志工作方式造成的。要禁用此行为，您需要清除 settings.py 中 ADMINS 的所有值，或者覆盖默认的日志记录行为，如上一节日志记录中所述。

自定义电子邮件:电子邮件的附件、标题、抄送、密件抄送等

虽然以前的电子邮件快捷方式可以在大多数情况下使用，但它们不支持附件、抄送、密件抄送或其他电子邮件标题。如果你想完全控制在 Django 中发送电子邮件，前面的快捷方式是行不通的。

Django EmailMessage类被以前的 Django 快捷方法“秘密”使用，并为在 Django 中发送电子邮件提供了最大的灵活性。表 5-5 中描述了EmailMessage类支持的各种参数和方法。

表 5-5。

Django EmailMessage class parameters and methods

| 参数和/或方法 | 描述 | | --- | --- | | 科目 | 电子邮件的主题行。 | | 身体 | 作为纯文本消息的正文文本。 | | 发件人电子邮件 | 发件人的地址。普通电子邮件(如`webmaster@coffeehouse.com`)和全名加电子邮件(如`Webmaster `)格式均可接受。如果省略，则使用 settings.py 中的默认发件人电子邮件值。 | | 到 | 收件人地址的列表或元组。 | | 复写的副本 | 发送电子邮件时，在电子邮件抄送标题中使用的收件人地址列表或元组。 | | 体形立方晶格 | 发送电子邮件时用作密件抄送邮件头的地址列表或元组。 | | 关系 | 电子邮件后端实例。如果希望多个消息使用同一个连接，请使用此参数。如果省略，则在调用 send()时创建一个新连接。 | | 附件 | 要放在邮件上的附件列表。这些可以是电子邮件。MIMEBase.MIMEBase 实例，或(文件名，内容，mimetype)三元组。 | | 头球 | 要放在消息上的额外标头的字典。关键字是标题名，值是标题值。调用者负责确保邮件头名称和值的格式正确无误。对应的属性是 extra_headers。 | | 发送(fail _ silently = False) | 发送消息。如果在构造电子邮件时指定了连接，则使用该连接。否则，将实例化并使用默认后端的一个实例。如果关键字参数 fail _ silently 为 True，则忽略发送消息时引发的异常。空的收件人列表不会引发异常。 | | 消息() | 当扩展 EmailMessage 类以覆盖您想要的内容并将其放入 MIME 对象时非常有用。构造一个 django.core.mail.SafeMIMEText 对象(Python 的 email 的子类。MIMEText.MIMEText 类)或保存要发送的消息的 django . core . mail . safemimemultipart 对象。 | | 收件人() | 在扩展 EmailMessage 类时非常有用，因为在发送邮件时，SMTP 服务器需要被告知完整的收件人列表。它返回邮件所有收件人的列表，无论他们是记录在“收件人”、“抄送”还是“密件抄送”属性中。 | | 附加() | 创建文件附件并将其添加到邮件中。有两种方法可以调用 attach()。你可以传递给它一个参数，就是一封电子邮件。MIMEBase.MIMEBase 实例，它直接插入到生成的消息中，或者您可以向它传递三个参数:文件名、内容和 mimetype(例如，message.attach('menu.png '，img_data，' image/png ')，其中文件名是将出现在电子邮件中的文件附件的名称，内容是将包含在附件中的数据，mimetype 是附件的可选 MIME 类型。如果省略 mimetype，MIME 内容类型将根据附件的文件名进行猜测。 | | 附加文件() | 使用文件系统中的文件创建附件。可以使用要附加的文件的路径来调用它(例如，message . attach _ fileimg/menu . png ')，也可以选择使用用于附件的 MIME 类型(例如，message . attach _ fileimg/menu . png '，' image/png ')。如果省略 MIME 类型，则根据文件名进行猜测。 |

对表 5-5 中的EmailMessage类提供的功能有了一个清晰的概念，让我们来看一些你会使用 EmailMessage 类发送电子邮件的典型案例。

清单 5-25 提供了一个基本的电子邮件示例，它使用了像 CC、BCC 这样的选项。和回复头，上一节中的 Django 电子邮件快捷方式不支持它们。

from django.core.mail.message import EmailMessage

# Build message
email = EmailMessage(subject='Coffeehouse specials', body='We would like to let you know about this week\'s specials....', from_email='stores@coffeehouse.com',
            to=['ilovecoffee@hotmail.com', 'officemgr@startups.com'], bcc=['marketing@coffeehouse.com'], cc=['ceo@coffeehouse.com']
            headers = {'Reply-To': 'support@coffeehouse.com'})

# Send message with built-in send() method
email.send()

Listing 5-25.Send basic email with EmailMessage class

正如您在清单 5-25 中看到的，EmailMessage 实例是通过指定它的各种类参数创建的。一旦完成，您只需调用send()方法来发送电子邮件。就这么简单。因为在清单 5-25 中的EmailMessage实例中没有提供连接值，Django 使用在settings.py中定义的默认后端连接。

EmailMessage send()方法的一个缺点是，每次调用它时，它都会打开一个到电子邮件服务器的连接。如果你一次发送数百或数千封电子邮件，效率会很低。根据上一节的send_mass_mail()快捷方式的精神，也可以用EmailMessage打开一个到邮件服务器的连接，发送多封邮件。清单 5-26 展示了如何通过EmailMessage使用单个连接发送多个电子邮件。

from django.core import mail
connection = mail.get_connection()

# Manually open the connection
connection.open()

# Build message
email = EmailMessage(subject='Coffeehouse specials', body='We would like to let you know about this week\'s specials....', from_email='stores@coffeehouse.com',
            to=['ilovecoffee@hotmail.com', 'officemgr@startups.com'], bcc=['marketing@coffeehouse.com'], cc=['ceo@coffeehouse.com']
            headers = {'Reply-To': 'support@coffeehouse.com'})
# Build message
email2 = EmailMessage(subject='Coffeehouse coupons', body='New coupons for our best customers....', from_email='stores@coffeehouse.com',
            to=['officemgr@startups.com','food@momandpopshop.com'], bcc=['marketing@coffeehouse.com'], cc=['ceo@coffeehouse.com']
            headers = {'Reply-To': 'support@coffeehouse.com'})

# Send the two emails in a single call
connection.send_messages([email, email2])
# The connection was already open so send_messages() doesn't close it.
# We need to manually close the connection.
connection.close()

Listing 5-26.Send multiple emails in a single connection with EmailMessage class

在清单 5-26 中，第一步是使用mail.get_connection()创建到电子邮件服务器的连接，然后使用open()方法打开连接。接下来，创建各种EmailMessage实例。一旦准备好了电子邮件实例，您就可以调用连接的send_messages()方法，该方法带有一个对应于每个EmailMessage实例的参数列表。最后，一旦发送了电子邮件，您调用连接的close()方法来断开到电子邮件服务器的连接。

另一个常见的电子邮件场景是发送 HTML 电子邮件。Django 为此提供了EmailMultiAlternatives类，它是EmailMessage类的子类。作为一个子类，这意味着你可以利用与EmailMessage相同的功能(例如，抄送、密件抄送)，但你不需要做很多工作，因为子类EmailMultiAlternatives是专门为处理多种类型的消息而设计的。清单 5-27 展示了如何使用EmailMultiAlternatives类。

from django.core.mail import EmailMultiAlternatives

subject, from_email, to = 'Important support message', 'support@coffeehouse.com', 'ceo@coffeehouse.com'
text_content = 'This is an important message.'
html_content = '
This is an important message.

'
msg = EmailMultiAlternatives(subject=subject, body=text_content, from_email=from_email, to=[to])
msg.attach_alternative(html_content, "text/html")
msg.send()

Listing 5-27.Send HTML (w/text) emails with EmailMultiAlternatives, a subclass of the EmailMessage class

清单 5-27 首先定义了所有的电子邮件字段，包括电子邮件的文本和 HTML 版本。请注意，拥有文本和 HTML 版本的电子邮件内容是常见的做法，因为不能保证最终用户会允许或能够阅读 HTML 电子邮件，所以提供文本版本作为备份。接下来，定义一个EmailMultiAlternatives类的实例；注意这些参数与那些EmailMessage类的参数是内联的。

接下来，在清单 5-27 中，您可以看到对attach_alternative方法的调用，它特定于EmailMultiAlternatives类。这个方法的第一个参数是 HTML 内容，第二个参数是对应于text/html的内容类型。最后，清单 5-27 调用send()方法——是EmailMessage类的一部分，但也是 to EmailMultiAlternatives的一部分，因为它是一个子类——来发送实际的电子邮件。

在可以保证所有终端用户都能够查看 HTML 电子邮件的受控环境(例如，公司电子邮件)中，只发送电子邮件的 HTML 版本并完全绕过文本版本可能是实用的。在这些情况下，您实际上可以直接使用EmailMesssage类，只需稍加修改。清单 5-28 展示了如何用EmailMessage类发送 HTML 电子邮件。

subject, from_email, to = 'Important support message', 'support@coffeehouse.com', 'ceo@coffeehouse.com'
html_content = '
This is an important message.

'
msg = EmailMessage(subject=subject, body=html_content, from_email=from_email, to=[to])
msg.content_subtype = "html"  # Main content is now text/html
msg.send()

Listing 5-28.Send HTML emails

with EmailMessage class

清单 5-28 看起来像一个标准的EmailMessage过程定义；然而，第四行——msg.content_subtype——是清单 5-28 与众不同的地方。如果发送的 HTML 内容没有行设置msg.content_subtype，最终用户将收到 HTML 内容的一字不差的版本(即，没有呈现 HTML 标签)。这是因为默认情况下，EmailMessage类将内容类型指定为文本。为了切换一个EmailMessage实例的默认内容类型，在第四行调用将content_subtype设置为html。通过这一更改，电子邮件内容类型被设置为 HTML，最终用户能够查看呈现为 HTML 的内容。

Beware of Just Sending Html Email Versions to the Public

虽然发送 HTML 电子邮件版本比发送文本和 HTML 电子邮件版本更快，但如果您不能确定最终用户在哪里阅读他们的电子邮件，这可能会有问题。出于安全原因，某些用户会禁用查看 HTML 电子邮件的功能，某些电子邮件产品也不能或不太擅长呈现 HTML 电子邮件。因此，如果你只是发送一个 HTML 版本的电子邮件，可能会有一部分最终用户无法看到电子邮件的内容。

由于这个原因，如果你发送电子邮件给你无法控制其环境的最终用户(即电子邮件阅读器)，最好发送文本和 HTML 电子邮件版本——如清单 5-27 所示——而不是发送清单 5-28 所示的 HTML 电子邮件版本。

发送电子邮件时的另一个常见做法是附加文件。清单 5-29 展示了如何将 PDF 附加到电子邮件中。

from django.core.mail.message import EmailMessage

# Build message
email = EmailMessage(subject='Coffeehouse sales report', body='Attached is sales report....', from_email='stores@coffeehouse.com',
            to=['ceo@coffeehouse.com', 'marketing@coffeehouse.com']
            headers = {'Reply-To': 'sales@coffeehouse.com'})
# Open PDF file
attachment = open('SalesReport.pdf', 'rb')
# Attach PDF file
email.attach('SalesReport.pdf',attachment.read(),'application/pdf')

# Send message with built-in send() method
email.send()

Listing 5-29.Send email with PDF attachment

with EmailMessage class

正如您在清单 5-29 中看到的，在创建了一个EmailMessage实例之后，您只需使用 Python 的标准open()方法打开 PDF 文件。接下来，使用来自EmailMessage的attach()方法，该方法有三个参数:文件名、文件内容和文件内容类型或 MIME 类型。最后，调用send()方法来发送邮件。

调试 Django 应用

纠正应用中意外行为的第一步通常是检查您认为有问题的源代码部分和相应的日志。有时，虽然这些审查是没有结果的，要么是因为应用变得越来越复杂，要么是因为不可预料的行为源自不太明显的位置。

在这种情况下，下一步是在工具的帮助下开始调试过程，以便更容易检测和修复问题。在接下来的章节中，我将描述一些调试 Django 应用的最流行的工具。

django Shell:Python manage . py Shell

就像 Python 的 CLI('命令行界面')shell 可以评估表达式(例如，1+3，mystring = 'django ')，django 通过python manage.py shell命令提供了自己的 shell 版本——其中manage.py是每个 Django 项目中的顶级文件。

Django 的 shell 非常有用，因为它可以自动加载项目的依赖项和应用，因此您可以评估与 Django 项目相关的表达式(例如查询、方法),而不必经历繁琐的设置过程。清单 5-30 展示了从 Django 的 shell 运行的一系列示例表达式。

[user@coffeehouse ∼]$ python manage.py shell
Python 2.7.3
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from coffeehouse.items.models import *
>>> Drink.objects.filter(item__price__lt=2).filter(caffeine__lt=100).count()
2
>>> from django.test import Client
>>> c = Client()
>>> response = c.get('/stores/1/')
>>> response.content
'<!DOCTYPE html>\n<html....
....
....
<\html>
>>> c.get('/stores/5/')
Not Found: /stores/5/
<HttpResponseNotFound status_code=404, "text/html">
Listing 5-30.Django shell sample expressions

清单 5-30 中的第一个代码片段使用from import语法来访问 Django 项目的模型类，之后对模型进行查询以验证结果。注意不需要导入额外的库或定义数据库连接；所有的依赖项和配置都是从 Django 项目本身加载的。

清单 5-30 中的第二个片段使用 Django 的测试库来模拟客户端/浏览器对/stores/1/和/stores/5/URL 的请求，之后您可以检查内容响应或 HTTP 状态代码(例如，404 Not Found)。这里再次注意，不需要启动 web 服务器或打开浏览器；您可以从 Django shell 中快速验证 Django 项目的 URL 及其响应。

Django 调试工具栏

与 Django shell 相比，Django 调试工具栏为调试 Django 应用提供了更直观的体验。Django 调试工具栏通过滑动侧边栏提供每页信息，这些信息涉及资源使用(即时间)、Django 设置、HTTP 头、SQL 查询、缓存和日志记录等。图 5-2 和 5-3 显示了 Django 调试工具栏折叠和非折叠的屏幕截图。

图 5-3。

Django debug toolbar collapsed

图 5-2。

Django debug toolbar hidden

正如您在图 5-2 中所看到的，Django 调试工具栏可以通过每个 Django 项目页面右上角的小标签来访问。图 5-3 展示了 Django 调试工具栏的折叠版本，在这里你可以看到它的各个部分；单击任何部分都会弹出一个窗口，显示每个部分的详细信息。

您可以用pip install django-debug-toolbar命令安装 Django 调试工具栏。一旦安装了django-debug-toolbar，您还需要将debug_toolbar行添加到settings.py中的INSTALLED_APPS变量中，这样 Django 就可以启用工具栏。

Note

Django 调试工具栏只有在项目使用 DEBUG=True 时才起作用。

除了 UI 工具栏，Django 调试工具栏还提供了debugsqlshell实用程序。这个实用程序的工作方式类似于 Django 的标准 shell，但是它输出与任何 Django 模型操作相关联的支持 SQL，如清单 5-31 所示。

[user@coffeehouse ∼]$ python manage.py debugsqlshell
Python 2.7.3
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from coffeehouse.items.models import *
>>> Drink.objects.filter(item__price__lt=2).filter(caffeine__lt=100).count()
SELECT COUNT(*) AS "__count"
FROM "items_drink"
INNER JOIN "items_item" ON ("items_drink"."item_id" = "items_item"."id")
WHERE ("items_item"."price" < 2.0
       AND "items_drink"."caffeine" < 100) [0.54ms]
Listing 5-31.Django debugsqlshell

sample expressions

Note

debugsqlshell 是 Django 调试工具栏的一部分；因此，必须按照前面段落中的描述进行安装(例如，pip install django-debug-toolbar并作为debug_toolbar添加到settings.py中的INSTALLED_APPS变量)。

正如您在清单 5-31 中看到的，debugsqlshell实用程序可以通过manage.py命令获得——就像 Django 的内置 shell 一样——并且在您运行 Django 模型操作之后，它还会输出操作的 SQL 查询。

关于定制 Django 调试工具栏的详细信息，请参阅其官方文档。¹⁰

Django pdb

pdb 是“Python Debugger”的缩写，是一个 Python 核心包，用于交互式调试源代码。使用 Python pdb，您可以逐行检查任何 Python 应用的执行情况。为了在 Django 应用的上下文中简化 Python pdb 的过程(例如，调试请求方法),您可以使用 Django pdb 包。

要安装 Python pdb，运行pip install django-pdb，然后在第一个位置将django_pdb添加到settings.py中的INSTALLED_APPS变量——这个位置很重要，这样其他 Django 应用就不会覆盖 Django pdb 的行为(例如，覆盖 runserver 和 test 命令)。请注意 Django pdb 包仅在DEBUG=True时有效。

用 Django 运行 pdb 有多种方法；最简单的方法是将?pdb参数附加到您想用 pdb 分析的任何 Django URL 上。例如，清单 5-32 显示了http://localhost:8000/drinks/mocha/?pdb URL 的调试序列。

[user@coffeehouse ∼]$ python manage.py runserver
INFO "GET /drinks/mocha/ HTTP/1.1" 200 11716
GET /drinks/mocha/?pdb
function "detail" in drinks/views.py:8
args: ()
kwargs: {'drink_type': u'mocha'}
()
> /python/djangodev/local/lib/python2.7/site-packages/django/core/handlers/base.py(79)make_view_atomic()
-> non_atomic_requests = getattr(view, '_non_atomic_requests', set())
(Pdb) n
> /python/djangodev/local/lib/python2.7/site-packages/django/core/handlers/base.py(80)make_view_atomic()
-> for db in connections.all():
...
...
...
--Call--
> /www/code/djangorecipes/5_django_settings/coffeehouse/drinks/views.py(8)detail()
-> def detail(request,drink_type):
(Pdb)
> /www/code/djangorecipes/5_django_settings/coffeehouse/drinks/views.py(9)detail()
(Pdb) c
Listing 5-32.Django pdb sequence

您可以看到清单 5-32 从 Django 的内置 web 服务器开始，并立即接收和发送对常规 URL /drinks/mocha/的响应。到目前为止，一切都是标准的；但是，请注意对 URL /drinks/mocha/?pdb的下一个请求以及随后的详细输出。

详细输出告诉您请求进入应用的位置，包括参数，以及在django.core.handlers.base.py包中进入 Django 核心框架的初始入口点。

在最初的详细输出之后，执行在第一个(Pdb)实例处停止。此时，您遇到了一个断点，因此运行runserver的控制台和请求客户端(即浏览器)会冻结，直到您在控制台上提供额外的输入。在清单 5-32 中，您可以看到字母n代表下一个被引入，执行向前移动到另一行，之后您将看到另一个(Pdb)提示或断点。此时，您只需按下Enter键即可重新调用之前的命令(即n)并向前移动。

如果您想前进而不碰到另一个断点，您可以键入c表示 continue，这样执行会正常继续，不会再次暂停。

正如您所看到的，使用 Django 的 pdb 的强大之处在于，除了能够交互式地分析和设置变量之外，您还可以以非常精细的方式遍历任何部分的执行周期。表 5-6 描述了与 pdb 相关的最基本命令。

表 5-6。

Python pdb commands used at (Pdb) prompt

| Pdb 命令 | 描述 | | --- | --- | | (回车)(按键) | 重新执行上一个命令。 | | n | 将执行移动到下一个断点。 | | c | 继续执行，不再有断点。 | | q | 立即退出执行。 | | p | 打印变量。 | | l (L 小写) | 显示当前断点处的源代码列表，共 11 行:断点行、前 5 行和后 5 行。有助于提供背景。 | | s | 进入子程序。在非方法相关断点中，s 和 n 都移动到下一个断点。在与方法相关的断点中，s 进入方法或子例程。 | | r | 中断子程序。用在 s 之后，返回主例程。 |

除了在 Django 应用中向 URL 附加?pdb参数以输入 pdb 之外，还有两种选择。您可以将--pdb标志附加到runserver上，以便在对应用的每个请求上输入 pdb(例如，python manage.py runserver --pdb)。您还可以使用--pm标志，仅当视图中出现异常时才进入 pdb(例如python manage.py runserver –pm)。

有关 pdb 本身的更多信息，请参考位于 https://docs.python.org/3/library/pdb.html 的官方 Python 文档。有关 Django pdb 的更多信息，请在 https://github.com/tomchristie/django-pdb 查阅项目文档。

Django 扩展

Django 扩展是为 Django 项目设计的工具集合。顾名思义，它为 Django 的标准工具在功能上趋于平衡的许多领域提供了扩展。出于调试的目的，Django extensions 提供了两个工具，我认为这是最值得研究的:runserver_plus 和 runprofileserver。

要使用 Django 扩展，你首先需要安装pip install django-extensions，然后将django_extensions添加到settings.py中的INSTALLED_APPS。一旦设置了 Django 扩展，就可以通过python manage.py命令使用它的各种工具，就像 Django 的标准工具一样。

Django extensions runserver_plus命令为 Django 项目提供了交互式和增强的调试。要使用runserver_plus，你首先需要安装 Werkzeug 工具- pip install Werkzeug。一旦安装了 Werkzeug，只需用python manage.py runserver_plus而不是 Django 的标准python manage.py runserver启动一个 Django 应用。乍一看，runserver_plus命令的工作方式就像 Django 的runserver；然而，如果您碰巧遇到一个异常，您将会看到如图 5-4 和 5-5 所示的错误页面。

图 5-5。

Django extensions runserver_plus with interactive console

图 5-4。

Django extensions runserver_plus

在图 5-4 中，你可以看到 Django 异常页面与 Django 默认异常页面略有不同。这种不同的布局是由 Werkzeug 生成的，但布局本身并不是这种方法的有趣之处:如果你将鼠标悬停在堆栈跟踪的任何部分，你就可以启动一个交互式调试会话，如图 5-5 所示。这是一种更加简单和强大的调试方法，因为它是直接在浏览器中完成的！

另一个强大的 Django 扩展工具是runprofileserver，它可以为 Django 应用页面创建一个 Python cProfile。Python cProfile 提供了一组统计数据，描述了程序的各个部分执行的频率和时间，这有助于确定加载缓慢和资源密集型 Django 应用页面的解决方案。

使用runprofileserver的第一件事是创建一个文件夹来保存概要文件(例如mkdir /tmp/django-coffeehouse-profiles/)。接下来，简单地用python manage.py runprofileserver --use-cprofile --prof-path=/tmp/django-coffeehouse-profiles/而不是 Django 的标准python manage.py server启动 Django 应用——注意--prof-path标志值指向保存概要文件的目录。

打开浏览器，进入 Django 应用。并在其中导航。如果您打开保存配置文件的文件夹，您会看到类似于root.000037ms.1459139463.prof、stores.000061ms.1459139465.prof和stores.2.000050ms.1459139470.prof的文件，其中每个文件代表一个页面点击的 cProfile。

尽管深入研究 cProfile 分析超出了本书的范围，更不用说有许多工具可以用于此目的，但是如果您想要一个快速简单的工具来打开 Python cProfile 文件，我会推荐 SnakeViz。只需做pip install snakeviz然后运行snakeviz <file_name>即可。一旦你在一个文件上运行snakeviz，你会看到 Python cProfile 的细节，如图 5-6 和 5-7 所示。

图 5-7。

SnakeViz cProfile listing sorted by run time

图 5-6。

SnakeViz cProfile image

正如我在开始时提到的，除了runserver_plus和runprofileserver之外，Django 扩展还提供了许多工具，我认为这些工具最适合调试任务。尽管如此，我还是建议您查看位于 https://django-extensions.readthedocs.org/en/latest/ 的 Django 扩展文档，探索其他可能在您自己的项目中有用的工具(例如，show_urls 工具显示 Django 项目的 url 路由，graph_models 工具为 Django 项目的模型生成图形)。

Django 管理命令

在前面的章节中——包括这一章——您依赖于通过所有 Django 项目中包含的manage.py脚本调用的管理命令。例如，为了启动 Django 项目的开发服务器，您使用了runserver命令(例如python manage.py runserver)，为了合并项目的静态资源，您使用了collectstatic命令(例如python manage.py collectstatic)。

Django 管理命令是 Django 应用的一部分，旨在通过一个关键字命令行指令完成重复或复杂的任务。每个 Django 管理命令都有一个脚本支持，该脚本包含一步一步的 Python 逻辑来完成其职责。因此，当您键入python manage.py runserver时，Django 会在幕后触发一个更加复杂的 Python 例程。

如果你在 Django 项目上输入python manage.py(即没有命令)，你会看到一个按 app 分类的 Django 管理命令列表(例如auth、django、staticfiles)。从这个列表中，您可以深入了解所有 Django 应用中可用的各种管理命令。

我将在书中描述与核心或第三方 Django 应用相关的 Django 管理命令的用途，就像我到目前为止所做的那样(例如，静态文件主题中的静态文件管理命令，模型主题中的模型管理命令)。

接下来我将描述如何在 Django 应用中创建定制的管理命令，这样您就可以通过一条指令来简化常规或复杂任务的执行。

定制管理命令结构

定制管理命令被构造为 Python 类，这些类从 Django django.core.management.base.BaseCommand类继承它们的行为。最后一个类提供了必要的结构来执行任何 Python 逻辑(例如，文件系统、数据库或特定于 Django 的)，同时处理通常与 Django 管理命令一起使用的参数。清单 5-33 展示了最可能的 Django 管理命令之一。

from django.core.management.base import BaseCommand, CommandError
from django.conf import settings

class Command(BaseCommand):
    help = 'Send test emails'

    def handle(self, *args, **options):
        for admin_name,email in settings.ADMINS:
            try:
                self.stdout.write(self.style.WARNING("About to send email to %s" % (email)))
                # Logic to send email here
                # Any other Python logic can also go here
                self.stdout.write(self.style.SUCCESS('Successfully sent email to "%s"' % email))
                raise Exception
            except Exception:
                raise CommandError('Failed to send test email')

Listing 5-33.Django management command class with no arguments

注意在清单 5-33 中，管理命令类必须被命名为Command，并从 Django BaseCommand类继承其行为。接下来，有一个help属性来描述管理命令的目的。如果您键入python manage.py help <task_file_name>或python manage.py <task_file_name> --help，Django 将输出help属性的值。

handle方法包含核心命令逻辑，在调用命令时自动运行。注意 handle 方法声明了三个输入参数:self来引用类实例；*args引用方法本身的论据；和**options来引用作为管理命令的一部分传递的参数。清单 5-33 中的任务逻辑只使用了self引用。另一个任务管理的例子——在清单 5-34 中——展示了如何使用参数。

清单 5-33 中的任务逻辑仅限于循环settings.py中的ADMINS值并输出任务结果。然而，在 handle 方法中可以执行的逻辑没有限制，只要它是有效的 Python。

尽管标准的 Python try/except 块在 Django 管理任务中可以正常工作，但是在创建 Django 管理任务时，有两个语法细节需要注意:输出消息和错误处理。

要在执行任务逻辑时发送输出消息——成功或信息——您可以看到清单 5-33 使用了self.stdout.write引用，它代表管理任务运行的标准输出通道。此外，您可以看到self.stdout.write同时使用了self.style.WARNING和self.style.SUCCESS来声明要输出的实际消息。在self.style.*中包装消息是可选的，但是根据 Django 语法着色角色输出彩色格式化的消息(例如，绿色字体的成功，黄色字体的警告)。 ¹¹

要在执行任务逻辑时发送错误消息，可以使用self.stderr.write引用，它代表管理任务运行的标准错误通道。为了由于错误而终止管理任务的执行，您可以raise这个django.core.management.base.CommandError异常——如清单 5-33 中所做的那样——它接受一个错误消息，该消息被发送到self.stderr.write通道。

在大多数情况下，很少有像清单 5-33 中这样的固定 Django 管理命令，它不使用任何参数来改变其逻辑工作流。例如，Django runserver命令接受像addrport和--nothreading这样的参数来影响 web 服务器的启动方式。

Django 管理命令可以使用两种类型的参数:位置参数——声明它们的顺序赋予它们意义；或者命名参数——在名称前加两个破折号(也叫旗帜)来给出它们的含义。

尽管handle()方法的**options参数——如清单 5-33 所示——提供了对管理命令参数的访问，以改变逻辑工作流，为了在自定义 Django 管理命令中使用参数，您还必须声明add_arguments()方法。

add_arguments()方法必须定义管理任务的参数，包括它们的类型——位置的或命名的——默认值、选择值和帮助消息，等等。本质上，add_arguments()方法作为命令参数的预处理程序，然后在handle()方法的**options参数中提供这些参数。

add_arguments(self,parser)签名的parser引用是一个基于标准 Python argparse 包 ¹² 的参数解析器，旨在轻松处理 Python 脚本的命令行参数。

要在add_arguments()方法中添加命令参数，可以通过parser.add_argument()方法，如清单 5-34 所示。

from django.core.management.base import BaseCommand, CommandError
from django.conf import settings

class Command(BaseCommand):
    help = 'Clean up stores'

    def add_arguments(self, parser):
        # Positional arguments are standalone name
        parser.add_argument('store_id')

        # Named (optional) arguments start with --
        parser.add_argument(
            '--delete',
            default=False,
            help='Delete store instead of cleaning it up',
        )

    def handle(self, *args, **options):
        # Access arguments inside **options dictionary
        #options={'store_id': '1', 'settings': None, 'pythonpath': None,
        #         'verbosity': 1, 'traceback': False, 'no_color': False, 'delete': False}

Listing 5-34.Django management task class with arguments

清单 5-34 中的管理命令声明了位置参数和命名参数。注意，这两个参数都是用parser.add_argument()方法添加的。不同之处在于，命名参数使用前导破折号——如果省略，参数被认为是位置性的。

根据定义，位置参数是必需的。所以在清单 5-34 的情况下，需要store_id参数(例如python manage.py cleanupstores 1，其中1是store_id)，否则 Django 抛出“参数太少”错误。

命名参数总是可选的。因为命名参数是可选的，你可以在清单 5-34 中看到--delete参数声明了一个default=False值，确保参数总是接收一个默认值来运行handle()方法中的逻辑。

清单 5-34 中的--delete参数也使用help属性来定义关于参数用途的描述性文本。除了default和help之外，parser.add_argument()方法还基于 Python argparse 包支持各种各样的属性——参见前面的脚注，了解该方法支持的一些参数。

最后，您可以在清单 5-34 中看到，handle()方法通过**options字典访问命令参数，其中的值可以用于构建命令逻辑。请注意**options—settings、pythonpath等中的附加论点。–由于BaseCommand类，默认情况下被继承。

自定义管理命令安装

所有 Django 管理任务都放在单独的 Python 文件中(即每个文件一个命令),并存储在/management/commands/文件夹下的 app 目录结构中。清单 5-35 显示了几个带有自定义管理任务的应用的文件夹结构。

+-<BASE_DIR_project_name>
|
+-manage.py
|
|
+---+-<PROJECT_DIR_project_name>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py
    |
    +-about(app)-+
    |            +-__init__.py
    |            +-models.py
    |            +-tests.py
    |            +-views.py
    |            +-management-+
    |                         +-__init__.py
    |                         +-commands-+
    |                                    +-__init__.py
    |                                    |
    |                                    |
    |                                    +-sendtestemails.py
    |
    +-stores(app)-+
                 +-__init__.py
                 +-models.py
                 +-tests.py
                 +-views.py
                 +-management-+
                              +-__init__.py
                              +-commands-+
                                         +-__init__.py
                                         |
                                         |
                                         +-cleanupstores.py
                                         +-updatemenus.py
Listing 5-35.Django management task folder structure and location

正如你在清单 5-35 中看到的，about应用在/management/commands/文件夹中有一个管理命令，stores应用在自己的/management/commands/文件夹中嵌套了两个管理命令。

Caution

为了确保应用管理命令的可见性，不要忘记添加空的 init。py 文件到/management/和/commands/文件夹中，如清单 5-35 所示，并在项目的 settings.py 文件中将应用声明为 INSTALLED_APPS 的一部分。

管理指挥自动化

Django 管理命令通常从命令行运行，需要人工干预。然而，有时从其他位置(例如，Django 视图方法或 shell)自动执行管理命令是有帮助或必要的。

例如，如果一个用户在 Django 应用中上传了一个图像，并且您希望该图像可以公开访问，那么您需要运行collectstatic命令，这样该图像就可以到达公开和合并位置(STATIC_ROOT)。类似地，您可能想在用户每次登录时运行一个cleanuprofile命令。

为了自动化管理命令的执行，Django 提供了django.core.management.call_command()方法。清单 5-36 展示了使用call_command()方法的各种方式。

from django.core import management

# Option 1, no arguments
management.call_command('sendtestemails')

# Option 2, no pause to wait for input
management.call_command('collectstatic', interactive=False)

# Option 3, command input with Command()
from django.core.management.commands import loaddata
management.call_command(loaddata.Command(), 'stores', verbosity=0)

# Option 4, positional and named command arguments
management.call_command('cleanupdatastores', 1, delete=True)

Listing 5-36.Django management automation with call_command()

清单 5-35 中的第一个选项执行一个没有任何参数的管理。清单 5-35 中的第二个选项使用 i nteractive=False参数来表示命令不能因为用户输入而暂停(例如，collectstatic总是询问你是否确定要覆盖先前存在的文件，interactive=False参数避免了这种暂停和输入的需要)。

清单 5-35 中的第三个选项调用管理命令，首先导入它，然后直接调用它的Command()类，而不是使用命令字符串值。最后，第四个选项——就像清单 5-35 中的第三个选项一样，使用了一个位置参数——声明为独立值(例如'stores'、1)和一个命名参数——声明为key=value(例如verbosity=0、delete=True)。

Footnotes 1

https://docs.djangoproject.com/en/1.11/topics/signing/

https://docs.python.org/3/library/time.html#time.strftime

https://pypi.python.org/pypi/ConcurrentLogHandler/0.9.1

https://docs.python.org/3/library/logging.handlers.html

https://github.com/getsentry/sentry

https://docs.sentry.io/server/installation/

https://github.com/getsentry/sentry/releases/tag/5.0.21

http://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys

https://support.sparkpost.com/customer/portal/articles/1933377-create-api-keys

http://django-debug-toolbar.readthedocs.org/

https://docs.djangoproject.com/en/1.11/ref/django-admin/#syntax-coloring

https://docs.python.org/3/library/argparse.html

六、Django 表单

表单是用户在 web 应用中输入或编辑数据的标准方式。在最底层，表单由具有特殊含义的 HTML 标签组成。虽然您可以直接向 Django 或 Jinja 模板添加 HTML 表单标记，但是您确实希望避免这种情况，并使用 Django 的内置表单支持来简化表单处理。

在这一章中，你将学习如何构建 Django 表单以及表单所经历的工作流程。您还将了解 Django 表单支持的各种字段类型和小部件，如何验证表单数据并管理其错误，以及如何在模板中布置表单及其错误。

一旦您对 Django 表单背后的基础有了牢固的理解，您将学习如何创建定制的表单字段和窗口小部件。最后，您将学习更复杂的 Django 表单处理技术，例如部分表单处理、使用 AJAX 的表单处理、如何处理通过 Django 表单发送的文件，以及如何使用 Django 表单集处理同一页面上的多个表单。

Django 表单结构和工作流程

Django 有一个特殊的表单包，它提供了一种处理表单的综合方法。这个包的特性包括在单一位置定义表单功能的能力、数据验证、与 Django 模型的紧密集成等等。让我们先来看看清单 6-1 中的一个独立 Django 表单类，它用于支持一个联系人表单。

# forms.py in app named 'contact'
from django import forms

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea)

Listing 6-1.Django form class definition

Note

Django 并不希望表单出现在特定的位置。您同样可以将 Django 表单类放在应用中它们自己的文件中(例如 forms.py)，或者放在其他应用文件中(例如 models.py、views.py)。您可以稍后将 Django 表单类导入到需要它们的地方，就像 Django 视图或 Python 包一样。

清单 6-1 中要注意的第一个重要方面是 Django 表单定义是forms.Form类的子类，所以它自动拥有这个父类的所有基本功能。接下来，您可以看到 form 类有三个属性，两个类型为forms.CharField，一个类型为forms.EmailField。这些表单域定义将输入限制为某些特征。

例如，forms.CharField表示输入应该是一组字符，而forms.EmailField表示输入应该是电子邮件。此外，你可以看到每个表单字段都包括属性(如required)来进一步限制输入的类型。目前，关于 Django 表单字段类型，这已经足够详细了；，关于 Django 表单字段类型的下一节将更详细地讨论这个主题。

接下来，让我们将清单 6-1 中的 Django 表单集成到 Django 视图方法中，这样就可以在 Django 模板中传递和呈现它。清单 6-2 展示了这个视图方法的初始迭代。

# views.py in app named 'contact'
from django.shortcuts import render
from .forms import ContactForm

def contact(request):
    form = ContactForm()
    return render(request,'about/contact.html',{'form':form})

Listing 6-2.Django view method that uses a Django form

清单 6-2 中的视图方法首先实例化ContactForm表单类，并将其分配给form引用。然后这个form引用作为一个参数被传递到about/contact.html模板中。

接下来，在 Django 模板中，您可以将 Django 表单作为常规变量输出。清单 6-3 展示了使用标准模板语法{{form.as_table}}时 Django 表单是如何呈现的。

<tr><th><label for="id_name">Name:</label></th><td><input id="id_name" name="name" type="text" /></td></tr>
<tr><th><label for="id_email">Your email:</label></th><td><input id="id_email" required name="email" type="email" /></td></tr>
<tr><th><label for="id_comment">Comment:</label></th><td><textarea cols="40" id="id_comment" required name="comment" rows="10">
</textarea></td></tr>
Listing 6-3.Django form instance rendered in template as HTML

在清单 6-3 中，您可以看到 Django 表单是如何被翻译成 HTML 标签的！注意 Django 表单如何为每个表单字段生成适当的 HTML <input>标签(例如，forms.EmailField(label='Your email')创建指定的<label>和一个 HTML 5 type="email"来执行电子邮件的客户端验证)。此外，请注意name字段缺少 HTML 5 required属性，这是因为清单 6-1 中的表单字段使用了required=False语句。

如果仔细观察清单 6-3 ，Django 表单实例的 HTML 输出只是内部 HTML 表格标签(即<tr>、<th>、<td>)。输出缺少一个 HTML <table>包装器标签和支持 HTML 表单标签(即，<form>标签和action属性，用于指示将表单发送到哪里，以及一个submit按钮)。这意味着您需要将缺少的 HTML 表单标签添加到模板中来创建一个工作的 web 表单——这个过程将在清单 6-4 中简要描述。

此外，如果您不想像清单 6-3 那样输出被 HTML 表格元素包围的整个表单域，有许多其他的语法变体可以输出精细的表单域并去掉 HTML 标签。在这种情况下，模板中的{{form.as_table}}引用是用来简化事情的，但是本章的下一节“在模板中设置 Django 表单的布局”将详细阐述在模板中输出 Django 表单的不同语法变化。

接下来，让我们看一下图 6-1 ，它显示了 Django 表单的工作流程，以更好地说明 Django 表单是如何从头到尾工作的。

图 6-1。

Django forms workflow

图 6-1 中工作流程的前两步是我到目前为止所描述的。它包括用户点击一个 URL，该 URL 由一个 view 方法处理，该方法根据 Django 表单类定义返回一个空表单。清单 6-3 显示了 Django 表单的原始 HTML 输出，但是正如我已经提到的，该表单缺少一些元素以成为一个功能性的 web 表单；接下来，我将描述获得一个功能性 web 表单需要添加的元素。

Django 表单的功能性 Web 表单语法

到目前为止，您已经了解了如何将 Django 表单类定义快速转换成 HTML 表单。但是这种自动 HTML 生成只是使用 Django 表单类定义的好处的一部分；您还可以更快地验证表单值并向最终用户显示错误。

要执行最后这些操作，首先需要有一个功能性的 web 表单。清单 6-4 展示了从 Django 表单创建功能性 web 表单的模板语法。

<form method="POST">
  {% csrf_token %}

<table>
{{form.as_table}}
</table>
<input type="submit" value="Submit form">
</form>

Listing 6-4.Django form template declaration for functional web form

关于清单 6-4 要注意的第一件事是表单被包装在 HTML <form>标签中，这是所有 web 表单的标准。Django 强迫您显式设置<form>标签的原因是因为它的属性决定了 web 表单的大部分行为，并且会根据表单的用途而变化。

在清单 6-4 中，method属性告诉 web 浏览器，当表单被提交时，它将数据发送到服务器。POST 方法值是处理用户数据的 web 表单中的标准做法——另一个方法选项值是 GET，但它不是传输用户提供的数据的典型选择。POST 方法的使用应该很快就会变得更加清晰，但是要了解更多关于表单method属性的背景知识，您可以参考许多关于 HTTP 请求方法的互联网参考资料。?? 1

另一个重要的<form>属性——在清单 6-4 中实际上是没有的——是action,它告诉 web 浏览器将表单提交到哪里(即哪个 URL 负责处理表单)。在这种情况下，因为清单 6-4 没有action属性，浏览器的行为是将数据发送到当前所在的同一个 URL，这意味着如果浏览器从/contact/ URL 获得表单，它会将数据发送到同一个/contact/ URL。如果您想将表单发布到一个单独的 URL，那么您可以将 action 属性(例如，action="/urltoprocessform/")添加到<form>标签中。

请记住，因为同一个 URL 通过 GET 请求交付初始表单，还必须通过 POST 请求处理表单数据，所以 URL 的 backing view 方法必须设计为处理这两种情况。在下一节中，我将描述清单 6-2 的修改版本——它只处理 GET 请求情况——也处理 POST 情况。

清单 6-4 中的{% csrf_token %}语句是一个 Django 标签。{% csrf_token %}是一个特殊的标记，用于通过 POST 提交 web 表单并由 Django 处理的情况。csrf 首字母的意思是跨站点请求伪造，这是 Django 实施的默认安全机制。虽然可以禁用 CSRF 而不在表单中包含{% csrf_token %} Django 标签，但我不建议这样做，并建议您继续将{% csrf_token %} Django 标签添加到 POST 的所有表单中，因为 CSRF 是一种保护措施，并且主要在幕后工作。第一部分的最后一小节更详细地描述了 CSRF 背后的推理以及它在 Django 是如何运作的。

清单 6-4 中的下一个是包装在<table>标签中的{{form.as_table}}片段，它表示 Django 表单实例并输出清单 6-3 中所示的 HTML 输出。最后，还有<input type="submit">标记，它生成表单的提交按钮——当用户点击时提交表单——和结束的</form>标记。

Django 查看流程表单的方法(后期处理)

一旦在 Django 中有了一个功能性的 web 表单，就有必要创建一个视图方法来处理它。在上一节中，我提到了同一个 URL(通过扩展，view 方法)如何处理空白 HTML 表单的生成，以及带有数据的 HTML 表单的处理。清单 6-5 展示了清单 6-2 中视图方法的一个修改版本，它就是这样做的。

from django.shortcuts import render
from django.http import HttpResponseRedirect
from .forms import ContactForm

def contact(request):
    if request.method == 'POST':
        # POST, generate form with data from the request
        form = ContactForm(request.POST)
        # check if it's valid:
        if form.is_valid():
            # process data, insert into DB, generate email,etc
            # redirect to a new URL:
            return HttpResponseRedirect('/about/contact/thankyou')
    else:
        # GET, generate blank form
        form = ContactForm()
    return render(request,'about/contact.html',{'form':form})

Listing 6-5.Django view method that sends and processes Django form

清单 6-5 的视图方法中最重要的构造是检查request方法类型的 if/else 条件。如果请求方法类型是 POST(即数据提交或图 6-1 中的步骤 3)，则处理表单的数据，但如果request方法类型是其他类型(即初始请求或图 6-1 中的步骤 1)，则生成一个空表单，产生与清单 6-2 相同的行为。注意清单 6-5 中的最后一行是一个return语句，该语句分配表单实例——无论是空的(也称为未绑定的)还是填充的(也称为绑定的)——并将其返回给模板进行呈现。

现在让我们仔细看看清单 6-5 中的 POST 逻辑。如果request方法类型是 POST，这意味着有传入的用户数据，所以我们用request.POST引用访问传入的数据，并用它初始化 Django 表单。但是请注意，没有必要访问单个表单字段或进行逐段赋值——尽管如果您想的话，您可以这样做，这一过程将在本章后面的章节中介绍——使用request.POST作为 Django 表单类的参数就足以用用户数据填充 Django 表单实例；就这么简单！值得一提的是，以这种方式(即使用用户提供的数据)创建的 Django 表单实例被称为绑定表单实例。

此时，我们仍然不知道用户提供的关于 Django 表单的字段定义的数据是否有效(例如，值是文本还是有效的电子邮件)。要验证表单的数据，必须在绑定的表单实例上使用is_valid() helper 方法。如果form.is_valid()为True，则处理数据并采取后续行动；在清单 6-5 中，这个额外的动作包括将控制重定向到/about/contact/thankyou URL。如果form.is_valid()是False，这意味着表单数据有错误，在这之后，控制落到最后一个return语句，该语句现在传递一个绑定的表单实例来呈现模板。在最后一种情况下，通过使用绑定表单实例，用户得到一个填充了初始数据提交和错误的呈现表单，这样他就能够纠正数据，而无需从头开始重新引入值。

我故意不提关于is_valid() helper 方法或错误消息显示的更多细节，因为 Django 表单处理可能会有点复杂。下一节“Django 表单处理:初始化、字段访问、验证和错误处理”涵盖了您需要了解的关于 Django 表单处理的所有内容，因此不会影响到本介绍性章节。

CSRF:这是什么？它是如何与 Django 一起工作的？

CSRF 或跨站请求伪造是网络犯罪分子使用的一种技术，目的是迫使用户在 web 应用上执行不想要的操作。当用户与 web 表单交互时，他们会执行各种状态更改任务，从下订单(例如，产品、汇款)到更改数据(例如，姓名、电子邮件、地址)。大多数用户在与 web 表单交互时会有一种增强的安全感，因为他们看到了一个 HTTPS/SSL 安全符号，或者他们在与 web 表单交互之前使用了用户名/密码，所有这些都会让人觉得网络罪犯无法窃听、猜测或干扰他们的行为。

CSRF 攻击在很大程度上依赖于社交工程和 web 应用松散的应用安全性，因此攻击媒介是开放的，与其他安全措施无关(例如，HTTPS/SSL、强密码)。图 6-2 展示了一个 web 应用的 CSRF 漏洞场景。

图 6-2。

Web application with no CSRF protection

在用户“X”与网络应用“A”交互之后(例如，下订单、更新他的电子邮件)，他简单地导航离开并转到其他站点。像大多数 web 应用一样，web 应用“A”将有效的用户会话保持几个小时或几天，以防用户回来决定做其他事情而不必再次登录。同时，网络罪犯也使用了站点“A ”,并且确切地知道其所有网络表单在哪里以及如何工作(例如，URL、诸如电子邮件、信用卡之类的输入参数)。

接下来，网络犯罪分子创建链接或页面，模仿在 web 应用“a”上提交 web 表单。例如，这可能是一个更改用户电子邮件地址以控制帐户或从用户帐户转移资金以窃取资金的表单。然后，网络罪犯通过电子邮件、社交媒体或其他带有诱人或可怕标题的网站，在互联网上植入这些链接或页面:“从网站‘A’获得 100 美元优惠券”、“紧急:由于安全风险，请更改您在网站‘A’的密码”。实际上，这些链接或页面并不像它们宣传的那样，而是在一次点击中模仿来自站点“A”的 web 表单提交(例如，更改用户的电子邮件或转移资金)。

现在让我们把注意力转向几小时或几天前访问过站点 A 的不知情用户 X。他瞥了一眼这些最后的广告，心想:“哇，我不能错过这个机会。”考虑到点击会造成什么危害，他点击了虚假广告，然后用户被发送到一个合法网站的“A”页面，或者点击“看起来”什么也没做。用户“X”对此毫不在意，继续执行其他任务。如果站点“A”没有带 CSRF 保护的 web 窗体，那么用户“X”只是无意中——在一次单击中——在站点“A”上执行了一个他没有意识到的操作。

如您所见，为了实施 CSRF 攻击，用户只需在给定的网站上进行一次活动会话，并且网络犯罪分子足够狡猾，可以诱骗用户点击在所述网站上执行操作的链接或页面。因此这个术语的名字是:“跨站点”，因为请求不是来自原始站点，而“请求伪造”是因为这是一个网络罪犯伪造的请求。

为了防止 web form CSRF 攻击，web 应用信任经过身份验证的用户是不够的，因为正如我刚才描述的，经过身份验证的用户可能无意中触发了他们没有意识到的操作。Web 表单必须配备一个惟一的标识符——通常称为 CSRF 令牌——它对用户来说是惟一的，并且有一个过期时间，类似于会话标识符。通过这种方式，如果一个经过身份验证的用户向一个站点发出请求，只有与他的 CSRF 令牌相匹配的请求才被认为是有效的，所有其他请求都被丢弃，如图 6-3 所示。

图 6-3。

Web application with CSRF protection

如图 6-3 所示，在 web 表单中包含 CSRF 令牌使得伪造用户请求变得非常困难。

在 Django 中，在 web 表单中生成一个 CSRF 令牌，该令牌带有一个以<input type="hidden" name="csrfmiddlewaretoken" value="32_character_string">形式生成 HTML 标签的{% csrf token %}标签，其中 32 个字符的字符串值因用户而异。以这种方式，如果 Django 应用发出 POST 请求——就像 web 表单发出的请求一样——它只接受 CSRF 令牌存在且对给定用户有效的请求；否则将产生“403 禁止”页面错误。

请注意，CSRF 在所有 Django 应用上是默认启用的，这要归功于其开箱即用的中间件设置，包括负责实施 CSRF 功能的django.middleware.csrf.CsrfViewMiddleware类。如果您希望完全禁用 Django 应用中的 CSRF 支持，您可以从settings.py中的MIDDLEWARE变量中删除django.middleware.csrf.CsrfViewMiddleware类。

如果希望在某些 web 表单上启用或禁用 CSRF，可以有选择地在处理 web 表单 POST 请求的视图方法上使用@csrf_exempt()和@csrf_protect装饰器。

要在所有 web 表单上启用 CSRF，并在某些 web 表单上禁用 CSRF 行为，请在MIDDLEWARE中保留django.middleware.csrf.CsrfViewMiddleware类，并使用@csrf_exempt()装饰器将不需要的视图方法装饰为 CSRF 验证，如清单 6-6 所示。

from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def contact(request):
    # Any POST-processing inside view method
    # ignores if there is or isn't a CSRF token

Listing 6-6.Django view method decorated with @csrf_exempt() to bypass CSRF enforcement

要在所有 web 表单上禁用 CSRF，并在某些 web 表单上启用 CSRF 行为，请从MIDDLEWARE中移除django.middleware.csrf.CsrfViewMiddleware类，并用@csrf_protect()装饰器装饰您想要 CSRF 验证的视图方法，如清单 6-7 所示。

from django.views.decorators.csrf import csrf_protect

@csrf_protect
def contact(request):
    # Any POST processing inside view method
    # checks for the presence of a CSRF token
    # even when CsrfViewMiddleware is removed

Listing 6-7.Django view method decorated with @csrf_protect() to enforce CSRF when CSRF is disabled at the project level

Django 表单处理:初始化、字段访问、验证和错误处理

因为 Django 表单处理可以有很多变化，所以我将从上一节中解释的相同的表单和视图方法开始讨论，现在合并到清单 6-8 中。

from django import forms
from django.shortcuts import render

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea)

def contact(request):
    if request.method == 'POST':
        # POST, generate form with data from the request
        form = ContactForm(request.POST)
        # Reference is now a bound instance with user data sent in POST
        # process data, insert into DB, generate email, redirect to a new URL,etc
    else:
        # GET, generate blank form
        form = ContactForm()
        # Reference is now an unbound (empty) form
    # Reference form instance (bound/unbound) is sent to template for rendering
    return render(request,'about/contact.html',{'form':form})

Listing 6-8.Django form class with backing processing view method

初始化表单:字段和表单的 Initial、init 方法、label_suffix、auto_id、field_order 和 use_required_attribute

当用户请求由 Django 表单支持的页面时，他们会收到一个空表单(也称为未绑定表单)，由清单 6-8 中的 GET 部分和ContactForm()实例表示。虽然从用户数据的角度来看，表单总是空的，但是表单可以包含来自的数据，作为其初始化序列的一部分(例如，带有用户电子邮件或姓名的预填充表单)。

要执行这种 Django 表单初始化，您有三种选择。第一种技术是通过 view 方法中声明的表单实例上的initial参数，用值字典初始化表单。清单 6-9 展示了这种技术。

def contact(request):
        ....
        ....
    else:
        # GET, generate blank form
        form = ContactForm(initial={'email':'johndoe@coffeehouse.com','name':'John Doe'})
        # Form is now initialized for first presentation to display these values
    # Reference form instance (bound/unbound) is sent to template for rendering
    return render(request,'about/contact.html',{'form':form})
Listing 6-9.Django form instance with initial argument declared in view method

ContactForm()现在使用initial={'email':'johndoe@coffeehouse.com','name':'John Doe'}生成一个预填充的表单实例，其中包含电子邮件和姓名字段的值，这样最终用户就不必麻烦地自己从头开始键入这些值。

清单 6-9 中的技术是针对一次性的或者特定于实例的初始化值。如果你想不断地为一个给定的表单域提供相同的值，一个更合适的技术是直接在表单域上使用相同的initial参数，如清单 6-10 所示。

from django import forms

class ContactForm(forms.Form):
      name = forms.CharField(required=False,initial='Please provide your name')
      email = forms.EmailField(label='Your email', initial='We need your email')
      comment = forms.CharField(widget=forms.Textarea)

def contact(request):
        ....
        ....
    else:
        # GET, generate blank form
        form = ContactForm()
        # Form is now initialized for first presentation and is filled with initial values in form definition
    # Reference form instance (bound/unbound) is sent to template for rendering
    return render(request,'about/contact.html',{'form':form})

Listing 6-10.Django form fields with initial argument

请注意清单 6-10 中的表单字段是如何配备了initial参数的。值得一提的是，如果在表单实例和表单字段上都使用了initial参数，则表单实例值优先于任何表单字段(例如，如果将清单 6-9 和清单 6-10 中的语句组合在一起，表单将总是用清单 6-9 中的email='johndoe@coffeehouse.com' and name='John Doe'预先填充)。

在像清单 6-10 这样的表单字段中使用initial参数的一个缺点是，值不能在运行时动态改变(也就是说，你不能像清单 6-9 那样根据谁调用表单来个性化initial值)。为了解决这个问题并为最复杂的表单初始化场景提供最大的灵活性，第三种技术使用了清单 6-11 中所示的表单类的__init__方法。

from django import forms

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea)

      def __init__(self, *args, **kwargs):
            # Get 'initial' argument if any
            initial_arguments = kwargs.get('initial', None)
            updated_initial = {}
            if initial_arguments:
                  # We have initial arguments, fetch 'user' placeholder variable if any
                  user = initial_arguments.get('user',None)
                  # Now update the form's initial values if user
                  if user:
                        updated_initial['name'] = getattr(user, 'first_name', None)
                        updated_initial['email'] = getattr(user, 'email', None)
            # You can also initialize form fields with hardcoded values
            # or perform complex DB logic here to then perform initialization
            updated_initial['comment'] = 'Please provide a comment'
            # Finally update the kwargs initial reference
            kwargs.update(initial=updated_initial)
            super(ContactForm, self).__init__(*args, **kwargs)

def contact(request):
        ....
        ....
    else:
        # GET, generate blank form
        form = ContactForm(initial={'user':request.user,'otherstuff':'otherstuff'})
        # Form is now initialized via the form's __init__ method
    # Reference form instance (bound/unbound) is sent to template for rendering
    return render(request,'about/contact.html',{'form':form})

Listing 6-11.Django form initialized with __init__ method

清单 6-11 中第一个重要的方面是如何在视图方法中初始化表单；注意，它使用了相同的initial参数，但是字典值现在是{'user':request.user,'otherstuff':'otherstuff'}。这些值看起来奇怪吗？该表单甚至没有名为user或otherstuff的字段，这是怎么回事呢？

这些最后的值完全有效，在其他情况下会被忽略，因为 Django 表单确实没有这些名称的字段，但是因为我们将在__init__方法中操作表单初始化过程的内部，我们可以访问这些占位符值用于间接初始化目的。更重要的是，使用这些占位符值说明了如何使用上下文数据或不相关的表单数据来初始化 Django 表单字段。

接下来，让我们将注意力转向 Django 表单的__init__方法，当您创建一个表单实例时会调用该方法。__init__方法的参数*args、**kwargs是标准的 Python 语法——如果您从未见过最后一种语法，请查看 Python 基础的附录:方法:默认、可选、*参数& **kwargs 参数。

__init__中的第一步是检查初始值，并创建一个引用来保存新值以初始化表单。如果有一个initial值，检查一个user值，将这些值用于表单的实际name和email字段。接下来，不考虑任何传入的值，对表单的comment字段进行直接赋值。

最后，用一组反映表单实际字段的新值更新表单的initial引用，导致使用表单上下文之外的数据(例如，请求数据、数据库查询等)初始化表单。).作为__init__方法的最后一步，调用super()方法，这样基类/父类初始化过程就开始了。

Always Use the Initial Argument or Init Method to Populate Forms with Initialization Data and Keep Them Unbound.

需要注意的是，前面所有的初始化技术都保持表单未绑定，这个术语用于描述没有填充用户数据的表单实例。术语“绑定”是为用用户数据填充表单的字段值而保留的。当您进入下一节中描述的 Django 表单的验证阶段时，绑定和未绑定之间的细微差别非常重要。

这也意味着语法 contact form(initial = { ' email ':' John Doe @ coffee house . com '，' name':'John Doe'})不等同于 contact form({ ' email ':' John Doe @ coffee house . com '，' name':'John Doe'})。第一种变体使用初始参数创建一个未绑定表单实例，而第二种变体通过直接传递值而不使用任何参数来创建一个绑定表单实例。

除了初始化 Django 表单上加载的第一组数据之外，Django 表单还有另外四个初始化选项，它们会影响模板中表单的布局:label_suffix、auto_id、field_order和use_required_attribute。

当您在模板中为 Django 表单生成输出时——这个主题将在本章后面的“在模板中设置 Django 表单的布局”中详细描述——表单字段通常伴随着所谓的字段标签，这是对人类友好的描述符的另一个名称。例如，如果您有名为name和email的字段，它们的默认标签分别是Your name和Your email。为了将字段标签从字段的 HTML 标记中分离出来(例如，<input type="text">)，Django 定义了一个标签后缀(默认为: (冒号符号)来产生带有模式<field_label>:<input type="<field_type>">的输出。通过label_suffix你可以定义一个自定义的标签后缀符号来分隔每个表单域和它的标签。因此，例如，ContactForm(label_suffix='...')语法输出由...分隔的每个表单字段标签(例如，Your email...<input type="text">)。

Tip

单个表单域也可以使用 label_suffix 属性；参见 Django 表单字段类型部分。如果在表单域和表单初始化中都声明了 label_suffix，则前者优先。

Django 表单的另一个初始化选项是auto_id，它为每个表单字段自动生成一个id和label。默认情况下，Django 表单总是被设置为auto_id=True，所以当输出带有form.as_table()的表单时，您总是会得到自动生成的 HTML ids 和标签，如清单 6-12 的第一部分所示。

<!-- Option 1, default auto_id=True -->
<tr><th><label for="id_name">Name:</label></th><td><input id="id_name" name="name" type="text" /></td></tr>
<tr><th><label for="id_email">Your email:</label></th><td><input id="id_email" name="email" type="email" /></td></tr>
<tr><th><label for="id_comment">Comment:</label></th><td><textarea cols="40" id="id_comment" name="comment" rows="10">
</textarea></td></tr>

<!-- Option 2 auto_id=False -->
<tr><th>Name:</th><td><input name="name" type="text" /></td></tr>
<tr><th>Your email:</th><td><input name="email" type="email" /></td></tr>
<tr><th>Comment:</th><td><textarea cols="40" name="comment" rows="10">\r\n</textarea></td></tr>

Listing 6-12.Django form with automatic ids

(default auto_id=True option) and no automatic ids auto_id=False option

注意清单 6-12 顶部输出中的field标签是如何围绕<label for="id_field_name"> <label>的，并且字段 HTML 标签包含了id="id_field_name"属性。在大多数情况下，这是一个理想的输出，因为它允许容易地引用字段来附加 JavaScript 事件或 CSS 类。然而，在其他情况下auto_id=True会产生非常冗长的输出和包含冲突的 HTML 标签(例如，如果在同一个页面上有两个相同类型的表单实例，就会有两个相同的 id)。

要关闭 id 和标签的自动生成，您可以用auto_id=False选项初始化一个表单。例如，ContactForm(auto_id=False)语法生成清单 6-12 的后半部分中的输出。

另一个影响表单布局的未绑定表单实例的初始化选项是field_order选项。默认情况下，表单字段按照声明的顺序输出，所以清单 6-10 中的表单定义遵循输出顺序:name、email、comment。您可以通过使用field_order选项来覆盖这个默认的字段输出，该选项接受一个带有期望输出顺序的字段名列表。field_order选项可以声明为初始化过程的一部分，也可以包含在内，就像它是一个表单字段一样。

例如，ContactForm(field_order=['email','comment','name'])语法确保首先输出email字段，然后是comment和name。值得一提的是，field_order选项可以接受一个不完整的字段列表，比如ContactForm(field_order=['email']),输出email字段，然后是剩余的表单字段，按照它们声明的顺序，在本例中是name，然后是comment。如果您经常设置field_order来初始化表单的字段顺序，一个更快的解决方案是设置默认的field_order作为表单本身的一部分:

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea)
      field_order = ['email','comment','name'] # Sets order email,comment,name

如果将field_order声明为表单本身的一部分，在初始化时，初始化field_order优先。下一节“在模板中设置 Django 表单的布局”包含了更多关于在模板中实际使用field_order的细节。

最后，use_required_attribute选项允许您设置 HTML 5 required属性的总体用途。默认情况下use_required_attribute=True，这意味着所有必需的表单域都用 HTML 5 required属性输出，确保浏览器总是提供这些表单域。通过用use_required_attribute=False初始化表单，可以禁用这个 HTML 5 客户端验证required属性。请注意，设置use_required_attribute=False不会影响 Django 服务器端对表单字段的验证(例如，如果表单字段是必需的，Django 服务器端验证仍然会捕获未提供的字段，而不管use_required_attribute选项如何)。

访问表单值:请求。发布和清理 _ 数据

一旦用户填写了 Django 表单，该表单将被发送回服务器进行处理，并对用户数据执行一个操作(例如，创建订单、发送电子邮件、将数据保存到数据库)——这一步在清单 6-8 的 POST 部分中有所描述。

Django 表单处理的一个主要优点是可以使用request.POST变量创建绑定表单实例。尽管request.POST变量是用用户数据填充 Django 表单的初始访问点，但是除了初始化表单实例之外，不应该使用这些数据，因为request.POST中的数据对于直接访问来说太原始了。

例如，在request.POST中，你仍然不知道用户提供的数据是否有效。此外，request.POST中的数据仍然被视为字符串，因此如果您的 Django 表单碰巧有一个IntegerField()或DateField()，它仍然需要手动转换为预期的数据类型(例如，“6”到 6 整数，“2017-01-01”到 2017-01-01 日期时间)，这只是 Django 表单的另一部分处理的不必要的工作。

一旦用request.POST变量生成了绑定表单，就可以通过cleaned_data字典访问表单的每个字段值。例如，如果绑定表单有一个名为name的表单字段，您可以使用语法form.cleaned_data['name']来访问用户提供的name值。更重要的是，如果表单字段是名为age的IntegerField()，语法form.cleaned_data['age']会产生一个整数值，这种格式化行为也适用于其他非字符串数据类型的表单字段(例如DateField())。

Caution

在对表单调用 is_valid()之前，您不能访问 cleaned_data。

按照设计，除非首先调用is_valid()方法，否则不可能访问表单实例的cleaned_data字典。如果你试图在调用is_valid()之前访问cleaned_data，你会得到错误AttributeError: 'form_reference' object has no attribute 'cleaned_data'。

如果你考虑一下，这是一个好的实践，毕竟，你为什么要访问未经验证的数据呢？下一节描述了is_valid()方法。

验证表单值:is_valid()、validators、clean_ ()和 clean()

is_valid()方法是 Django 表单处理的重要部分之一。一旦用request.POST创建了绑定表单，就调用实例上的is_valid()方法来确定包含的值是否符合表单的字段定义(例如，EmailField()值是否是有效的电子邮件)。尽管is_valid()方法返回布尔值True或False，但它有两个重要的副作用:

调用is_valid()还会在表单实例上创建cleaned_data字典来保存通过验证规则的表单字段值。

调用is_valid()还会在表单实例上创建errors字典，为每个没有通过验证规则的字段保存表单错误。

清单 6-13 展示了清单 6-8 使用is_valid()方法的修改版本。

from django.http import HttpResponseRedirect

def contact(request):
    if request.method == 'POST':
        # POST, generate form with data from the request
        form = ContactForm(request.POST)
        # Reference is now a bound instance with user data sent in POST
        # Call is_valid() to validate data and create cleaned_data and errors dict
        if form.is_valid():
           # Form data is valid, you can now access validated values in the cleaned_data dict
           # e.g. form.cleaned_data['email']
           # process data, insert into DB, generate email
           # Redirect to a new URL
           return HttpResponseRedirect('/about/contact/thankyou')
        else:
           pass # Not needed
           # is_valid() method created errors dict, so form reference now contains errors
           # this form reference drops to the last return statement where errors
           # can then be presented accessing form.errors in a template
    else:
        # GET, generate blank form
        form = ContactForm()
        # Reference is now an unbound (empty) form
    # Reference form instance (bound/unbound) is sent to template for rendering
    return render(request,'about/contact.html',{'form':form})

Listing 6-13.Django form is_valid() method

for form processing

注意在清单 6-13 中，在绑定表单实例创建之后，调用了is_valid()方法。如果所有的表单字段值都符合表单字段数据类型，我们输入一个条件，在这里可以通过cleaned_data字典访问表单值，执行任何必要的业务逻辑，并将控制权交给另一个页面，在清单 6-13 中是执行重定向。

如果任何表单字段值未能通过规则，那么is_valid()返回False，并在此过程中创建一个errors字典，其中包含未能通过规则的值的详细信息。因为最后自动创建了errors，所以在is_valid()返回False之后，所有需要做的就是返回相同的表单实例，以便向最终用户显示errors字典，这样他就可以纠正错误。

但是对于 Django 表单处理来说，与is_valid()方法同样重要的是，它的验证只是针对表单字段的数据类型进行的。例如，is_valid()可以验证一个值是否为空，一个值是否匹配给定的数字范围，或者一个值是否是有效的日期:本质上是 Django 表单字段类型支持的任何东西。

但是如果您想在is_valid()之后执行更复杂的验证呢？比如在认为一个值有效之前对照数据库检查该值，或者对照两个值进行检查(例如，对照提供的城市值检查提供的邮政编码值)。虽然您可以在调用is_valid()之后直接添加这些验证检查，但是 Django 提供了三种更有效的方法来执行高级规则，方法是将它们添加到表单字段或表单类定义中。

如果您想要一个可以跨多个 Django 表单域使用的可重用验证机制，最好的选择是通过表单域的validators选项分配一个验证器。validators表单域选项需要一个方法列表，用于在值不符合预期规则的情况下引发forms.ValidationError错误。清单 6-14 展示了一个 Django 表单，它的一个字段通过validators选项使用一个定制的验证器方法。

from django import forms
import re

def validate_comment_word_count(value):
      count = len(value.split())
      if count < 30:
            raise forms.ValidationError(('Please provide at least a 30 word message, %(count)s words is not descriptive enough'), params={'count': count},)

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea,validators=[validate_comment_word_count])

Listing 6-14.Django form field validators option with custom validator method for form processing

清单 6-14 中的第一部分展示了自定义的validate_command_word_count()方法，它(初步地)检查message是否至少有 30 个单词。如果方法的输入不是至少 30 个单词，Django 的forms.ValidationError错误就会被抛出，以表明违反了规则。

在清单 6-14 的下半部分，您可以看到一个修改过的ContactForm，其中comment字段使用了validators=[validate_csv]选项。这告诉 Django，在运行了is_valid()并且所有的表单字段都根据它们的数据类型检查了错误之后，它还应该根据为comment字段提供的值运行validate_comment_word_count验证器方法。如果注释值不符合这条规则，那么就会产生一个ValidatioError错误，这个错误会被添加到表单errors字典中——这个字典与上一节中描述的字典相同，用于根据字段值的数据类型检查字段值。

从清单 6-14 中的例子可以看出，通过validators选项，你同样可以在同一个表单或另一个 Django 表单中的任何其他表单字段上重用自定义的validate_comment_word_count()方法。此外，您还可以对一个字段应用多个验证器，因为validators选项接受一个验证器列表。最后，值得一提的是django.core.validators包包含了一系列验证器，你也可以重用 ² ，这些验证器由某些表单域数据类型在后台使用。

除了表单字段validators选项，还可以通过clean_<field>()和clean()方法添加验证表单规则，它们是作为 Django 表单类的一部分创建的——就像前面描述的__init__()。就像在表单字段validators选项中指定的方法一样，clean_<field>()和clean()方法在is_valid()方法运行时被自动调用。清单 6-15 展示了两种clean_<field>()方法的使用。

from django import forms

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea)

      def clean_name(self):
          # Get the field value from cleaned_data dict
          value = self.cleaned_data['name']
          # Check if the value is all upper case
          if value.isupper():
             # Value is all upper case, raise an error
             raise forms.ValidationError("Please don't use all upper case for your name, use lower case",code='uppercase')
          # Always return value
          return value

      def clean_email(self):
          # Get the field value from cleaned_data dict
          value = self.cleaned_data['email']
          # Check if the value end in @hotmail.com
          if value.endswith('@hotmail.com'):
             # Value ends in @hotmail.com, raise an error
             raise forms.ValidationError("Please don't use a hotmail email, we simply don't like it",code='hotmail')
          # Always return value
          return value

Listing 6-15.Django form field validation with clean_<field>() methods

在清单 6-15 中，有两个clean_<field>()方法来为name和email字段添加验证规则。Django 会自动搜索以clean_为前缀的表单方法，并尝试将表单的字段名与剩余的名称进行匹配，以对有问题的字段进行验证。这意味着你可以拥有和表单域一样多的clean_<field>()方法。

每个clean_<field>()方法内部的逻辑遵循与validators方法相似的模式。首先，通过代表表单实例的self引用从表单的cleaned_data字典中提取一个字段的值。接下来，对字段值运行您想要的任何规则或逻辑，如果您认为该值不符合，您将引发一个forms.ValidationError，它将错误添加到表单实例中。最后，这与validators方法唯一不同的是，您必须返回字段值，而不管是否引发错误或更改其值。

有时有必要应用一个不一定属于特定领域的规则，在这种情况下，通用的clean()方法是优于clean_<field>()方法的方法。清单 6-16 展示了clean()方法的使用。

from django import forms

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea)

      def clean(self):
          # Call clean() method to ensure base class validation
          super(ContactForm, self).clean()

          # Get the field values from cleaned_data dict
          name = self.cleaned_data.get('name','')
          email = self.cleaned_data.get('email','')

          # Check if the name is part of the email
          if name.lower() not in email:
             # Name is not in email, raise an error
             raise forms.ValidationError("Please provide an email that contains your name, or viceversa")

Listing 6-16.Django form field validation with clean() method

在清单 6-16 中，你可以看到与清单 6-15 中之前的clean_<field>()方法相似的方法。但是因为clean()方法是一个类范围的方法，并且你要自己覆盖它，它与clean_<field>()方法的不同之处在于，你必须首先显式调用基类/父窗体类的clean()方法(即super(...).clean())来确保基类验证被应用。表单字段值提取也是通过cleaned_data数据字典完成的，验证逻辑也是如此，并引发forms.ValidationError来指示违反规则。最后，clean()方法与clean_<field>()方法的不同之处在于它不返回值。

从功能上讲，clean()方法是不同的，因为它是在validators选项和clean_<field>()方法中的所有方法之后被调用的，这一行为很重要，因为所有这些方法都依赖于cleaned_data字典中的数据。这意味着如果一个validators或clean_<field>()方法引发了一个ValidationError错误，它将不会返回任何值，并且cleaned_data字典也不会包含这个字段的值。因此，当运行clean()方法时，如果在validators或clean_<field>()方法中有一个被短路，那么cleaned_data字典可能不一定具有所有的表单字段值，这就是为什么在cleaned_data字典没有给定字段的情况下，clean()方法使用更安全的字典访问语法cleaned_data.get('<field>','')来分配默认值。

clean()方法、clean_<field>()和validators方法之间另一个重要的行为差异是它们如何对待forms.ValidationError。当一个forms.ValidationError在一个validators或clean_<field>()方法中被引发时，错误被分配给表单的errors字典中有问题的<field>——这对显示很重要。但是当在clean()方法中引发一个forms.ValidationError时，错误被分配给一个名为__all__的特殊占位符字段——也称为“非字段错误”——它也被放在表单的errors字典中。

如果你想将clean()方法中的错误分配给特定的表单字段，你可以使用清单 6-17 中所示的add_error()方法。

def clean(self):
    # Call clean() method to ensure base class validation
    super(ContactForm, self).clean()

    # Get the field values from cleaned_data dict
    name = self.cleaned_data.get('name','')

    # Check if the name is part of the email
    if name.lower() not in email:
       # Name is not in email, raise an error
       message = "Please provide an email that contains your name, or viceversa"
       self.add_error('name', message)
       self.add_error('email', forms.ValidationError(message))
       self.add_error(None, message)

Listing 6-17.Django form field error assignment with add_error()

in clean() method

注意清单 6-17 是如何在表单实例上使用add_error()方法而不是raise forms.ValidationError()语法的。add_error()方法接受两个参数:第一个是要分配错误的表单字段名称，第二个可以是错误消息字符串或ValidationError类的实例。

清单 6-17 中的前两个add_error()方法分别将错误分配给name和email字段。带有None键的第三个add_error()方法将错误分配给__all__占位符，使其等同于清单 6-16 中的raise forms.ValidationError()。

错误表单值:错误

在调用is_valid()方法后，前面章节中描述的表单错误会自动添加到errors字典中的表单实例中。包容地说，不像cleaned_data字典，不需要调用is_valid()方法就可以直接访问errors字典。

字典很重要，因为所有的表单错误都在上面。无论错误是因为值不符合表单字段数据类型还是不符合clean()方法、clean_<field>()方法、validators方法或clean()方法中的add_error()方法中的 raise forms.ValidationError()而引发的，所有错误最终都将出现在表单的errors字典中。

errors字典遵循{'<field_name>':'<error_message>'}模式，这使得识别视图方法或模板中的表单错误变得容易。最后一种模式的唯一例外是表单错误不是特定于字段的(例如，在clean()方法中创建的那些)，在这种情况下，表单错误被分配给一个名为__all__的特殊键，这种错误也称为非字段错误。

虽然您可以像访问任何其他 Python 字典一样访问errors字典，但是 Django 提供了表 6-1 中描述的一系列方法，使得处理错误更加容易。

表 6-1。

Django form errors methods

| 方法 | 描述 | | --- | --- | | 表单.错误 | 允许您访问原始错误字典。 | | form.errors.as_data() | 输出包含原始 ValidationError 实例的字典。例如，如果 errors 输出{'email':['此字段是必需的']}，则 errors.as_data()输出{'email':[ValidationError(['此字段是必需的'])]}。 | | form . errors . as _ JSON(escape _ html = False) | 输出包含错误字典内容的 JSON 结构。例如，如果 errors 输出{'email':['此字段是必需的']}，则 errors.as_json()输出{'email':[{'message ':'此字段是必需的'，' code ':'必需的' }]}。请注意，默认情况下，as_json()不会对其输出进行转义，如果您希望对错误进行转义，请使用 escape_html 标志(例如，as_json(escape_html=True))。 | | form.add_errorfield，message) | 将错误信息与给定的表单域相关联。尽管通常在 clean()方法中使用，但如果需要，也可以在视图方法中使用。请注意，如果未指定 field，则错误消息将成为被视为非字段错误的错误中 __all__ 占位符键的一部分。 | | form.has_error(字段，代码=无) | 如果给定字段有错误，则返回 True 或 False 值。请注意，默认情况下，如果任何错误类型与某个字段相关联，has_error 将返回 True。要针对特定的错误类型执行评估，可以使用 code 关键字(例如，form.has_error('email '，code='required '))。要检查表单是否有非字段错误，可以使用 NON_FIELD_ERRORS 作为字段值。 | | form.non_field_errors() | 返回与表单相关联的非表单错误列表(即 __all__ 占位符键)。这些错误通常通过 ValidationError 或 add_error(None，' message ')在 clean() clean 方法中创建。 |

您可能已经注意到，在所有前面的例子中创建的ValidationError类实例使用不同的参数，这意味着有多种方法来创建ValidationError实例。例如，一些ValidationError实例使用一个简单的字符串，但是也可以用一系列ValidationError实例创建一个ValidationError实例，并指定一个code属性来进一步分类错误类型。清单 6-18 展示了一系列使用这些变体的ValidationError类实例。

from django import forms

# Placed inside def clean_email(self):
raise forms.ValidationError("Please don't use a hotmail email, we simply don't like it",code='hotmail')

# Placed inside def clean(self):
raise forms.ValidationError(
     forms.ValidationError("Please provide an email that matches your name, or viceversa",code='custom'),
     forms.ValidationError("Please provide your professional email, %(value)s doesn't look professional ",code='required',params={'value':self.cleaned_data.get('email') })

Listing 6-18.Django form ValidationError

instance creation

清单 [6-18 中的ValidationError实例变体都是可选的，但是当需要在模板上显示或过滤错误消息时，这个过程将在本章后面的“在模板中设置 Django 表单的布局”一节中详细描述。

Django 表单字段类型:小部件、选项和验证

由于 Internet 不受控制的特性——它有许多类型的设备、浏览器和用户体验级别——它对 web 表单必须处理的数据类型提出了各种各样的要求，以及如何净化数据以符合 web 表单的原始目的的各种各样的要求。

当您为 Django 应用创建 web 表单时，您依赖于由表单字段组成的 Django 表单类。每个 Django 表单字段都很重要，因为它规定了最终构成 web 表单整体行为的一小部分功能。

Django 表单域定义了两种类型的功能，表单域的 HTML 标记和它的服务器端验证工具。例如，Django 表单字段转换成实际的 HTML 表单标记(例如，<input>、<select>或<textarea>标签)、HTML 标记属性(例如，长度、字段是否可以留空，或者字段是否必须禁用)，以及对表单字段的数据轻松执行服务器端验证的必要挂钩。

Django 表单字段出于需要定义了这两种类型的 web 表单功能。尽管随着 HTML5 等技术的发展，浏览器已经取得了巨大的进步，通过 HTML 标记本身(无需 JavaScript)提供了开箱即用的表单字段验证，但浏览器仍然完全控制着最终用户，只要有足够的知识，最终用户就可以绕过表单，将他想要的任何数据输入表单。因此，一旦用户提交了表单域数据，标准的做法是进一步检查它是否符合表单的规则，由于使用了 Django 表单域，这个过程变得非常容易。

表 6-2 展示了各种 Django 表单字段，包括它们的类型、它们生成的 HTML、它们的默认小部件以及它们的验证行为。

表 6-2。

Django form field types, generated HTML, default widget, and validation behavior

| 字段类型 | Django 表单字段类型 | HTML 输出 | 默认 Django 小部件 | 验证行为 | | --- | --- | --- | --- | --- | | 布尔代数学体系的 | 表格。布尔字段() | | forms.widgets.CheckboxInput() | 生成 HTML 复选框输入标记以获取布尔值 True 或 False 未选中复选框时返回 False，选中复选框时返回 True。 | | 布尔代数学体系的 | 表格。NullBooleanField() | | forms . widgets . nullbooleanselect() | 就像 BooleanField 一样工作，但也允许“未知”值；选择未知(1)值时返回 None，选择是(2)值时返回 True，选择否(3)值时返回 False。 | | 文本 | 表格。夏菲尔德() | | forms.widgets.TextInput() | 生成 HTML 文本输入标记。 | | 文本(专业) | 表格。电子邮件字段() | | forms.widgets.EmailInput() | 生成 HTML 电子邮件输入标记。请注意，HTML5 标记用于客户端电子邮件验证，仅当浏览器支持 HTML5 时才有效。如果浏览器不支持 HTML5，那么它会将这个标记视为常规文本输入。Django 服务器端的表单验证是针对电子邮件进行的，与 HTML5 支持无关。 | | 文本(专业) | 表格。GenericIPAddressField() | | forms.widgets.TextInput() | 工作原理与 CharField 类似，但是服务器端 Django 验证(文本)值是否可以转换为 IPv4 或 IPv6 地址(例如，192.46.3.2，2001:0db 8:85a 3:0000:0000:8a2e:0370:7334)。 | | 文本(专业) | 表格。regex field(regex = ' regular _ expression ') | | forms.widgets.TextInput() | 就像 CharField 一样工作，但是服务器端 Django 验证(文本)值是否符合 regex 中定义的正则表达式。注意 regex 可以是表示正则表达式的字符串(例如\。以. com$结尾的字符串。com)或来自 Python 的 re 包的编译的 Python 正则表达式(例如，re.compile('\。com$ '))。 | | 文本(专业) | 表格。斯拉格菲尔德() | | forms.widgets.TextInput() | 就像 CharField 一样工作，但是服务器端 Django 验证(文本)值可以转换为 slug。在 Django 中,“slug”是一个仅包含小写字母、数字、下划线和连字符的值，通常用于净化 URL 和文件名(例如,“什么是 slug？！“消毒过的绳子”是一根消毒过的绳子。 | | 文本(专业) | 表格。URLField() | | forms.widgets.URLInput() | 生成 HTML url 输入标记。请注意，HTML5 标记用于客户端 url 验证，仅当浏览器支持 HTML5 时才起作用。如果浏览器不支持 HTML5，那么它会将该标记视为常规文本输入。Django 服务器端的表单验证是针对 url 进行的，与 HTML5 支持无关。 | | 文本(专业) | 表格。UUIDField() | | forms.widgets.TextInput() | 就像 CharField 一样工作，但是服务器端 Django 验证(文本)值是否可转换为 UUID(通用唯一标识符)。 | | 文本(专业) | 表格。组合字段(fields=[field_type1，field_type1]) | | forms.widgets.TextInput() | 工作原理与 CharField 类似，但是服务器端 Django 对 Django 表单字段列表强制执行数据传递规则(例如，combo field(fields =[CharField(max _ length = 50)，SlugField()])强制数据为最大长度为 50 个字符的 slug 字段)。 | | 文本(专业) | 表格。多值字段(字段=[字段类型 1，字段类型 1]) | 因字段列表而异(例如，对于三个 char field:；为两个夏菲尔德: | forms.widgets.TextInput() | 旨在创建由多个预先存在的表单字段组成的自定义表单字段(例如，由三个 CharField()组成的社会保险表单字段)。它需要一个子类实现(例如，SocialSecurityField(MultiValueField):)来包含新字段的基本表单字段和验证逻辑。 | | 文本(专业)/文件 | 表格。文件路径字段(路径= '目录') | | forms.widgets.Select() | 从位于服务器端路径目录中的文件生成 HTML 选择列表。注意值由路径+文件名组成，并且只显示文件名。 | | 文件 | 表格。文件字段() | | forms . widgets . clearable file input() | 生成 HTML 文件输入标记，以便最终用户能够通过其 web 浏览器选择文件。此外，它还提供了各种实用程序来处理文件的后期处理。 | | 文件(专用) | 表格。图像字段() | | forms . widgets . clearable file input() | 生成 HTML 文件输入标记，以便最终用户能够通过其 web 浏览器选择图像文件。工作方式与 FileField 类似，但使用 Pillow 软件包提供了额外的工具来处理图像的后期处理。请注意，此字段会强制您安装枕头(例如，pip 安装枕头)。 | | 日期/时间 | 表格。日期字段() | | forms . widgets . file output() | 工作方式与 CharField 类似，但是服务器端 Django 验证(文本)值是否可以转换为 datetime.date、datetime.datetime 或以特定日期格式(例如 2017-12-25、11/25/17)格式化的字符串。 | | 日期/时间 | 表格。时间字段() | | forms.widgets.TextInput() | 工作原理与 CharField 类似，但是服务器端 Django 验证(文本)值是否可以转换为 datetime.time 或以特定时间格式(例如 15:40:33，17:44)格式化的字符串。 | | 日期/时间 | 表格。日期时间字段() | | forms.widgets.DateTimeInput() | 工作方式与 CharField 类似，但服务器端 Django 验证(文本)值是否可以转换为 datetime.datetime、datetime.date 或以特定日期时间格式格式化的字符串(例如 2017-12-25 14:30:59、11/25/17 14:30)。 | | 日期/时间 | 表格。DurationField() | | forms.widgets.TextInput() | 工作原理与 CharField 类似，但是服务器端 Django 验证(文本)值是否可以转换为 timedelta。注意 Django 使用 Django . utils . date parse . parse _ duration()方法作为助手，这意味着字符串必须与格式 DD HH:MM:SS.uuuuuu 匹配(例如，2 1:10:20 表示 2 天 1 小时 10 分 20 秒的时间增量)。 | | 日期/时间 | 表格。SplitDateTimeField() | | forms . widgets . splitdatetimewidget | 工作方式类似于 DateTimeField，但会为日期和时间生成两个单独的文本输入，这与 DateTimeField 不同，它需要一个包含日期和时间的字符串。验证方面，Django 强制将日期输入转换为 datetime.date，将时间输入转换为 datetime.time。 | | 数字 | 表格。IntegerField() | | forms.widgets.NumberInput() | 生成 HTML 数字输入标记。请注意，此 HTML5 标记用于客户端数字验证，仅当浏览器支持 HTML5 时才起作用。如果浏览器不支持 HTML5，那么它会将该标记视为常规文本输入。Django 服务器端表单验证是对整数进行的，与 HTML5 支持无关。 | | 数字 | 表格。十进制菲尔德() | | forms.widgets.NumberInput() | 生成 HTML 数字输入标记。请注意，HTML5 标记用于客户端数字验证，仅当浏览器支持 HTML5 时才起作用。如果浏览器不支持 HTML5，那么它会将该标记视为常规文本输入。Django 服务器端表单验证是针对一个十进制数进行的，与 HTML5 支持无关。 | | 数字 | 表格。浮动字段() | | forms.widgets.NumberInput() | 生成 HTML 数字输入标记。请注意，HTML5 标记用于客户端数字验证，仅当浏览器支持 HTML5 时才起作用。如果浏览器不支持 HTML5，那么它会将该标记视为常规文本输入。Django 服务器端表单验证是针对浮点数进行的，与 HTML5 支持无关。 | | 预定义值 | 表格。choice field(choices = tuple _ of _ tuples) | | forms.widgets.Select() | 从通过选择定义的元组生成 HTML 选择列表(例如，((1，“美国”)、(2，“加拿大”)、(3，“墨西哥”))。注意，对于 ChoiceField，如果没有选择任何值，则传递空字符串“”进行后处理，如果选择了类似“2”的值，则传递文字字符串进行后处理，而不考虑原始数据表示。请参见 TypeChoiceField 或 clean form 方法，为空值和字符串处理重写这些最后的行为。 | | 预定义值 | 表格。TypeChoiceField(choices = tuple _ of _ tuples，coefit = coefit _ function，empty_value=None) | | forms.widgets.Select() | 其工作方式与 ChoiceField 类似，但通过强制参数和 empty_value 参数提供了额外的后处理功能。例如，使用 TypeChoiceField，您可以使用 empty_value 参数定义不同的默认值(例如，empty_value=None ),并且可以使用 constrate 参数定义强制方法，以便将选定的值从其字符串表示形式转换过来(例如，使用 constrate = int，类似“2”的值会通过内置的 int 函数转换为 2(整数))。 | | 预定义值 | 表格。MultipleChoiceField(choices = tuple _ of _ tuples) | | forms.widgets.SelectMultiple() | 从通过选择定义的元组中为多个值生成 HTML 选择列表(例如，((1，“美国”)、(2，“加拿大”)、(3，“墨西哥”))。它的工作方式类似于 ChoiceField，但允许选择多个值，这些值在后期处理中作为列表提供。 | | 预定义值 | 表格。TypedMultipleChoiceField(choices = tuple _ of _ tuples，coefit = coefit _ function，empty_value=None) | | forms.widgets.Select() | 其工作方式与 MultipleChoiceField 类似，但通过强制参数和 empty_value 参数提供了额外的后处理功能。例如，使用 TypedMultipleChoiceField，您可以使用 empty_value 参数定义不同的默认值(例如，empty_value=None ),并且可以使用 constrate 参数定义一个强制方法，以便所选值从其字符串表示形式转换而来(例如，使用 constrate = int，像“2”这样的值会通过内置的 int 函数转换为 2(整数))。 |

正如你在表 6-2 中看到的，Django 表单域为几乎所有现存的 HTML 表单输入的生成提供了现成的支持，并为各种数据类型提供了必要的服务器端验证。例如，您可以使用CharField()表单字段类型来捕获标准文本，或者使用更专业的EmailField()表单字段类型来确保捕获的值是有效的电子邮件。正如您可以使用ChoiceField()生成一个带有预定义值的表单列表，或者使用DateField()强制表单值是一个有效日期。

小部件和表单域之间的关系

在表 6-2 中，你可以看到除了实际的 Django 表单域语法(例如forms.CharField()、forms.ImageField())之外，每个表单域都与一个默认的小部件相关联。Django 小部件在很大程度上没有被注意到，并且经常与表单字段本身的功能混合在一起(例如，如果您想要一个 HTML 文本输入<input type="text"..>，您可以使用forms.CharField())。但是，当您需要更改表单域生成的 HTML 或者表单域数据最初的处理方式时，您需要使用小部件。

更令人困惑的是，您在表单字段上指定的许多选项最终都被用作小部件的一部分。例如，表单字段forms.CharField(max_length=25)告诉 Django 在处理时将一个值限制为最多 25 个字符，但是这个相同的max_length选项被传递给forms.widgets.TextInput()小部件以生成 HTML <input type="text" maxlength="25"...>，从而通过 HTML maxlength="25"属性在浏览器上执行相同的规则。所以在这种情况下，您实际上可以通过一个表单域选项来更改 HTML 输出，甚至不需要了解小部件！

那么，您真的需要使用小部件来改变表单字段产生的 HTML 吗？答案是视情况而定。许多表单域选项被自动传递给幕后的小部件，实际上改变了生成的 HTML，但是不要搞错，它是一个负责生成 HTML 而不是表单域的小部件。如果表单域的选项不能实现期望的 HTML 输出，那么就有必要改变表单域的小部件来实现自定义的 HTML 输出。

在本章接下来的章节中，我将详述 Django 窗口小部件的主题，并描述如何覆盖和定制 Django 表单字段的默认窗口小部件。现在您已经知道了 Django 小部件的存在以及它们与 Django 表单字段的关系，我将继续 Django 表单字段的主题，并解释各种 Django 表单字段选项及其验证行为。

Django ‘Hidden’ Built-in Widgets

表 6-2 显示了 Django 中所有内置的表单字段，这可能会误导您认为同一个表也显示了所有 Django 内置的表单小部件。事实并非如此。表 6-2 中的 widget 列仅显示分配给所有内置表单域的默认 widget。forms.widgets. package 中还包含一些 Django 内置的小部件:

密码输入。-密码字段的小部件(例如，当用户键入文本时显示****)。还支持在验证错误后重新显示字段值。
HiddenInput。-隐藏字段的小部件(如)。
MultipleHiddenInput。-类似 HiddenInput，但用于多个值(即一个列表)。
文本区域。-文本区域字段的小部件(如 )。

无线电选择。-类似于 Select 小部件，但生成一个单选按钮列表(如

)。

复选框选择多个。-类似于 SelectMultiple 小部件，但生成一个复选框列表(如

)。

时间输入。-类似于 DateTimeInput 小部件，但仅用于时间输入(例如，13:54，13:54:59)。

选择日期小工具。- widget 生成三个选择日期的 widget(例如，选择日期的 widget、选择月份的 Widget、选择年份的 Widget)。

SplitHiddenDateTimeWidget。-类似 SplitDateTimeWidget 小部件，但是使用隐藏的日期和时间输入。

文件输入。-类似于 ClearableFileInput 小部件，但是没有复选框输入来清除字段的值。

本章后面的章节描述了表单域的小部件参数以及如何定制 Django 小部件，提供了更多关于如何以及何时使用这些额外的内置小部件的上下文。

空值、默认值和预定值:必需值、初始值和选项

默认情况下，所有 Django 表单字段都被标记为 required，这意味着每个字段都必须包含一个值才能通过验证。required参数对表 6-2 中描述的所有 Django 表单字段都有效，除了在服务器端强制值不为空，HTML 5 required属性也被分配给表单字段，因此用户的浏览器也强制验证。

Tip

可以用 use_required_field=False 初始化表单，以放弃使用 HTML 5 required 属性。请参阅上一小节“初始化表单”

如果你想让一个字段值为空- None或空字符串'' -那么一个字段必须被赋予required=False参数。

您还可以通过initial参数为字段分配默认值。初始参数对表 6-2 中描述的所有 Django 表单字段同样有效，并在前面的小节“初始化表单”中有详细描述

如果您不想让用户为字段引入开放式值，您可以通过choices参数将字段值限制为一组预先确定的值。如果您想使用choices属性，您必须使用一个表单域数据类型，该数据类型被设计用来生成一个 HTML <select>列表，如forms.ChoiceField()、forms.MultipleChoiceField或forms.FielPathField()。choices参数不能用于像forms.CharField()这样为开放式输入设计的数据类型。

限制文本值:max_length、min_length、strip 和验证器

接受文本(如CharField()、EmailField()以及表 6-2 中描述的其他文本)的表单字段数据类型可以接受max_length和min_length参数，以将字段值分别限制为最大和最小字符长度。

strip参数用于将 Python 的strip()方法应用于字段值——该方法去除了所有尾随和前导空格。strip参数只能用于两种 Django 字段数据类型，默认为strip=True,的CharField()和默认为strip=False的RegexField()。

要对接受文本值的字段应用更高级的限制规则，请参阅上一小节“验证表单值”，该小节描述了限制字段值的validators和其他技术。

限制数值:最大值、最小值、最大位数、小数位数和验证器

接受数字如IntegerField()、DecimalField()和FloatField()的表单字段数据类型可以接受max_value和min_value参数，分别限制字段数值的上限和下限。

此外，DecimalField()数据类型接受更精细的数字类型，可以使用max_digits参数来限制值中的最大位数，或者使用decimal_places参数来指定值中的最大小数位数。

要对接受数字值的字段应用更高级的限制规则，请参阅上一小节“验证表单值”，该小节描述了限制字段值的validators和其他技术。

错误消息:错误消息

每个 Django 字段数据类型都有内置的错误消息。例如，当一个字段的数据类型是required并且用户没有添加任何值时，Django 会将错误消息This field is required分配给该字段，作为表单的errors字典的一部分。类似地，如果一个字段数据类型使用了max_length参数，并且用户提供的值超过了这个阈值，Django 就会创建错误消息Ensure this value has at most X characters (it has X)。

如清单 6-18 中所述，除了错误消息本身，Django 错误消息通常还会给出一个消息错误代码。正是这些消息错误代码用于通过error_messages参数分配定制消息。

error_messages参数需要一个字典，其中每个键是消息错误代码，其值是自定义错误消息。例如，为了给required代码提供一个定制的消息，你可以使用语法forms.CharField(error_messages={"required":"Please, pretty please provide a comment"})。类似地，如果您希望一个表单字段违反它的max_length值，您可以通过max_length代码(例如error_messages={"max_length":"This value exceeds its max length value"})指定一个定制的错误消息。

错误代码通常直接映射到它们违反的规则(例如，如果一个forms.IntegerField违反了它的max_value，Django 使用max_value代码分配一个默认的错误消息，您可以使用这个代码覆盖它)。然而，有二十多个内置错误消息代码(例如'missing'、'contradiction')，其中一些并不太明显。例如，forms.ImageField可以生成错误消息'Upload a valid image. The file you uploaded was either not an image or a corrupted image.'，它使用'invalid_image'错误代码，这意味着要覆盖这个默认的错误消息，您需要事先知道错误代码，以将其声明为error_messages的一部分。

在大多数情况下，很少需要为一些更深奥的错误代码定制错误消息。但是如果您在为给定字段定制错误消息时遇到了麻烦，因为您无法确定它的错误代码，那么在表单错误字典上进行一点日志调试(例如，form.errors.as_json()或表 6-1 中的一些其他方法)可以快速地为您找到表单的错误代码，以覆盖带有error_messages参数的消息。

字段布局值:标签、标签后缀、帮助文本

当你在一个模板中输出一个表单域时，除了基本的 HTML 表单域标记(例如<input type="text">)之外，它几乎总是伴随着一个人类友好的描述符来指示一个域是做什么用的(例如Email: <input type="text">)。这个对人友好的描述符被称为标签，在 Django 中默认情况下，它被赋予与字段名相同的值。

要定制一个表单域的标签，你可以使用label参数。例如，要为名为 email 的字段提供更具描述性的标签，可以使用语法email = EmailField(label="Please provide your email")。默认情况下，表单上的所有标签都带有一个:符号，它的作用相当于一个后缀。您可以使用单个表单字段或表单实例本身的label_suffix参数进一步定制字段标签的输出。

例如，语法email = EmailField(label_suffix='-->')覆盖了电子邮件字段中用于-->符号的默认后缀标签。

Tip

label_suffix 也可以用来初始化一个表单(例如，form = ContactForm(label_suffix='-->'))，这样所有的字段都会收到一个标签后缀，而不是一个字段一个字段地初始化。有关更多细节，请参见前面的“初始化表单”一节。

在某些情况下，向表单域添加更明确的说明会很有帮助；对于这种情况，您可以使用help_text参数。根据您使用的模板布局，help_text值被添加到 HTML 表单字段标记的右侧。

例如，语法comment = CharField(help_text="Please be as specific as possible to receive a quick response")生成紧挨着comment输入字段的给定的html_text值(例如Please be as specific as possible to receive a quick response <input type="text">)。下一节“在模板中设置 Django 表单的布局”将更详细地介绍help_text和其他表单布局属性的使用。

在模板中设置 Django 表单的布局

当您将 Django 表单(未绑定的或绑定的)传递给模板时，有许多选项可以生成它的布局。您可以使用 Django 的一个预构建的 HTML 助手来快速生成表单的输出，或者粒度化地输出每个字段来创建一个高级的表单布局(例如，响应式设计 ³ )。此外，还可以有许多方式来输出表单错误(例如，除了字段本身之外或者在表单的顶部)。接下来，我将描述在模板中输出 Django 表单的各种选项。

清单 6-19 显示了我将在其余布局部分使用的 Django 表单——这与本章中使用的表单相同。

from django import forms

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea)

Listing 6-19.Django form class definition

输出表单字段:form.as_table、form.as_p、form.as_ul 和按字段粒度

Django 表单提供了三个助手方法来简化所有表单字段的输出。语法form.as_table o 输出一个表单的字段来容纳一个 HTML <table>，如清单 6-20 所示。语法form.as_p输出带有 HTML <p>标签的表单字段，如清单 6-21 所示。Where as 语法form.as_ul输出一个表单的字段来容纳一个 HTML <ul>列表标签，如清单 6-22 所示。

Caution

如果您使用 form.as_table、form.as_p、form.as_ul，您必须声明开始/结束 HTML 标签、换行

<tr>
    <th><label for="id_name">Name:</label></th>
    <td><input id="id_name" name="name" type="text" /></td>
</tr>\n
<tr>
    <th><label for="id_email">Your email:</label></th>
    <td><input id="id_email" name="email" type="email" required/></td>
</tr>\n
<tr>
    <th><label for="id_comment">Comment:</label></th>
    <td><textarea cols="40" id="id_comment" name="comment" rows="10" required>\r\n</textarea></td>
</tr>
Listing 6-20.Django form output with form.as_table

<p>
    <label for="id_name">Name:</label> <input id="id_name" name="name" type="text" />
</p>\n
<p>
    <label for="id_email">Your email:</label> <input id="id_email" name="email" type="email" required/>
</p>\n
<p>
    <label for="id_comment">Comment:</label> <textarea cols="40" id="id_comment" name="comment" rows="10" required>\r\n</textarea>
</p>'
Listing 6-21.Django form output with form.as_p

<li>
    <label for="id_name">Name:</label> <input id="id_name" name="name" type="text" />
</li>\n
<li>
    <label for="id_email">Your email:</label> <input id="id_email" name="email" type="email" required/>
</li>\n
    <li><label for="id_comment">Comment:</label> <textarea cols="40" id="id_comment" name="comment" rows="10" required>\r\n</textarea>
</li>
Listing 6-22.Django form output with form.as_ul

Tip

通过用auto_id=False初始化表单，可以使form.as_table、form.as_p & form.as_ul输出不那么冗长——省略标签和 id 属性。此外，您还可以通过使用label_suffix变量初始化表单，来更改分隔标签名称的符号(默认为:)和另一个符号。也可以使用field_order选项改变输出场顺序。

在某些情况下，前面的帮助器方法都不足以实现特定的表单布局。例如，要创建响应式设计，您需要手动输出每个字段，以适应特定的布局要求(例如，引导 CSS 网格列)。为了实现字段的自定义输出，每个表单实例都允许使用表 6-3 中的属性通过form.<field_name>语法访问其字段。

表 6-3。

Django form field attributes accessible in templates

| 属性名 | 描述 | | --- | --- | | { {表单。 }}(即没有属性，只有字段名本身) | 输出与字段相关联的 HTML 表单标记——技术上称为 Django 小部件(例如，)。) | | { {表单。。姓名}} | 输出在 form 类中定义的字段名称。 | | { {表单。。值}} | 输出分配了初始数据或用户提供的数据的字段的值。如果您需要单独输出 HTML 表单标记的 value 属性(例如，对于，{{form.name.value}}输出 John Doe)，这很有用。 | | { {表单。。标签}} | 输出字段的标签，默认情况下使用语法“您的”(例如，对于电子邮件字段，{{form.email.label}}输出您的电子邮件)。 | | { {表单。。id_for_label}} | 输出字段的标签 id，默认情况下使用语法 id_ (例如，对于电子邮件字段，{ { form . email . id _ for _ label } } outputs id _ email)。 | | { {表单。。auto_id}} | 输出字段的自动 id，默认情况下使用语法 id_ (例如，对于电子邮件字段，{{form.email.auto_id}}输出 id_email)。 | | { {形式.。label_tag} | Helper 方法输出 HTML 标签以及 id_for_label 和 label(例如，对于 email 字段，{{form.email.label_tag}}输出您的电子邮件:)。 | | { {表单。。help_text}} | 输出与字段相关的帮助文本。 | | { {表单。。错误}} | 输出与字段相关的错误。 | | { {表单。。css_classes}} | 输出与字段关联的 CSS 类。 | | { {表单。。as_hidden}} | 将字段的 HTML 输出为隐藏的 HTML 字段(如)。 | | { {表单。。is_hidden}} | 字段隐藏状态的布尔结果。 | | { {表单。。as_text}} | 将字段的 HTML 输出为文本 HTML 字段(如)。 | | { {表单。。as_textarea}} | 将字段的 HTML 输出为 textarea HTML 字段(如 )。 | | { {表单。。as_widget}} | 输出与字段相关联的 Django 小部件；从技术上讲，生成的输出与使用语法{ { form }调用独立字段的输出相同。} }–显示在此表格的顶部。 |

Tip

通过使用表单字段上的label、label_suffix和help_text选项，您可以覆盖表格 6-4 中{{form.<field_name>.label}}的默认输出、{{form.<field_name>.label_tag}}的后缀和{{form.<field_name>.help_text}}的默认输出。这个过程在上一节“Django 表单域类型:小部件、选项和验证”中有描述

正如您在表 6-4 中看到的，有许多字段属性可用于定制表单的布局。只是要小心，如果你输出的表单字段很细，你不会错过一个字段，因为如果你错过了一个字段，最有可能的结果是 Django 将无法处理表单，因为它不会从丢失的字段接收值。

表 6-4。

FORM_RENDERER values that influence finding and loading custom widget templates

| 表单渲染器类 | 描述 | | --- | --- | | django . forms . renderers . django templates(默认) | 从内置的 django/forms/templates/目录(即发行版)中搜索并加载小部件模板。从 INSTALLED_APPS 中声明的应用内的所有模板目录中搜索并加载小部件模板。 | | django . forms . renderers . jinja templates | 从内置的 django/forms/jinja2/目录(即发行版)中搜索并加载小部件模板。从 INSTALLED_APPS 中声明的应用内的所有 jinja2 目录中搜索并加载小部件模板。 | | django . forms . renderers . templates 设置 | 基于项目的模板配置(例如，其 DIRS 值)搜索和加载微件模板。注意:这个渲染器要求您将 django.forms 包声明为 INSTALLED_APPS 的一部分。 |

清单 6-23 展示了一个标准的{% for %}循环，它确保你不会错过任何字段，并提供了比之前的form.as_table、form.as_p & form.as_ul方法更大的灵活性。

{% for field in form %}
    <div class="row">
       <div class="col-md-2">
        {{ field.label_tag }}
        {% if field.help_text %}
          <sup>{{ field.help_text }}</sup>
        {% endif %}
        {{ field.errors }}
       </div><div class="col-md-10 pull-left">
         {{ field }}
       </div>
    </div>
 {% endfor %}
Listing 6-23.Django form {% for %} loop over all fields

在清单 6-23 中，在form引用上创建了一个循环，以确保没有字段被遗漏。如果您想避免在某些表单布局中显示某个字段，那么我建议您使用{{field.as_hidden}} vs. {{field}}，因为这样可以确保该字段仍然是表单的一部分，以便进行验证，并且只是对用户隐藏——关于这种情况的更多细节将在下一节高级表单处理和部分表单中提供。

输出字段顺序:field_order 和 order_fields

如果您使用清单 6-20 、 6-21 、 6-22 或 6-23 中介绍的任何技术，表单字段的输出顺序与它们在清单 6-19 的表单类中声明的顺序相同(即姓名、电子邮件、评论)。但是，您可以使用几种技术来改变表单域的输出顺序。

第一种也是最明显的方法是直接在表单类定义中改变表单字段的顺序。因为最后一种技术需要修改表单的源代码，Django 还提供了field_order选项。field_order选项按照您希望它们输出的顺序接受表单字段名列表(例如，field_order=['email','name','comment']首先输出email字段，然后是name和comment)。field_order选项非常灵活，您可以提供表单域的部分列表(例如，field_order=['email']首先输出电子邮件域，其余的表单域按照它们声明的顺序输出)，还可以声明不存在的域名，这些域名会被忽略，在使用表单继承时非常有用。

可以在两个位置声明field_order选项。首先，它可以被声明为表单类定义的一部分，如清单 6-24 所示。

from django import forms

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea)
      field_order = ['email','comment','name']

Listing 6-24.Django form field_order option to enforce field order

正如您在清单 6-24 中看到的，field_order被声明为任何其他表单字段，并被分配了一个字段名列表，以确保这些字段按顺序输出:电子邮件、评论和名称。也可以使用field_order选项作为表单初始化过程的一部分——在表单处理部分有详细描述。值得一提的是，如果在类定义(如清单 6-24 所示)和表单实例初始化上都使用了field_order选项，那么后者的值优先于前者。

除了field_order选项，Django 还提供了order_fields,它也希望字段名列表能够改变表单的输出字段顺序。但是与必须在表单类中声明或作为表单实例初始化的一部分的field_order选项不同，order_fields可以直接在表单实例上调用，这使得它成为在视图方法或模板中使用的一个好选项(例如，form.order_fields(['email']))。

输出 CSS 类、样式和字段属性:error_css_class、required_css_class、小部件、定制和各种表单字段选项

默认情况下，当您输出表单字段和标签时，没有与它们相关联的 CSS 类或样式。Django 提供了几种将 CSS 类与表单字段关联起来的机制。前两种方法是error_css_class和required_css_class字段，它们以 Django 形式直接声明，如清单 6-25 所示。

from django import forms

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email')
      comment = forms.CharField(widget=forms.Textarea)
      error_css_class = 'error'
      required_css_class = 'bold'

Listing 6-25.Django form error_css_class and required_css_class

fields to apply CSS formatting

正如您在清单 6-25 中看到的，error_css_class和required_css_class字段被添加，就像常规的表单字段一样。当与这种表单实例相关联的字段呈现在模板上时，Django 将error CSS 类添加到所有标记有错误的字段中，并将bold CSS 类添加到所有标记为必需的字段中。

例如，除了明确使用required=False时，所有表单域都被视为必需的。这意味着如果您使用form.as_p输出清单 6-25 中的一个未绑定表单实例，那么注释字段将输出为<p class="bold">Comment: <textarea cols="40" name="comment" rows="10" required>\r\n</textarea></p>——注意<p>标签中的class。类似地，如果与清单 6-25 中的绑定表单实例相关联的字段出现错误，Django 会将error CSS 类添加到该字段中(例如，如果 email 字段值无效，email 字段会输出为<p class="bold error">Your email: <input name="email" type="email" value="aninvalidemail" required /></p>，注意bold CSS 类会保留，因为表单字段也是必需的)。

尽管error_css_class和required_css_class字段很有帮助，但它们仍然提供有限的 CSS 格式化功能。为了获得对 CSS 类输出的完全控制，你需要对表 6-4 中的字段使用一些更细粒度的输出选项，或者定制一个表单字段的小部件，如清单 6-26 所示。

from django import forms

class ContactForm(forms.Form):
      name = forms.CharField(required=False)
      email = forms.EmailField(label='Your email', widget=forms.TextInput(attrs={'class' : 'myemailclass'}))
      comment = forms.CharField(widget=forms.Textarea)

Listing 6-26.Django form with inline widget definition to add custom CSS class

注意清单 6-26 中的 email 字段是如何用widget=forms.TextInput(attrs={'class' : 'myemailclass'})参数声明的。最后一条语句告诉 Django，当它输出email字段时，它使用定制的forms.TextInput小部件，该小部件用myemailclass值声明 CSS class属性。

通过使用清单 6-26 中的表单定义，email字段被输出为<input class="myemailclass" type="text"...>。如果您不知道什么是 Django 小部件，请参阅前面题为“小部件和表单字段之间的关系”的部分

清单 6-26 中介绍的方法是一种强大的技术，因为正如您可以声明 CSS class属性一样，您也可以声明任何其他表单域 HTML 属性。例如，如果你想声明定制的 HTML 属性——比如那些被像 jQuery 或 Bootstrap 这样的框架使用的属性——你可以很容易地使用同样的技术(例如，widget=forms.TextInput(attrs={'role' : 'dialog'})将输出<input role="dialog" type="text"...>)。

但是，现在需要注意的是，您已经知道在 Django 表单字段旁边输出任何 HTML 属性是多么容易。请注意，几乎所有 Django 表单字段数据类型都带有内置选项，可以转换成 HTML 属性。例如，forms.CharField(max_length=25)语句输出到<input type="text" maxlength="25"...>，这意味着表单字段max_length选项自动生成 HTML maxlength="25"属性。所以在开始使用清单 6-26 中的方法添加 HTML 属性时要小心，因为它们可能已经被内置的数据类型选项所支持。有关这些内置数据类型选项的更多细节，请参见上一节“Django 表单字段类型:小部件、选项和验证”。

输出表单域错误:表单。<field_name>。错误，表单.错误，表单. _ field _ 错误</field_name>

正如表单域可以用不同的方式输出一样，表单域错误也可以用不同的方式输出。在清单 6-23 第一部分的末尾，您可以看到我们如何使用{{field.errors}}语法来输出与特定字段相关的错误。然而，当以这种方式输出字段的errors值时，需要记住的一件重要事情是，输出是作为 HTML 格式的列表生成的:

<ul class="errorlist">
    <li>Name is required.</li>
</ul>

正如你在清单 6-27 中看到的，{{fields.errors}}值是带有errorlist CSS 类的列表——这允许你提供 CSS 行为，如背景颜色或边框——并且这些值被预先包装成列表元素。

如果你想去掉这些包装的 HTML 列表标签以获得对错误布局的更多控制(例如，创建一个响应式设计或 CSV 列表)，你可以在每个field.errors上创建一个循环，如清单 6-27 所示。

 {% for field in form %}
    <div class="row">
      <div class="col-md-2">
        {{ field.label_tag }}
        {% if field.help_text %}
          <sup>{{ field.help_text }}</sup>
          {% endif %}
          {% for error in field.errors %}

           <div class="row">

             <div class="alert alert-danger">{{error}}</div>

           </div>

          {% endfor %}

       </div><div class="col-md-10 pull-left">
         {{ field }}
       </div>
    </div>
  {% endfor %}
Listing 6-27.Django loop over form.<field_name>.errors

您可以在清单 6-27 中看到，在每个字段的循环中，对field.errors引用进行了另一个循环，以粒度输出并为每个字段错误分配自定义标记。

正如清单 6-27 中的错误输出一样，这种布局假设除了需要在表单的字段上循环之外，你还想在每个字段旁边显示表单的错误信息。但是，如果您想在顶部或主表单旁边显示表单的错误，该怎么办呢？或者想继续使用 Django 的快捷方式(即form.as_table、form.as_p & form.as_ul)仍然显示错误？

除了清单 6-27 中的form.<field_name>.errors语法来访问字段错误之外，Django 还可以使用清单 6-28 中所示的errors和non_field_errors字典来输出表单的错误。

<!-- Field errors -->
 {% if form.errors %}
  <div class="row">
    {% for field_with_error,error_messages in form.errors.items %}
        <div class="alert alert-danger">{{field_with_error}}  {{error_messages}}</div>
    {% endfor %}
  </div>
  {% endif %}

<!-- Non-field errors -->
 {% if form.non_field_errors %}
  <div class="row">
    {% for error in form.non_field_errors %}
    <div class="alert alert-danger">{{error}}</div>
    {% endfor %}
  </div>
  {% endif %}

Listing 6-28.Django form.errors and form.non_field_errors

with custom HTML output

正如您在清单 6-28 中看到的，form.errors字典提供了所有form.<field_name>.errors的聚合版本，其中每个字典键代表表单字段名称，值是一个带有错误代码的错误消息列表(例如required)，以进一步过滤错误列表。如果你想在一个表单/页面的顶部输出每个表单错误，要求按照代码类型过滤错误，或者想继续使用 Django 的快捷输出表单方法(例如form.as_table)并获得表单错误，那么在模板上使用form.errors是一个不错的选择。

此外，注意清单顶部的 6-28 在form.non_field_errors字典上的循环。form.non_field_errors包含不属于特定表单域的错误——如前面“错误表单值:错误”一节所讨论的，以及名为__all__的特殊错误占位符域。因为非字段错误不适用于特定的表单字段，所以在访问non_field_errors字典的表单顶部输出这种类型的错误是很常见的。

请注意，如果您使用form.errors或form.non_field_errors来输出错误，默认情况下，错误引用——清单 6-28 中的{{error_messages}}和{{error}}——被包装为 HTML 格式的列表(例如<ul class="errorlist"><li>...</li></ul>),但是您可以向错误列表添加一个额外的 for 循环——如清单 6-27 所示——来创建一个定制的 HTML 错误布局。

最后，值得一提的是有一系列的辅助方法被设计来促进错误输出(例如，以 JSON 格式)；Django 表单处理部分的表 6-1 描述了这些方法。

Django 定制表单字段和小部件

在表 6-2 中，您看到了各种各样的内置 Django 表单字段，从基本的文本和数字类型到更专业的文本类型(如 CSV、预定义选项)，包括文件和目录类型。但是，尽管这些内置表单域非常广泛，在某些情况下，还是有必要构建自定义表单域。

类似地，在表 6-2 中，您了解了所有 Django 表单域是如何链接到 Django 窗口小部件的，这些窗口小部件定义了表单域产生的 HTML。在前面的章节中(例如，清单 6-25 和 6-26 )，您了解了如何使用表单字段的widget属性用自定义属性(例如，CSS class属性)覆盖它的默认小部件，或者给它分配一个完全不同的小部件(例如，forms.Textarea小部件分配给forms.CharField字段)，在某些情况下，使用 Django 的内置小部件(例如，添加属性或切换一个内置小部件

接下来，您将学习如何定制 Django 表单字段和小部件。

Customize Django Form Fields, Widgets, or Both?

正如您在本章中学到的，表单域和表单小部件之间存在模糊关系，当内置选项不足时，很难决定定制哪一个。

根据经验，如果您需要经常更改表单域的数据或验证逻辑，您应该使用自定义表单域。如果您需要不断地改变表单域的 HTML 输出(例如，表单标签、CSS 类、JavaScript 事件)，您应该使用定制的小部件。

创建自定义表单域

与其他定制 Django 构造(例如，定制模板过滤器或上下文处理器)相比，创建定制表单字段的好消息是您不必从头开始编写所有内容。由于 Django 的内置表单字段是从forms.Form类继承其行为的子类，所以您可以将内置表单字段进一步子类化为更专业的表单字段。因此，自定义表单域可以从内置表单域中的一组基本功能开始，然后您可以根据需要对其进行自定义。

例如，如果您发现自己在使用内置的forms.FileField创建表单，并不断地以某种方式对其进行自定义(例如，针对某些文件大小或类型)，您可以创建一个自定义表单字段(例如，PdfFileField、MySpecialFileField)，它继承了forms.FileField的行为，对其进行自定义，并直接在您的表单中使用该自定义表单字段。

清单 6-29 展示了一个定制表单域，它从内置的forms.ChoiceField表单域继承了它的行为。

class GenderField(forms.ChoiceField):
      def __init__(self, *args, **kwargs):
            super(GenderField, self).__init__(*args, **kwargs)
            self.error_messages = {"required":"Please select a gender, it's required"}
            self.choices = ((None,'Select gender'),('M','Male'),('F','Female'))
Listing 6-29.Django custom form field inherits behavior from forms.ChoiceField

正如您在清单 6-29 中看到的，GenderField类从内置的forms.ChoiceField字段类中继承了它的行为，使它能够自动访问与后一个类相同的行为和特性。接下来，__init__方法——用于初始化类的实例——调用super(),以确保父类(即forms.ChoiceField)的初始化过程完成，并在值被分配给error_messages和choices字段后立即执行。

清单 6-29 中的error_messages和choices字段可能看起来很熟悉，因为它们是内置forms.ChoiceField中通常使用的参数，也是本章前面描述的 Django 标准表单字段参数的一部分。您可以类似地添加表单域支持的任何其他参数(例如，self.required、self.widget)，以便使用表单域参数设置的行为创建自定义表单域。

一旦你有了一个定制的表单域，如清单 6-29 所示，你就可以用它在 Django 表单类中声明一个表单域(例如，gender = <pkg_location>.GenderField() vs. gender = forms.ChoiceField(error_messages={...},choices=...))。如您所见，如果您要对内置表单域进行重复的自定义，自定义表单域是一个很好的选择。

自定义内置小部件

在清单 6-25 和 6-26 中，您已经探索了一些与 Django 内置部件相关的定制。例如，在清单 6-25 中，您看到了如何定制分配给表单字段的默认内置小部件，而在清单 6-26 中，您看到了如何向内置小部件添加定制属性。在本节中，您将学习如何全局定制内置小部件。

回头看看表 6-2 ，你可以看到，例如，forms.widget.TextInput()小部件产生一个类似于<input type="text" ...>的 HTML 输出，类似地，表 6-2 中的所有其他小部件产生它们自己特定的 HTML 输出。

考虑到许多前端设计提出的高期望，对于许多 Django 项目来说，生成这种类型的基本样板 HTML 输出是不可能的。例如，如果您想将 JavaScript jQuery 或 ReactJS 逻辑紧密集成到 HTML 表单中，那么定制由 Django 的内置小部件生成的默认 HTML 可能是必要的。在这种情况下，理想的方法是为 Django 的内置小部件生成定制的 HTML，放弃使用 Django 在开箱即用状态下定义的默认标记。

关于定制 Django 的内置小部件，您需要知道的第一件事是 Django 在哪里保存它的默认内置小部件。Django 从 Django 主发行版中的django/forms/templates/django/forms/widgets/目录中的 Django 模板为其内置小部件构建 HTML 输出(例如，如果您的 Python 安装位于/python/coffeehouse/lib/python3.5/site-packages/，则附加此目录路径以定位小部件模板)。

如果查看最后一个目录，您会发现每个内置 Django 小部件的模板(例如，input.html、radio.html)。请注意，所有这些小部件模板都不使用普通的 HTML，而是使用 Django 模板语法(例如，{% include %}标签，{% if %}条件)来支持代码重用。如果你对 Django 模板语法不熟悉，请查看第三章。

现在，虽然您可以在这个位置直接修改模板来改变每个小部件产生的 HTML 输出，但是不要这样做。为每个内置小部件定制输出的推荐方法是基于项目包含定制的内置小部件。因此，定制 Django 内置小部件的第一步是构建定制的内置小部件，并使它们成为 Django 项目的一部分。

Tip

将 Django 发行版中所有内置的小部件(即django/forms/templates/django/forms/widgets/中的模板)复制到您的项目中，并根据需要进行修改。

因为内置的小部件是 Django 模板，它们需要放在一个可以被发现的项目目录中。这意味着定制的内置小部件必须放在项目目录中，该目录是在settings.py的TEMPLATES变量中声明的DIRS列表的一部分。在大多数情况下，一个项目声明一个名为templates的目录——作为DIRS的一部分——它也包含一个项目的模板——但是你可以使用任何目录，只要它被声明为DIRS的一部分——参见第三章中的“模板搜索路径”一节以获得关于DIRS的更多细节。

除了使用属于DIRS列表的一部分的目录来定位小部件模板，Django 还期望在用于其默认内置小部件的相同路径中定位定制内置小部件(即，包括在 Django 发行版中的那些)。

因此，如果您有一个名为templates的项目目录作为DIRS列表的一部分，那么在这个templates目录中，您将需要创建相同的目录路径django/forms/widgets/，并且在这个最后的widgets子目录中放置定制的内置小部件(例如，要在django/forms/templates/django/forms/widgets/input.html定制位于 Django 发行版中的内置input.html小部件，您将在<project_dir>/templates/django/forms/widgets/input.html创建一个项目版本，这样后面的input.html模板优先于默认的内置发行版模板)。

一旦在项目中设置了定制的内置小部件，就需要对项目的settings.py进行两项配置更改。第一个配置要求您添加FORM_RENDERER变量，如下所示:

FORM_RENDERER = 'django.forms.renderers.TemplatesSetting'

默认情况下，Django 内置的小部件是通过独立的 Django 模板渲染器django.forms.renderers.DjangoTemplates加载的，该渲染器与包含项目模板的DIRS列表的项目主TEMPLATES配置无关。因为您现在将定制的内置小部件放在声明为DIRS列表的一部分的目录中，所以您需要配置 Django 来使用项目的主TEMPLATES配置，作为表单呈现过程的一部分。通过将FORM_RENDERER变量设置为django.forms.renderers.TemplatesSetting，Django 还会检查主TEMPLATES配置的DIRS列表中的路径，以查找内置的小部件。关于小部件的最后一小节提供了关于FORM_RENDERER变量的更多细节。

最后，因为您正在覆盖项目中的django.forms包以获得定制的内置部件，所以您还必须将django.forms包声明为settings.py中的INSTALLED_APPS列表的一部分。

创建自定义表单小部件

定制表单小部件用于需要保持 Django 内置小部件功能不变，但仍需要定制小部件产生的 HTML 输出的情况。

Tip

在创建定制表单小部件之前，仔细查看表 6-2 中的内置小部件和侧栏“Django 隐藏内置小部件”中的小部件您也许能够找到您正在寻找的东西，而不需要创建自定义的小部件。

与定制表单域类似，定制表单小部件具有基于类的优势，因此可以从内置小部件继承它们的行为。例如，如果您发现自己经常以某种方式定制内置的forms.widgets.TextInput小部件(例如，HTML 属性或 JavaScript 事件)，您可以创建一个从forms.widgets.TextInput继承其行为的定制小部件(例如，CustomerWidget、EmployeeWidget)，对其进行定制，并直接在表单字段中使用定制小部件。

例如，假设您一直在修改 Django 文本小部件，使其包含 HTML 5 placeholder属性——该属性用于向最终用户提示输入表单字段的用途，当用户关注某个字段时，该属性就会消失。清单 6-30 展示了一个定制表单小部件，它基于分配给小部件的字段name属性生成 HTML 5 placeholder属性。

class PlaceholderInput(forms.widgets.Input):
      template_name = 'about/placeholder.html'
      input_type = 'text'
      def get_context(self, name, value, attrs):
            context = super(PlaceholderInput, self).get_context(name, value, attrs)
            context['widget']['attrs']['maxlength'] = 50
            context['widget']['attrs']['placeholder'] = name.title()
            return context
Listing 6-30.Django custom form widget inherits behavior from forms.widgets.Input

Note

forms.widgets.Input窗口小部件是比forms.widgets.TextInput更通用的窗口小部件，不包括文本输入行为；因此，由于它的基本特性集，它通常是构建定制小部件的首选。值得一提的是forms.widgets.Input是forms.widgets.TextInput、forms.widgets.NumberInput、forms.widgets.EmailInput以及表 6-2 中描述的其他输入控件的父控件。

正如您在清单 6-30 中看到的，PlaceholderInput类从内置的forms.widgets.Input小部件类继承了它的行为，使它能够访问与后者相同的行为和特性。

接下来是两个类字段。template_name字段定义了自定义小部件的支持模板，该模板指向'about/placeholder.html'–注意，如果您省略了template_name字段，则使用父类模板(即对于forms.widgets.Input小部件，模板是django/forms/widgets/input.html)。input_type字段是forms.widgets.Input子类所必需的，用于分配 HTML 输入type属性，值可以包括:text、number、email、url、password或任何其他有效的 HTML 输入type值。

自定义小部件类内部是get_context()方法，用于设置支持小部件模板的上下文——就像标准 Django 模板一样。在这种情况下，调用super()以确保设置了父窗口小部件类模板(即forms.widgets.Input)的上下文，并且紧接着在['widget']['attrs']字典中的窗口小部件上下文上设置了一对属性——maxlength和placeholder——以便在窗口小部件模板内使用。注意maxlength的值是固定的，而placeholder的值取自字段name属性，并使用 Python 的标准title方法转换为标题。最后，get_context()方法返回更新后的context引用，将其传递给小部件模板。

现在让我们看看清单 6-31 中的小部件模板'about/placeholder.html'。

# about/placeholder.html
<input type="{{ widget.type }}" name="{{ widget.name }}"{% if widget.value != None %} value="{{ widget.value }}"{% endif %}{% include "django/forms/widgets/attrs.html" %} />

# django/forms/widgets/attrs.html
{% for name, value in widget.attrs.items %}{% if value is not False %} {{ name }}{% if value is not True %}="{{ value }}"{% endif %}{% endif %}{% endfor %}

Listing 6-31.Django custom form widget inherits behavior from forms.widgets.Input

您可以在清单 6-31 中看到，HTML input标签是用通过get_context方法设置的widget字典中的值生成的。widget.type、widget.name和widget.value的值都是在父类(即forms.widgets.Input)中后台设置的。此外，注意 HTML input标签使用了清单 6-31 底部所示的内置小部件模板django/forms/widgets/attrs.html。最后一个小部件模板循环遍历widgets.attrs上下文字典中的所有元素，并生成input属性。由于清单 6-30 中的widgets.attrs上下文字典被修改为包含maxlength和placeholder属性，所以input标签是用这些附加属性生成的(例如<input type="text" name="email" maxlength="50" placeholder="Email">)。

现在让我们后退一步来讨论一下'about/placeholder.html'小部件模板的位置。默认情况下，Django 定制小部件只在INSTALLED_APPS中定义的所有 Django 应用的templates文件夹中搜索。这意味着，为了让 Django 找到定制的'about/placeholder.html'小部件模板，它必须放在任何项目应用的templates文件夹中(例如，给定一个名为about的项目应用，定制小部件应该位于templates/about/placeholder.html下，其中templates文件夹与应用的models.py和views.py文件在同一级别)。在全局目录上定义定制的小部件是可能的，但是我将在关于小部件的最后一小节中讨论这一点。

最后，一旦在正确的位置定义了定制小部件，就可以将它作为 Django 表单字段的一部分(例如，email=forms.EmailField(widget=<pkg_location>.PlaceholderInput))来生成一个带有默认placeholder属性的 HTML input标签。

自定义表单小部件配置选项

在前两节关于定制表单小部件的内容中，为了避免偏离手头的主要任务，我没有提到各种配置选项。但是现在您已经知道了如何定制 Django 的内置小部件以及如何创建定制表单小部件，我可以为您提供这些额外的细节。

第一个主题与查找和加载定制小部件模板有关。Django 通过settings.py中的FORM_RENDERER变量定义了一个表单渲染器。表 6-4 描述了FORM_RENDERER变量支持的三个不同值。

正如你在表 6-4 中看到的，除了前面章节中使用的其他渲染器之外，甚至还有一个 Jinja 模板渲染器允许你定制由 Jinja 模板支持的部件。

在清单 6-30 中，您了解了定制小部件类如何使用字段(例如template_name、input_type)来指定某些行为。小部件类中的字段高度依赖于父小部件类。例如，尽管template_name对所有内置小部件都有效，但是更特殊的内置小部件可以接受额外的字段。如果有疑问，请查阅用作小部件父类的内置小部件 ⁴ 支持的字段。

在清单 6-30 中，您还学习了如何通过get_context()方法访问和修改小部件的模板上下文。虽然在清单 6-30 中，您只向context['widget']['attrs']字典添加了几个小部件属性，但是父context['widget']字典是一个大型数据结构，存储了与小部件相关的所有数据，您可以在其中包含更新小部件的字段值。下面的代码片段展示了使用清单 6-30 中的PlaceholderInput小部件类的表单字段的context['widget']的内容。

{'widget': {'attrs': {'placeholder': 'Email', 'maxlength': 50}, 'name': 'email', 'is_hidden': False, 'type': 'text', 'value': None, 'template_name': 'about/placeholder.html', 'required': True}}

正如您所看到的，除了存储在attrs键下的 HTML 输入属性之外，还有其他的widget字段键(例如name、is_hidden)可以在模板中使用，以呈现最终的输出。这也意味着您可以在get_context()方法中向context['widget']字典添加自定义数据键，将它们集成为最终模板布局的一部分(例如'react':{<react_data>}、'jquery':{<jquery_data>}).

Django 高级表单处理:部分表单、AJAX 和文件

在大多数情况下，Django 表单处理遵循本章第一节概述的步骤和代码序列，如图 6-1 所示。然而，Django 表单处理可能需要针对某些场景进行小的调整，比如涉及部分表单处理、AJAX 表单和文件上传的场景。

部分表单

有时，您可能会发现自己需要使用基于预先存在的 Django 表单的部分表单。例如，您收到一个请求，请求将一个类似的表单添加到目前使用的ContactForm中——在清单 6-25 中——但是不需要name和email字段。由于ContactForm经过了测试，包括必要的后处理逻辑(例如，将表单数据添加到 CRM(客户关系管理)系统)，重用ContactForm类是一个值得考虑的想法。但是如何部分地使用 Django 表单呢？

实现部分表单的第一种方法是对用户隐藏不需要的表单字段，允许原始表单类保持不变，同时不需要新的子类。这是侵入性最小的方法，但是您需要注意两个方面。第一个方面是表单模板布局，如清单 6-32 所示。

<form method="POST">
  {% csrf_token %}
    <div class="row">
      <div class="col-md-2">
        {{ form.comment.label_tag }}
          {% if form.comment.help_text %}
          <sup>{{ form.comment.help_text }}</sup>
          {% endif %}
          {% for error in form.comment.errors %}
           <div class="row">
             <div class="alert alert-danger">{{error}}</div>
           </div>
          {% endfor %}
       </div><div class="col-md-10 pull-left">
         {{ form.comment }}
       </div>
    </div>
    {{form.name.as_hiddden}}

    {{form.email.as_hidden}}

<input type="submit" value="Submit form" class="btn btn-primary">
</form>
Listing 6-32.Django form with fields marked as hidden

首先注意清单 6-32 中的表单字段是单独输出的，不使用快捷方式(如form.as_table)或像前面的一些表单布局例子那样循环。原因是，最后的form字段通过as_hidden方法被显式输出为隐藏——如表 6-4 所述。as_hidden方法生成一个表单域作为隐藏的 HTML 输入(如<input type="hidden"...>)，不管它的表单域数据类型。这种机制有效地对最终用户隐藏了字段，但是将字段作为表单的一部分保留下来。

为什么将字段保留为表单的一部分而不仅仅是删除它们很重要？验证。记住表单实例没有变，只有需求变了；您可能不需要这个模板页面上的name和email数据，但是表单实例和验证逻辑不知道这一点。所有这些把我们带到了你需要注意的第二个方面:必需的值。

如果您发布清单 6-32 中的模板而没有考虑第二个方面，当您意识到表单从未通过验证时，您可能会感到惊讶！为什么呢？底层的ContactForm类根据需要处理email字段，因此必须给它一个值，但是由于该字段现在对最终用户是隐藏的，您必须自己给email字段赋值——注意name字段不存在这个问题，因为它是用required=False配置的。因此，为了让清单 6-32 中的模板工作，表单必须用一个值初始化，如下所示:

form = ContactForm(initial={'email':'anonymous@gmail.com'})

通过以这种方式初始化表单，电子邮件表单字段被赋予这个初始值作为隐藏输入。因此，一旦用户提交表单，email 值就作为表单的一部分被传输回 Django，在那里通过验证，因为后处理逻辑得到了所有预期的值。当然，如果表单的字段都是可选的(也就是说，它们标有required=False，这个初始化过程是不必要的，因为验证无论如何都不会期望任何值。

实现部分表单的第二种方法是从表单类创建一个子类，并删除不需要的字段。这是一种更简单的方法，但是它需要创建一个 form 子类，这对于某些场景来说可能是多余的。清单 6-33 展示了如何子类化 Django 表单类并移除其父类的一些字段。

from coffeehouse.about.forms import ContactForm

class ContactCommentOnlyForm(ContactForm):
    def __init__(self, *args, **kwargs):
        super(ContactCommentOnlyForm, self).__init__(*args, **kwargs)
        del self.fields['name']
        del self.fields['email']

Listing 6-33.Django form subclass with removed parent fields

正如您在清单 6-33 中看到的，ContactCommentOnlyForm表单从ContactForm类继承了它的行为。接下来，在表单类__init__方法中，通过super()调用父类的__init__，并使用 Python 的del对self.fields进行两次调用，从表单子类中删除name和email字段。

一旦有了清单 6-33 中的表单子类，就可以在视图方法中生成一个未绑定的实例表单，并将其传递给模板进行呈现。由于最后一个子类删除了name和email字段，所以在验证时，您不会遇到前面描述的隐藏字段缺少值的问题，因为ContactCommentOnlyForm表单现在只有一个字段。

AJAX 表单提交

AJAX 是一种技术，其中网页上的 JavaScript 与服务器端应用通信，并根据通信结果重新呈现网页，所有这些都不需要网页转换。Django 表单通常被设计成通过 AJAX 提交数据，以创建更流畅的工作流(即，不需要用 web 表单改变原始的 web 页面)

就初始表单交付而言，使用 AJAX 的表单的工作流程(图 6-1 中的步骤 1 和 2)与常规 Django 非 AJAX 表单的工作流程相同:在 view 方法中创建一个未绑定的表单实例，该实例被传递给一个模板，以呈现给最终用户的 web 页面。

通过 AJAX 提交数据的 Django 表单的第一个不同之处是，交付未绑定表单的网页必须包含必要的 JavaScript 逻辑，以便将表单数据发送到服务器端应用，并处理服务器端响应。清单 6-34 展示了使用 jQuery 库通过 AJAX 提交 Django 表单的 JavaScript 逻辑。

# NOTE: The following is only the Django (HTML) template with AJAX logic
# See Listing 6-35 for AJAX processing views.py and urls.py
<h4>Feedback</h4>
<div class="row">
  <div id="feedbackmessage"</div>
</div>
<form method="POST" id="feedbackform" action="{% url 'stores:feedback' %}">
  {% csrf_token %}
    <div class="row">
      <div class="col-md-12 pull-left">
         {{ form.comment }}
       </div>
    </div>
    {{form.name.as_hiddden}}
    {{form.email.as_hidden}}
<input type="submit" value="Submit feedback" class="btn btn-primary">
</form>

<script>
$(document).ready(function() {
    $("#feedbackform").submit(function(event) {
       event.preventDefault();
       $.ajax({ data: $(this).serialize(),
                type: $(this).attr('method'),
                url: $(this).attr('action'),
                success: function(response) {
                     console.log(response);
                     if(response['success']) {
                         $("#feedbackmessage").html("<div class='alert alert-success'>Succesfully sent feedback, thank you!</div>");
                         $("#feedbackform").addClass("hidden");
                     }
                     if(response['error']) {
                         $("#feedbackmessage").html("<div class='alert alert-danger'>" + response['error']['comment'] +"</div>");
                     }
                },
                error: function (request, status, error) {
                     console.log(request.responseText);
                }
       });
   });
})
</script>

Listing 6-34.JavaScript jQuery logic to submit Django form via AJAX

清单 6-34 的第一部分是标准的 Django 表单布局。然而，请注意<form>标签包含了action属性。在以前的 Django 表单中，没有使用action属性，因为服务 URL——GET 请求——和处理 URL——POST 请求——是同一个属性。在清单 6-34 中，action属性明确地告诉浏览器应该将 POST 请求发送到哪个 url——在本例中,{% url 'stores:feedback' %}是一个 Django 模板标签，它被翻译成一个 URL(例如/stores/feedback/)。在这种情况下，不同的 URL 是必要的，因为处理 AJAX 请求/响应的 Django 视图方法不同于处理标准 web 请求/响应的 Django 视图方法。

现在让我们把注意力转向清单 6-34 的下半部分和包含在<script>标签中的 JavaScript 逻辑。简而言之——因为描述 jQuery 语法超出了我们的讨论范围——网页等待点击#feedbackform表单的提交按钮。一旦检测到这个点击，使用表单数据的 AJAX POST 请求将被发送到表单的action属性中定义的 url。AJAX 请求完成后(即服务器端发回响应时)，将分析 JSON 格式的响应。如果 AJAX 响应包含一条success消息，则该消息输出在表单的顶部，并且表单被隐藏以避免多次提交。如果 AJAX 响应包含一条error消息，该消息将输出到表单的顶部。

现在您已经知道 Django 表单数据是如何通过 AJAX 提交到服务器端的，清单 6-35 展示了处理这个 AJAX 请求有效负载所必需的 Django 视图方法。

# urls.py (Main)
urlpatterns = [
    url(r'^stores/',include('coffeehouse.stores.urls',namespace="stores"))
]

# urls.py (App stores)
urlpatterns = [
    url(r'^$',views.index,name="index"),
    url(r'^feedback/$',views.feedback,name="feedback"),
]

# views.py (App stores)
from django.http import HttpResponse, JsonResponse
from coffeehouse.about.forms import ContactForm

def feedback(request):
    if request.POST:
        form = ContactForm(request.POST)
        if form.is_valid():
            return JsonResponse({'success':True})
        else:
            return JsonResponse({'error':form.errors})
    return HttpResponse("Hello from feedback!")

Listing 6-35.Django view method to process Django form via AJAX

关于清单 6-35 中的视图方法，最重要的一点是它只处理 POST 请求。注意，如果if request.POST:语句不为真，view 方法总是用Hello from feedback!字符串来响应。

接下来，在request.POST段中，流程开始时非常类似于标准 Django 表单处理序列(即，创建一个绑定表单实例，并调用表单的is_valid()方法来验证用户提供的数据)。但是，请注意使用JsonResponse()的有效和无效表单数据的响应。因为 AJAX 表单提交是在 JavaScript 上下文中操作的，所以 JSON 格式响应是一种常见的格式，用于将响应发送回浏览器。

如果您将注意力转回到清单 6-34 ，您可以看到 JavaScript 逻辑被设计为处理和输出清单 6-35 中的 view 方法返回的 JSON 响应(success或error)。

表单中的文件

Django 提供了几个表单域来通过表单捕获文件——如表 6-2 中描述的forms.ImageField()和forms.ImageField()。然而，尽管这些表单域生成必要的 HTML 和验证逻辑来强制文件通过表单提交，但是在表单中处理文件还是有一些微妙之处。

第一个问题是用于传输文件的表单的 HTML <form>标签必须显式地将编码类型设置为enctype="multipart/form-data"，此外还要使用method=POST。第二个问题是文件的内容被放在 Django request对象的特殊FILES字典键下。清单 6-36 展示了一个带有文件字段的表单，它对应的视图方法，以及它的模板布局。

# forms.py
from django import forms

class SharingForm(forms.Form):
    # NOTE: forms.PhotoField requires Python PIL & other operating system libraries,
    #       so generic FileField is used instead
    video = forms.FileField()
    photo = forms.FileField(widget=forms.ClearableFileInput(attrs={'multiple': True}))

# views.py
def index(request):
    if request.method == 'POST':
        # POST, generate form with data from the request
        form = SharingForm(request.POST,request.FILES)
        # check if it's valid:
        if form.is_valid():
            # Process file data in request.FILES
            # Process data, insert into DB, generate email,etc
            # redirect to a new URL:
            return HttpResponseRedirect('/about/contact/thankyou')
    else:
        # GET, generate blank form
        form = SharingForm()
    return render(request,'social/index.html',{'form':form})

# social/index.html
<form method="post" enctype="multipart/form-data">
  {% csrf_token %}
  <ul>
    {{form.as_ul}}
  </ul>
    <input type="submit" value="Submit photo" class="btn btn-primary">
</form>

Listing 6-36.Django form with file fields, corresponding view method, and template layout

请注意 HTML <form>标签是如何声明所需属性的，另外请注意request.FILES引用是如何用于创建绑定表单的——以及标准的request.POST。清单 6-36 中剩余的表单结构与常规的非文件表单相同(例如，创建未绑定表单，调用is_valid())。

但是类似于常规的 Django 表单处理，一旦表单有效——如果is_valid()返回True——您将希望对表单数据的内容做一些事情；因此在这种情况下，你需要访问request.FILES来处理用户上传的文件。

但是在描述如何处理request.FILES中的文件内容之前，理解request.FILES字典的可能内容是很重要的:

Option 1) request.FILES = {'photo': [<InMemoryUploadedFile>,<TemporaryUploadedFile>], 'video': [<InMemoryUploadedFile>]}
Option 2) request.FILES = {'photo': [<TemporaryUploadedFile>],'video': [<InMemoryUploadedFile>]}

request.FILES字典包含对应于文件字段名的键。在这种情况下，您可以看到photo和video键对应于清单 6-36 中声明的表示文件的表单字段名称。接下来，注意每个键的值都是一个列表，不管文件表单域是否可以接受多个文件——比如photo,因为被覆盖的小部件具有'multiple': True属性——或者在video的情况下接受单个文件。

现在让我们分析分配给每个文件表单字段键的列表内容。每个列表元素代表一个上传的文件。但是请注意这些文件是如何由InMemoryUploadedFile或TemporaryUploadedFile类表示的——这两个类都是django.core.files.uploadedfile.UploadedFile类的子类。上传文件由InMemoryUploadedFile或TemporaryUploadedFile实例类表示的原因取决于上传文件的大小。

事实证明，在您决定如何处理上传的文件之前，Django 必须决定做什么以及将上传的文件放在哪里。为此，Django 依赖于上传处理程序。默认情况下，除非在settings.py,中的FILE_UPLOAD_HANDLERS变量中被显式覆盖，否则 Django 使用以下两个文件上传处理程序:

FILE_UPLOAD_HANDLERS= [
    'django.core.files.uploadhandler.MemoryFileUploadHandler',
    'django.core.files.uploadhandler.TemporaryFileUploadHandler',
]

默认情况下，如果文件小于 2.5 MB，Django 使用MemoryFileUploadHandler将上传文件的内容放入内存；如果文件大于 2.5 MB，Django 使用TemporaryFileUploadHandler将上传文件的内容放在一个临时文件中(例如/tmp/Af534.upload)。

你可以在settings.py中定义FILE_UPLOAD_HANDLERS，只包含你想要的文件上传处理器(例如，如果你想节省内存资源，删除MemoryFileUploadHandler)。但是，请注意，文件上传处理程序必须始终处于活动状态，文件上传才能正常进行。如果您不喜欢 Django 内置文件上传处理程序的行为，那么您需要编写自己的文件上传处理程序。 ⁵

除了在settings.py中定义FILE_UPLOAD_HANDLERS之外，您还可以在settings.py中声明另外两个参数来影响文件上传处理程序的行为。FILE_UPLOAD_MAX_MEMORY_SIZE变量设置文件保存在内存中与作为临时文件处理的阈值大小，默认为2621440字节(或 2.5 MB)。并且FILE_UPLOAD_TEMP_DIR变量设置必须保存临时上传文件的目录，默认为None，意味着使用操作系统的临时文件目录(例如，在 Linux OS 上/tmp/)。

现在您已经知道了 Django 在哪里以及如何存储上传的文件，甚至在您决定如何处理它们之前，让我们看看如何处理request.FILES的内容。清单 6-37 显示了清单 6-36 的延续，其中包含处理上传文件所需的相关代码片段。

# views.py

from django.conf import settings

def save_uploaded_file_to_media_root(f):

    with open('%s%s' % (settings.MEDIA_ROOT,f.name), 'wb+') as destination:

        for chunk in f.chunks():

            destination.write(chunk)

def index(request):
    if request.method == 'POST':
        # POST, generate form with data from the request
        form = SharingForm(request.POST,request.FILES)
        # check if it's valid:
        if form.is_valid():
            for field in request.FILES.keys():

                for formfile in request.FILES.getlist(field):

                    save_uploaded_file_to_media_root(formfile)

            return HttpResponseRedirect('/about/contact/thankyou')
    else:
        # GET, generate blank form
        form = SharingForm()
    return render(request,'social/index.html',{'form':form})

Listing 6-37.Django form file processing with save procedure to MEDIA_ROOT

在 form is_valid()方法之后，您知道request.FILES字典中的每个键都是文件表单字段，因此创建了一个循环来获取每个文件字段(即video、photo)。接下来，使用request.FILES字典的getlist()方法，获得每个文件字段的文件实例列表(即InMemoryUploadedFile,TemporaryUploadedFile),并遍历每个元素以获得文件实例。最后，在每个文件实例上执行save_uploaded_file_to_media_root()方法。

每个文件实例——在清单 6-37 中表示为formfile引用——要么是InMemoryUploadedFile要么是TemporaryUploadedFile实例类型。但是正如我前面提到的，这些类是从父类django.core.files.uploadedfile.UploadedFile派生的，这意味着文件实例也是UploadedFile实例。

按照设计，Django django.core.files.uploadedfile.UploadedFile类有一系列方法和字段，专门用于轻松处理上传文件的内容，其中一些包括:

<file_instance>.name。-输出文件的名称，就像在用户的计算机上一样。

<file_instance>.size。-输出文件的大小，以字节为单位。
<file_instance>.content_type。-输出分配给文件的 HTTP 内容类型头(例如，text/html、application/zip)。
<file_instance>.chunks()。-一种生成器方法，可以高效地输出文件的块内容。

通过使用这些UploadedFile字段和方法，您可以在清单的顶部看到 6-37save_uploaded_file_to_media_root()方法逻辑包括使用其原始名称保存上传的文件——使用 Python 的标准with...open语法——然后使用chunks()方法有效地将上传文件的所有片段写入文件系统。

Note

列表 6-37 中上传的文件保存在设置下。媒体根文件夹。虽然您可以将文件保存到任何想要的位置，但是 Django 中用户上传文件的标准做法是将它们保存在 settings.py 中定义的 MEDIA_ROOT 文件夹下。

Django formsets

因为 Django 表单代表了用户将数据引入 Django 项目的主要方式，所以 Django 表单被用作数据捕获机制并不罕见。然而，这可能导致效率问题，因为每个 web 页面都依赖一个 Django 表单。Django 表单集允许您将多个相同类型的表单集成到一个模板中——带有所有必要的验证和布局工具——通过多个表单简化数据捕获。

好消息是，到目前为止，您对 Django 表单的所有了解——表单字段、验证工作流、模板布局、小部件和所有其他主题——同样适用于 Django 表单集。这意味着表单集的学习曲线相当简单，尽管您必须学习一些新概念。

表单集初始化。尽管表单集被初始化为一组常规的 Django 表单，但是表单集初始化需要特定于表单集的参数。

表单集管理表单。-为了跟踪同一页面上的多个 Django 表单，表单集还使用了一种特殊的表单，称为“管理表单”。

假设您正在向 coffehouse 应用添加在线订购功能。您已经有了一个饮料表单，用户可以订购一种饮料，但是希望添加用户订购多种饮料的功能，因此您需要在同一页面上有多个饮料表单或一个饮料表单集。

清单 6-38 展示了独立的DrinkForm类，生成空表单集的相应视图方法，以及用于显示表单集的模板布局。

# forms.py
from django import forms

DRINKS = ((None,'Please select a drink type'),(1,'Mocha'),(2,'Espresso'),(3,'Latte'))
SIZES = ((None,'Please select a drink size'),('s','Small'),('m','Medium'),('l','Large'))

class DrinkForm(forms.Form):
    name = forms.ChoiceField(choices=DRINKS,initial=0)
    size = forms.ChoiceField(choices=SIZES,initial=0)
    amount = forms.ChoiceField(choices=[(None,'Amount of drinks')]+[(i, i) for i in range(1,10)])

# views.py

from django.forms import formset_factory

def index(request):
    DrinkFormSet = formset_factory(DrinkForm, extra=2, max_num=20)

    if request.method == 'POST':
        # TODO
    else:
        formset = DrinkFormSet(initial=[{'name': 1,'size': 'm','amount':1}])

    return render(request,'online/index.html',{'formset':formset})

# online/index.html
<form method="post">
          {% csrf_token %}
    {{ formset.management_form }}

    <table>
        {% for form in formset %}

        <tr><td><ul class="list-inline">{{ form.as_ul }}</ul></td></tr>
        {% endfor %}

    </table>
    <input type="submit" value="Submit order" class="btn btn-primary">
</form>

Listing 6-38.Django formset factory initialization and template layout

清单 6-38 中的DrinkForm类使用标准的 Django 表单语法，所以没有什么新东西。然而，index视图方法是从使用django.forms.formset_factory方法开始的。formset_factory用于从给定的表单类生成一个FormSet类。在这种情况下，注意formset_factory使用DrinkForm参数——代表表单类——来生成DrinkForm表单集。我将很快提供关于额外的formset_factory参数的细节。

接下来，在清单 6-38 中，您可以看到一个未绑定的Drink FormSet()实例是用一个initial值创建的——类似于如何创建独立的未绑定表单并使用initial参数。然而，注意initial值是一个列表，不像标准表单中使用的独立字典。因为表单集是一组表单，所以表单集的initial值是一组字典，其中每个字典代表每个表单的initial值。在清单 6-38 的情况下，formset 的一个表单被设置为用{'name': 1,'size': 'm','amount':1}值初始化。

在清单 6-38 的底部，你可以看到formset的模板。独立表单模板的第一个区别，是输出管理表单的{{ formset.management_form }}语句。第二个区别是formset参考输出的不同形式。在这种情况下，每个 formset 表单都以完整的形式输出，而{{form.as_ul}}作为内嵌表单，但是您同样可以使用任何 Django 表单模板布局技术以定制的方式输出每个表单实例(例如，删除字段 id 值)。

表单集工厂

清单 6-38 中使用的formset_factory()方法是使用表单集的核心方法之一。尽管清单 6-38 中的例子只使用了三个参数，但是formset_factory()方法可以接受多达九个参数。下面的代码片段说明了formset_factory()方法中每个参数的名称和默认值。

formset_factory(form, formset=BaseFormSet, extra=1, can_order=False, can_delete=False,
                  max_num=None, min_num=None, validate_max=False, validate_min=False)

正如您可以在这个代码片段中确认的那样，formset_factory()方法唯一需要的参数(即没有默认值)是form。每个参数的含义如下:

form。-定义要在其上创建窗体集的窗体类。

formset。-定义表单集基类，默认为django.forms.formsets.BaseFormSet。当您需要自定义窗体集进行自定义窗体集验证时会发生变化。

extra。-定义添加到窗体集中的空窗体的数量。如果一个表单集的表单都是空的(也就是说，它们没有被初始化)，那么一个表单集包含了extra个表单。如果一个窗体集的窗体包含数据(即它们被初始化)，一个窗体集包含初始化窗体的数量+ extra(空窗体)。

can_order。-将 ORDER 字段(作为一个forms.IntegerField)添加到表单集中的每个表单，目的是改变表单集中的表单顺序。默认为False。

can_delete。-向表单集中的每个表单添加删除字段(作为一个forms.BooleanField)，目的是将表单集中的一个表单标记为删除。默认为False。

max_num。-定义要在窗体集中显示的最大窗体数。默认为None，表示最多显示 1000 个表单实例。

min_num。-定义要在窗体集中显示的最小窗体数。默认为None，表示至少显示 0 个表单实例。

validate_max。-与max_num一起使用，以确保验证得到执行，并且表单实例不会超过max_num。默认为False。

validate_min。-与min_num一起使用，以确保实施验证，并且表单实例永远不会少于min_num。默认为False。

现在你已经知道了各种formset_factory()方法选项，让我们把注意力转回到清单 6-38 中使用的方法:

formset_factory(DrinkForm, extra=2, max_num=20)

这个formset_factory方法用DrinkForm类创建一个表单集；extra=2表示总是包含 2 个空的DrinkForm实例；这意味着，因为表单集是用清单 6-38 中的一个DrinkForm实例初始化的，所以表单集中的表单总数将是 1，加上两个空表单，因为extra=2;``max_num=20参数表明表单集应该包含最多 20 个DrinkForm实例。

表单集管理表单和表单集处理

要理解表单集的管理表单的目的，最简单的方法是查看该表单包含的内容。清单 6-39 基于清单 6-38 中的例子展示了表单集管理表单的内容。

<input type="hidden" name="form-TOTAL_FORMS" value="3" id="id_form-TOTAL_FORMS" />
<input type="hidden" name="form-INITIAL_FORMS" value="1" id="id_form-INITIAL_FORMS" />
<input type="hidden" name="form-MIN_NUM_FORMS" value="0" id="id_form-MIN_NUM_FORMS" />
<input type="hidden" name="form-MAX_NUM_FORMS" value="20" id="id_form-MAX_NUM_FORMS" />
Listing 6-39.Django formset management form contents and fields

正如您在清单 6-39 中看到的，表单集管理表单的内容(即清单 6-38 中的{{formset.management_form}}语句)是四个隐藏的输入变量。form-TOTAL_FORMS字段表示表单集中的表单总数；form-INITIAL_FORMS字段表示表单集中已初始化表单的总数；form-MIN_NUM_FORMS字段表示表格集中表格的最小数量；而form-MAX_NUM_FORMS字段表示表单集中表单的最大数量。

乍一看，清单 6-39 中的变量似乎并不重要，但是一旦表单集中的各种表单进入处理和呈现阶段，它们就在表单集中扮演了重要的角色。为了更好地说明这些表单集管理字段的相关性，让我们修改清单 6-38 中的表单集，以允许用户添加更多的饮料表单，这样他们就可以根据需要增加订单。

#views.py
def index(request):
    extra_forms = 2
    DrinkFormSet = formset_factory(DrinkForm, extra=extra_forms, max_num=20)
    if request.method == 'POST':
        if 'additems' in request.POST and request.POST['additems'] == 'true':

            formset_dictionary_copy = request.POST.copy()

            formset_dictionary_copy['form-TOTAL_FORMS'] = int(formset_dictionary_copy['form-TOTAL_FORMS']) + extra_forms

            formset = DrinkFormSet(formset_dictionary_copy)

        else:

            formset = DrinkFormSet(request.POST)

            if formset.is_valid():

                return HttpResponseRedirect('/about/contact/thankyou')

    else:
        formset = DrinkFormSet(initial=[{'name': 1,'size': 'm','amount':1}])
    return render(request,'online/index.html',{'formset':formset})

# online/index.html
<form method="post">
          {% csrf_token %}
    {{ formset.management_form }}
    <table>
        {% for form in formset %}
        <tr><td>{{ form }}</td></tr>
        {% endfor %}
    </table>
    <input type="hidden" value="false" name="additems" id="additems">

    <button class="btn btn-primary" id="additemsbutton">Add items to order</button>

    <input type="submit" value="Submit order" class="btn btn-primary">
</form>

<script>

$(document).ready(function() {

        $("#additemsbutton").on('click',function(event) {

         $("#additems").val("true");

       });

});

</script>

Listing 6-40.Django formset designed to add extra forms by user

清单 6-40 中的第一个重要修改来自表单集模板。请注意，表单声明了一个名为additems的隐藏输入字段，设置为false，以及一个按钮，单击该按钮会将隐藏输入字段的值更改为true。这种机制是一个简单的控制变量，用于跟踪用户何时想要向订单添加更多的项目(例如，向表单集添加更多的饮料表单)。

现在让我们转向清单 6-40 中处理表单集的视图方法。首先，注意表单集使用设置为 2 的extra_forms变量来定义表单集的extra值，所以初始表单集工厂包含两个额外的表单，就像清单 6-38 中一样。

接下来是request.POST处理表单集部分，它有两种可能的结果。如果request.POST包含了additems字段，并且它被设置为true，这表明用户点击了按钮，向表单集中添加了更多的表单。如果request.POST不包含additems字段或者它被设置为 false，则表明用户点击了标准的提交按钮，因此创建了一个绑定的表单集，并在表单集上调用了is_valid()。现在，让我们来分析一下每种可能结果背后的逻辑。

当用户向表单集中添加更多表单时，会生成一个request.POST的副本——因为request.POST是不可变的，所以copy()方法是必需的。接下来，通过添加extra_forms变量，修改表单集的管理表单字段form-TOTAL_FORMS以反映附加的表单。最后，DrinkFormSet用这个新修改的request.POST字典重新绑定——用一个改变的form-TOTAL_FORMS。当重新绑定的表单集被发送回用户时，由于简单地修改了form-TOTAL_FORMS管理表单集字段，该表单集现在将包含两个额外的空表单。

如果表单集属于清单 6-40 中的标准后处理和验证部分，会发生以下情况。首先，使用request.POST创建一个绑定表单集——就像使用常规绑定表单一样——接下来，在表单集上调用is_valid()方法——也像在常规绑定表单中一样。如果is_valid()返回 true(即表单集或单个表单中没有错误)，则重定向到成功页面。如果is_valid()返回 false(即在表单集或单个表单中有错误),一个errors字典被附加到表单集引用，控制落到最后一行—return render(request,'online/index.html',{'formset':formset})—它发送带有错误的formset实例以显示在模板上——这个过程也几乎与标准表单验证和错误管理相同。

正如您所看到的，通过对 Django 表单集的管理表单中的一个字段进行微小的修改，就可以动态地改变表单集中的表单数量。注意，在大多数情况下，没有必要直接操作表单集的管理表单字段，Django 更多时候在幕后使用这些值来跟踪处理和呈现任务。尽管一旦您创建了更高级的表单集行为(例如，订购表单、删除表单)，剩余的管理表单集字段承担了同样重要的角色，可能需要直接操作。

表单集自定义验证和表单集错误

表单集中的所有表单都根据上一节中解释的表单验证规则进行验证(例如，validators、clean_<field>()方法)。然而，有时有必要在一个表单集中实施表单间规则，在这种情况下，你需要构建一个自定义的表单集类，如清单 6-41 所示。

from django.forms import BaseFormSet

class BaseDrinkFormSet(BaseFormSet):
    def clean(self):
        # Check errors dictionary first, if there are any error, no point in validating further
        if any(self.errors):
            return
        name_size_tuples = []
        for form in self.forms:
            name_size = (form.cleaned_data['name'],form.cleaned_data['size'])
            if name_size in name_size_tuples:
                raise forms.ValidationError("Ups! You have multiple %s %s items in your order, keep one and increase the amount" % (dict(SIZES)[name_size[1]],dict(DRINKS)[int(name_size[0])]))
            name_size_tuples.append(name_size)

Listing 6-41.Django custom formset with custom validation

首先，注意清单 6-41 中的类继承了django.forms.BaseFormSet类的行为，赋予它 Django 表单集的所有基本功能。接下来，自定义 formset 类定义了一个clean()方法，该方法与标准 Django 表单中的clean()方法具有相同的用途:在整体(即 formset)而不是单个部分(即表单)上实施验证规则。clean()方法中的验证逻辑强制规定，如果表单集中的两个表单具有相同的name和size，则会引发错误。

请注意清单 6-41 中验证错误创建也使用了标准表单中使用的相同的forms.ValidationError()类。如果clean()方法引发了一个验证错误，这个错误将被分配给一个特殊的字段，这个字段在表单集的errors字典中被称为non_form_errors。清单 6-42 显示了清单 6-38 中表单集模板的更新版本，说明了如何消除表单集的非表单错误。

<form method="post">
          {% csrf_token %}
    {{ formset.management_form }}
    {% if formset.non_form_errors %}

      <div class="alert alertdanger">{{formset.non_form_errors}}</div>

    {% endif %}

     {{ formset.management_form }}
    <table>
        {% for form in formset %}
        <tr><td><ul class="list-inline">{{ form.as_ul }}</ul></td></tr>
        {% endfor %}
    </table>
</form>
Listing 6-42.Django custom formset to display non_form_errors

您可以在清单 6-42 中的{{formset.management_form}}语句下面看到一个条件循环，它输出放置在表单集的errors字典的non_forms_errors键中的任何错误。虽然名称不同，但formset.non_form_errors的目的与常规 Django 表单的form.non_field_errors相同，显示与特定零件无关的错误。因为表单集使用表单构造，所以错误变量称为non_forms_errors，因为表单使用字段构造，所以变量称为non_field_errors。

请注意，如果表单集的表单中出现任何错误，它们会像在常规表单中一样被放置在表单的error字典中，因此您可以使用清单 6-28 中概述的技术来自定义表单集中各个表单错误的输出。

Django Form Tools and Django Crispy Forms

除了你在本章中学到的 Django 内置表单功能，还有几个第三方 Django 应用值得一提，它们旨在解决更高级的 Django 表单问题。

Django 表单工具包 ⁶ 支持表单审核流程和表单向导的创建。在 Django 表单的数据被验证之后，表单检查过程会强制进行预览，当您希望最终用户在表单生命周期结束之前仔细检查他们的表单数据(例如，预订或采购订单)时，这个过程非常有用。表单向导由不同页面中的分组表单组成，作为序列的一部分(例如，注册或调查问卷)。Django 表单工具包的好处是，它实现了支持这些类型的 Django 表单工作流所需的所有“低级”逻辑。

Django crisp forms⁷是另一款专注于高级表单布局的第三方 Django 应用。Django crispy forms 是 Django 表单与 Bootstrap 库集成以及需要复杂小部件和模板布局的表单(例如，内联和水平表单)的流行选择。

Footnotes 1

https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods

https://docs.djangoproject.com/en/1.11/ref/validators/#built-in-validators

https://en.wikipedia.org/wiki/Responsive_web_design

https://docs.djangoproject.com/en/1.11/ref/forms/widgets/#built-in-widgets

https://docs.djangoproject.com/en/1.11/ref/files/uploads/#custom-upload-handlers

https://django-formtools.readthedocs.io/

http://django-crispy-forms.readthedocs.io/

七、Django 模型

Django 应用与数据交互的典型方式是通过 Django 模型。Django 模型是一个面向对象的 Python 类，表示实体的特征。例如，一个实体可以是一个人、一个公司、一个产品或应用使用的一些其他概念。

因为数据是现代应用的中心，Django 框架执行 DRY(不要重复自己)原则，Django 模型经常充当 Django 项目的构建模块。一旦您有了一组代表应用实体的 Django 模型，Django 模型也可以作为简化创建其他操作数据的 Django 结构(例如表单、基于类的视图、REST 服务、Django 管理页面)的基础，因此 Django 模型在整体上非常重要。

在这一章中，您将了解 Django 模型的核心行为，包括如何创建模型和如何使用迁移，这是有效使用模型的核心。接下来，您将了解 Django 模型的默认行为，以及如何用自定义行为覆盖它们。此外，您将了解创建 Django 模型可用的不同数据类型，Django 模型可用的不同关系，以及如何使用 Django 模型管理数据库事务。

接下来，您将了解有关迁移文件的更多信息，包括创建迁移文件的各种方法、如何重命名迁移文件、如何将多个迁移文件压缩成一个迁移文件、每个迁移文件元素背后的含义以便您可以放心地编辑迁移文件，以及回滚迁移文件的过程。

此外，您将了解各种 Django 工具，这些工具旨在简化 Django 模型和数据库之间的工作，例如用 fixture 文件备份和加载模型数据，包括如何将初始数据加载到 Django 模型中。接下来，您将了解 Django 模型中支持软件观察者模式的 Django 信号。最后，您将学习如何在默认位置之外声明 Django 模型，以及如何配置多个数据库并在 Django 模型中使用它们。

本章假设您已经为 Django 项目建立了一个数据库。如果您还没有建立数据库，请参见第一章为 Django 项目建立数据库。

Django 模型和迁移工作流

Django 的主要存储技术是关系型的(即开箱即可连接到 SQLite、Postgres、MySQL 或 Oracle)，因此 Django 模型被设计为直接映射到关系数据库表。这意味着 Django 模型的实例被存储为以模型命名的关系表的行。

例如，对于名为Store的 Django 模型类，默认情况下，Django 对名为<app_name>_store的数据库表执行数据库 CRUD(创建、读取、更新和删除)操作，其中模型的每个Store实例表示数据库行，模型的字段(例如，name、address、city、state)映射到数据库表列。

因为 Django 模型围绕着数据，所以它们很容易改变。例如，由于业务需求，一个名为Store的 Django 模型可能突然需要修改其原始字段(例如，添加一个新字段，如email，或者删除一个不再需要的字段，如telephone)。维护这些 Django 模型的变化也是 Django 模型的一个重要方面，并通过使用迁移文件来管理。

创建 Django 模型

Django 模型存储在 Django 应用中的models.py文件中。一旦创建了 Django 应用，一个空的models.py文件就会被添加到应用中以供将来使用。如果你不熟悉 Django app 这个术语，请参阅章节 1 中关于设置内容的部分。清单 7-1 展示了一个 Django 模型定义的例子。

Tip

记住这本书的代码在 https://github.com/drubio/beginningdjango ，如果你觉得用一个预先输入的结构化的应用更容易理解的话。

from __future__ import unicode_literals
from django.utils.encoding import python_2_unicode_compatible

from django.db import models

@python_2_unicode_compatible
class Store(models.Model):
    #id = models.AutoField(primary_key=True)# Added by default, not required explicitly
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    #objects = models.Manager()# Added by default, to required explicitly
    def __str__(self):
        return "%s (%s,%s)" % (self.name, self.city, self.state)

Listing 7-1.Django model class definition in models.py

清单 7-1 中的前两行导入了使用 Python 2 和 Python 3 在 Django 中运行 Python 类所需的功能。如果您的 Django 项目只是在 Python 3 上运行，那么您可以省略这些 import 语句。清单 7-1 中的第三行导入了django.db.models包，这是在类定义中访问 Django 模型功能所必需的。接下来，您可以看到 class Store(models.Model)语句。在 Python 2 上运行这个类需要@python_2_unicode_compatible注释，但是如果你只是使用 Python 3，你可以省略这个注释。

在清单 7-1 中的主类定义之后，您可以看到四个数据类型为models.CharField的字段，它们将这些字段限定为字符串。进一步限制每个字段的可接受值的是models.CharField的max_length参数(例如，max_length=30表示字符字段的最大长度为 30 个字符)。

目前，不要担心models.CharField字段的定义。Django 的models包支持许多其他数据类型和参数，我将在下一节关于 Django 模型数据类型中描述所有这些选项。

此外，注意清单 7-1 中的 Django 模型有id和objects字段。在这种情况下，我用#将它们注释掉，因为你不需要显式声明它们；两者都被自动添加到所有 Django 模型中，但是我把它们放在那里，这样你就知道它们的存在了。

id字段是 Django AutoField数据类型，它在后台创建一个自动递增的整数表列。例如，当您创建第一个Store记录时，数据库将id字段设置为 1，对于第二个Store记录，数据库将id字段设置为 2，依此类推。id字段的目的是使记录搜索更容易、更有效。因为id代表一个唯一的数字来标识一个记录，所以它被用作一个引用，也用作一个数据库表的主键和一个加速记录访问的索引。虽然您可以覆盖这个默认的id字段的各种行为(例如，更改字段名)，但是我将把这方面的细节留到后面的部分。

objects字段是 Django 模型的默认模型管理器，负责管理与 Django 模型相关的所有查询操作。本章和下一章的后续章节将描述 Django 模型管理器的使用。

Tip

如果你想了解更多关于所有 Django 模型默认添加的 id 字段，表 7-1 描述了 AutoField 数据类型，这是 id 字段的基础；本章后面的“Django 模型数据类型”一节描述了 id 字段使用的 primary_key 属性的用途；本章后面的“模型方法”一节中描述的 save()方法描述了 id 字段的实际应用。

最后，在清单 7-1 中，你可以看到__str__的类方法定义，这是一个标准的 Python 方法——被称为‘魔法方法’的一部分——在试图查看或打印 Django 模型的实例时很有帮助。__str__方法定义了一个类实例的人类可读表示(例如，基于清单 7-1 的Store模型实例通过其name、city和state字段值输出)。

Django 模型定义即使放在应用的models.py文件中，也仍然不能被 Django 发现。为了让 Django 发现models.py文件中的模型定义，有必要将应用声明为settings.py中INSTALLED_APPS变量的一部分。清单 7-2 展示了在coffeehouse.stores应用中发现 Django 模型的INSTALLED_APPS定义。

INSTALLED_APPS = (
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'coffeehouse.stores',

)
Listing 7-2.Add app to INSTALLED_APPS in Django settings.py to detect models.py definitions

正如你在清单 7-2 中看到的，除了在INSTALLED_APPS中声明的默认应用之外，在最后还添加了coffeehouse.stores应用。这告诉 Django 检查coffeehouse.stores应用中的models.py文件，以考虑其中的任何 Django 模型定义。

在前面的步骤之后，models.py中的一个应用的 Django 模型定义就可以使用了。在下一节中，我将描述 Django 模型迁移以及与models.py文件中的模型相关联的工作流。

迁移和 Django 模型工作流

让我们从 Django models 工作流如何在混合迁移的情况下运行的例子开始。图 7-1 显示了带有迁移的 Django 模型工作流。

图 7-1。

Django workflow for models with migrations

如图 7-1 的左上方所示，当您在models.py文件上添加或修改 Django 模型时，工作流开始。一旦您认为对一个models.py文件所做的更改相当大，或者希望它们反映在数据库中，您需要创建一个迁移文件。无论您是添加、删除还是修改models.py文件中的内容，迁移文件都会提供对models.py文件所做更改的逐步快照。

为了创建迁移文件，使用makemigrations管理命令。当您运行这个命令时，Django 会扫描所有在INSTALLED_APPS中声明的 Django 应用的models.py文件，如果 Django 检测到对models.py文件的更改，它会为应用创建一个新的迁移文件。这个过程的功能就像一个版本控制系统，其中迁移文件反映了从以前的迁移文件对models.py所做的更改，整个系列的迁移文件讲述了一个应用的models.py文件的整个演变。

如图 7-1 所示，迁移文件存储在应用内的/migrations/子目录中，与它们跟踪的models.py文件放在一起。默认情况下，迁移文件使用命名约定<number_shortdescription>，因此很容易跟踪它们被创建的顺序以及它们包含的内容。

接下来，让我们在上一节中创建的 Django 模型上运行makemigrations。清单 7-3 演示了这个序列，并添加了stores参数来限制对stores应用的迁移过程——如果您不带任何参数运行makemigrations, Django 会检查settings.py中INSTALLED_APPS变量中定义的每个应用的models.py。

[user@coffeehouse ∼]$ python manage.py makemigrations stores
Migrations for 'stores':
  0001_initial.py:
    - Create model Store
Listing 7-3.Django makemigrations command

to create migration file for changes made to models.py

运行清单 7-3 中的makemigrations stores后，可以看到迁移文件0001_initial.py。给这个文件起这个名字是因为它是第一次从空的models.py中迁移出来。未来对models.py的修改会生成名为0002.、0003...的迁移文件

将我们的注意力转回图 7-1 中的工作流，迁移文件本身只是 Django 模型工作流的第一步。接下来，您可以预览或应用这些迁移文件，以便模型成为数据库的一部分。

要在将迁移应用到数据库之前预览实际的 SQL 语句，可以运行sqlmigrate <app_name> <migration_name>命令。清单 7-4 展示了最后一步中迁移文件的sqlmigrate序列。

[user@coffeehouse ∼]$ python manage.py sqlmigrate stores 0001
BEGIN;
CREATE TABLE "stores_store" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "name" varchar(30) NOT NULL, "address" varchar(30) NOT NULL, "city" varchar(30) NOT NULL, "state" varchar(2) NOT NULL);

COMMIT;

Listing 7-4.Django sqlmigrate command

to preview SQL generated by migration file

正如您在清单 7-4 中看到的，stores应用的迁移文件0001_initial.py被设置为运行一条 SQL 语句，该语句创建一个名为stores_store的数据库表，其字段名对应于清单 7-1 中的 Django 模型。

Tip

您可以使用 db_table 元类选项更改 Django 模型的默认数据库表名；“模型元类”一节详细描述了这一点。

在这个阶段，预览迁移文件生成的 SQL 语句可能看起来不太令人兴奋，但在其他情况下，它会非常有帮助。例如，如果您对 Django 模型进行了复杂的更改，或者您的数据库相对较大，那么在将迁移文件直接应用到数据库之前预览 SQL 是有益的。

最后，Django 模型工作流的最后一步是使用 migrate 命令将迁移文件应用到数据库。清单 7-5 演示了这个序列，并添加了stores参数来限制 stores 应用的进程——如果您不带任何参数运行migrate, Django 会处理项目中每个应用的迁移文件。

[user@coffeehouse ∼]$ python manage.py migrate stores
Operations to perform:
  Apply all migrations: stores
Running migrations:
  Applying stores.0001_initial... OK
Listing 7-5.Django migrate command

to execute migration files on database

在清单 7-5 中，stores.0001_initial迁移是针对数据库运行的。这意味着清单 7-4 中的 SQL 是针对数据库执行的。

Caution

小心不要通过 Django 迁移来直接操作数据库，因为这会导致不一致和错误。

Tip

如果不希望 Django 模型使用迁移，可以使用托管元类选项；请参阅“Django 元类”一节了解详细信息。

为了跟踪应用的迁移，在图 7-1 的左下方，您可以看到showmigrations管理命令的使用。showmigrations命令输出一个项目迁移列表，在那些已经应用到数据库的迁移文件旁边有一个 X。值得一提的是，showmigrations命令通过检查migration文件夹中的迁移文件和跟踪应用迁移的django_migrations数据库表来获取数据。

Django 模型数据类型

数据需要符合特定的规则才能在任何应用中有用。如果不是因为规则，那么您可能很容易以邮政编码数字结束，而您期望的是地址信息或大量文本，而您期望的是最多 10 个字符的输入。Django 模型可以使用几种数据类型来强制模型数据符合某些规则(例如，文本、数字、电子邮件)。

理解 Django 模型数据类型在两个层上操作很重要:数据库层和 Django/Python 层。当您使用 Django 模型的数据类型定义 Django 模型并创建其初始迁移时，Django 会生成并执行模型的 DDL(数据定义语言)来创建数据库表，该 DDL 包含反映 Django 模型字段的规则(例如，Django IntegerField模型字段会被转换为INTEGER DB 列以强制执行整数值)。这意味着，如果您更改这种 Django 模型字段(例如，将一个整数字段更改为一个文本字段)，它需要生成一个新的迁移，以便数据库表也能反映任何新的规则。

除了一开始由 Django 模型在数据库层创建的规则实施之外，Django 模型字段还在 Django/Python 层实施数据规则(即，在数据库中插入/更新数据之前)。例如，Django 模型的字段参数像choices强制字段的值符合一组选择；当您试图创建、保存或更新 Django 模型记录时，会强制执行这种类型的规则，并且不管数据库表规则如何。这意味着您可以简单地更改与这种类型的规则相关联的 Django 模型字段，而不必创建新的迁移来更改底层数据库表——在这种情况下，更改 Python 代码就足以更改验证行为。

对于 Django 模型字段数据类型，请始终牢记这一点:一些 Django 模型更改需要创建一个迁移，而其他更改只需更改 Django 模型字段代码即可生效。表 7-1 展示了各种 Django 模型字段以及它们为 Django 支持的所有四个主要关系数据库生成的 DDL:SQLite、MySQL、PostgreSQL 和 Oracle。

表 7-1。

Django model data types and generated DDL by database

| 数据类型 | Django 模型类型 | 数据库 DDL | 描述-验证-注释 | | --- | --- | --- | --- | | | | 数据库 | 关系型数据库 | 一种数据库系统 | 神谕 | | | --- | --- | --- | --- | --- | --- | --- | | 二进制的 | 模特。二进制字段() | BLOB NOT NULL | 长 blob 非 NULL | 字节不为空 | BLOB NULL | 创建 blob 字段来存储二进制数据(例如，图像、音频或其他多媒体对象)。 | | 布尔代数学体系的 | 模特。布尔字段() | 布尔值不为空 | 布尔值不为空 | 布尔值不为空 | NUMBER(1)NOT NULL CHECK(" VAR " IN(0，1)) | 创建一个布尔型字段来存储真/假(或 0/1)值。 | | 布尔代数学体系的 | 模特。NullBooleanField() | 布尔空 | 布尔空 | 布尔值空值 | 数字(1)空检查(((0，1)中的“VAR”)或(“VAR”为空)) | 与 BooleanField 类似，但也允许空值。 | | 日期/时间 | 模特。日期字段() | 日期不为空 | 日期不为空 | 日期不为空 | 日期不为空 | 创建日期字段来存储日期。 | | 日期/时间 | 模特。时间字段() | 时间不为空 | 时间不为空 | 时间不为空 | 时间戳不为空 | 创建时间字段来存储时间。 | | 日期/时间 | 模特。日期时间字段() | 日期时间不为空 | 日期时间不为空 | 时区不为空的时间戳 | 时间戳不为空 | 创建日期时间字段来存储日期和时间。 | | 日期/时间 | 模特。DurationField() | bigint NOT NULL | bigint NOT NULL | 间隔不为空 | 第(9)天到第(6)天的间隔不为空 | 创建一个字段来存储时间段。 | | 数字 | 模特。自动字段() | 整数非空自动增量 | 整数 AUTO_INCREMENT 不为空 | 序列不为空 | NUMBER(11) NOT NULL &也创建一个序列和触发器来增加字段 | 创建一个自动递增的整数，主要用于自定义主键。 | | 数字 | 模特们。bigintegerfield() | bigint NOT NULL | bigint NOT NULL | bigint NOT NULL | 数字(19)不为空 | 创建一个大整数来适应-9223372036854775808 到 9223372036854775807 之间的数字。该范围可能因 DB 品牌而异。 | | 数字 | 模特。DecimalField( decimal_places=X，max_digits=Y) | 小数不为空 | 数值(X，Y)不为空 | 数值(X，Y)不为空 | 数字(10，3)不为空 | 强制一个最多有 X 位数字和 Y 位小数点的数字。创建一个十进制字段来存储十进制数。注意 X 和 Y 参数都是必需的，其中 X 参数表示要存储的最大位数，Y 参数表示要存储的小数位数。 | | 数字 | 模特。浮动字段() | 实数不为空 | 双精度不为空 | 双精度不为空 | 双精度不为空 | 创建存储浮点数的列。 | | 数字 | 模特。IntegerField() | 整数不为空 | 整数不为空 | 整数不为空 | 数字(11)不为空 | 创建存储整数的列。 | | 数字 | 模特。PositiveIntegerField() | 无符号整数不为空 | 无符号整数不为空 | 整数非空检查(" VAR" >= 0) | NUMBER(11)非空校验(" VAR" >= 0) | 强制使用 0 到 2147483647 之间的值。与 IntegerField 类似，但将值限制为正数。 | | 数字 | 模特。PositiveSmallIntegerField() | smallint unsigned NOT NULL | smallint UNSIGNED NOT NULL | smallint NOT NULL CHECK （"VAR" >= 0） | NUMBER(11)非空校验(" VAR" >= 0) | 强制使用 0 到 32767 之间的值。与整数域和特殊的正整数域类似，但将数字限制在较小的正范围内。 | | 数字 | 选项。SmallIntegerField() | smallint not null | smallint not null | smallint not null | 数字(11)不为空 | 强制数字在-32768 到 32767 的范围内。工作方式与 IntegerField 类似，但整数范围更小。 | | 文本 | 模特。CharField( max_length=N) | varchar(N)不为空 | varchar(50)不为空 | varchar(50)不为空 | NVARCHAR2(50)空 | 创建一个文本列，其中 max_length 参数是指定最大字符长度所必需的。 | | 文本 | 模特。文本字段() | 文本不为空 | longtext NOT NULL | 文本不为空 | NCLOB NULL | 创建一个文本字段来存储文本。 | | 文本(专业) | 模特。CommaSeparatedIntegerField(max _ length = 50) | varchar(N)不为空 | varchar(N)不为空 | varchar(N)不为空 | NVARCHAR2(N) NULL | 强制字符串为 CSV 格式的整数。工作方式与 CharField 类似，只是 Django 在与数据库交互之前强制字符串为逗号分隔的整数值(例如，3，54，54，664，65)。 | | 文本(专业) | 模特。电子邮件字段() | varchar(254)不为空 | varchar(254)不为空 | varchar(254)不为空 | NVARCHAR2(254)空 | 使用内部 Django EmailValidator 强制文本是有效的电子邮件，以确定什么是有效的，什么不是。工作方式与 CharField 一样，默认 max_length 为 254 个字符，并且强制该字符串是有效的电子邮件。 | | 文本(专业) | 模特。文件字段() | varchar(100)不为空 | varchar(100)不为空 | varchar(100)不为空 | NVARCHAR2(100)空 | 实施并提供各种实用程序来处理文件(例如，打开/关闭文件、上传位置等)。).工作原理与 CharField 一样，默认 max_length 为 100 个字符，并强制该字符串是有效文件。 | | 文本(专业) | 模特。文件路径字段() | varchar(100)不为空 | varchar(100)不为空 | varchar(100)不为空 | NVARCHAR2(100)空 | 强制执行并提供各种实用程序来限制某些文件系统目录中的文件名选择。工作方式与 CharField 一样，默认 max_length 为 100 个字符，并强制该字符串是文件系统目录中的有效文件。 | | 文本(专业) | 模特。图像字段() | varchar(100)不为空 | varchar(100)不为空 | varchar(100)不为空 | NVARCHAR2(100)空 | 执行并提供各种实用程序来处理图像文件(例如，获取高度和宽度)。工作方式与 CharField 和专用 FileField 类似，默认 max_length 为 100 个字符，并强制字符串为有效图像。注意该字段需要 Pillow Python 库的存在(例如 pip install Pillow)。 | | 文本(专业) | 模特。GenericIPAddressField() | char(39)不为空 | char(39)不为空 | inet 不为空 | VARCHAR2(39) NULL | 强制执行并提供各种实用程序，仅接受有效的 IPv4 或 IPv6 地址(例如，198.10.22.64 和 FE80::0202:B3FF。:FE1E:8329，以及 unpack_ipv4 和 protocol 之类的实用程序)。工作原理与 CharField 一样，默认 max_length 为 39 个字符，并强制该字符串是有效的 IP 地址。 | | 文本(专业) | 模特。斯拉格菲尔德() | varchar(50)不为空 | varchar(50)不为空 | varchar(50)不为空 | NVARCHAR2(50)空 | 强制字符串为辅助字符串，即仅包含字母、数字、下划线或连字符的字符串。就像 CharField 默认为 50 个字符的 max_length 一样工作，并确保提供的字符串是一个 slug——这个概念通常用于清理包含空格和其他潜在无效字符(如带重音符号的字母)的 URL 字符串。 | | 文本(专业) | 模特。URLField() | varchar(200)不为空 | varchar(200)不为空 | varchar(200)不为空 | NVARCHAR2(200)空 | 强制提供的文本值是有效的 URL。工作原理与 CharField 一样，默认的 max_length 为 200 个字符，并强制该字符串是有效的 URL。 | | 文本(专业) | 模特。UUIDField() | char(32)不为空 | char(32)不为空 | uuid NOT NULL | VARCHAR2(32)不为空 | 强制提供的文本是一个通用唯一标识符(UUID ),就像 CharField 一样，默认的 max_length 为 32 个字符，并强制该值是一个 UUID。 |

Oracle Not Null Considered Harmful

如果您仔细查看表 7-1 中为不同 Django 模型字段生成的一些 DDL(例如，模型。CharField()，模型。FileField())，您会注意到 Oracle 使用 NULL 约束生成 DB 列，而其他三个数据库品牌使用 NOT NULL 约束生成 DB 列；这既不是一个打字错误，也不是一个错误，这是由于 Oracle 的工作方式而设计的。

尽管 Oracle 像其他数据库品牌一样支持 NOT NULL 约束，但 Oracle 也带来了副作用，即它也将空字符串“”视为非 NULL 值。这意味着，如果 Django 试图在 Oracle 数据库中存储一个空字符串' '(例如，在 CharField()或 FieldField()上)，如果存在 NOT NULL 约束，该操作将被拒绝——即使有 NOT NULL 约束，该操作在其他数据库中也完全有效。因此，为了保持跨数据库的一致性并避免这种 Oracle 特有的边缘情况，Django 选择在某些场景中不使用 NOT NULL 约束。

注意这是一个众所周知的 Oracle“特性”或“怪癖”——取决于您的观点——多年来一直为人所知:如何在不可空的列中插入空字符串(零长度)？答:不能。Oracle 在其文档中陈述了这一事实，并提到这一行为可能会在未来发生变化以符合标准(ANSI)，但在最新版本的 Oracle 12c 中，这一行为保持不变。在下一节中，我将提供一些与处理 NULL、NOT NULL 和空 string ' '问题相关的特定于 Django 的细节。

正如您在表 7-1 中看到的，Django 模型字段根据数据库品牌产生稍微不同的 DDL，尽管所有后端映射的最终行为都尽可能彼此接近，Django/Python 规则强制填补了空白。

例如，对于像models.DurationField()这样的 Django 模型字段，SQLite 和 MySQL 使用bigint数据类型，而 PostgreSQL 和 Oracle 使用更专业的interval数据类型。类似地，对于 Django 模型字段，如models.CommaSeparatedIntegerField()和models.EmailField()，在数据库级别，它们被表示为基本字符varchar数据类型——或者在 Oracle 中被表示为NVARCHAR2——是 Django/Python 强制文本表示分别是有效的 CSV 格式的整数或电子邮件。

了解了每个 Django 模型字段生成的初始 DDL 之后，在接下来的部分中，我将介绍各种 Django 模型字段选项以及它们与初始 DDL 和 Django/Python 验证相关的行为。

极限值:最大长度、最小值、最大值、最大位数和小数位数

将值限制在某个范围内是 Django 模型字段中最基本的选项之一。对于基于文本的数据类型，max_length选项强制值不超过一定数量的字符。在表 7-1 中，你可以看到CharField数据类型需要你指定max_length选项，对于更专业的基于文本的数据类型(例如EmailField)，Django 会分配一个默认的max_length选项值，你可以用一个显式的max_length值覆盖它。

对于使用IntegerField数据类型的字段，Django 提供了min_value和max_value选项来限制值的下限/上限(例如，IntegerField(min_value=0,max_value=1000)将值限制在 0 到 1000 的范围内)。类似地，对于数据类型为DecimalField的字段，Django 要求您指定max_digits和decimal_places选项来分别强制一个值的最大位数和小数点位数。

空值、Null 值和非 Null 值:空白值和 Null 值

默认情况下，所有 Django 模型字段都在数据库级别被赋予了一个NOT NULL限制；如果您再次查看表 7-1 ，您可以通过生成的 DDL 确认这一点——唯一的例外是 Oracle 数据库上的某些字段，这在表 7-1 下面的侧栏中有解释。

这意味着当您创建/更新一个带有NOT NUL L 字段的记录时，必须为该字段提供一个值，否则数据库会拒绝该操作。但是在某些情况下，可能有必要允许空字段值或数据库中的NULL值。为了允许 Django 模型字段在数据库级别支持NULL值，您必须声明null=True字段选项(例如，IntegerField(null=True)允许一个整数字段为空，并使用NULL而不是默认的NOT NULL生成 DDL)。

除了在数据库级执行的默认为null=False的null选项，Django 还支持blank选项。blank选项在所有字段上也默认为blank=False,用于通过在 Django 模型上工作的表单来执行 Django/Python 验证(例如，通过 Django 管理中的表单或自定义 Django 表单来创建 Django 模型记录)。如果 Django 模型字段用blank=True声明，Django 允许该字段在表单中留空，否则(即，如果blank=True没有在模型字段中显式声明), Django 拒绝该表单并强制最终用户为该字段提供一个值。

由于null和blank选项的使用可能是 Django 模型字段选项中最令人困惑的主题之一，表 7-2 展示了一个具有不同模型定义和操作的矩阵，以更好地说明这种行为。

表 7-2。

Django model validation for blank and null field options

| 模型定义类 Person(模型。型号):名字=型号。CharField(max _ length = 30)middle _ name = models。CharField(max _ length = 30)last _ name = models。CharField(max_length=30) | | --- | | 空白和空字段组合 | Default(空白=假，null =假)middle_name =模型。CharField(max_ length=30) | null=True(默认值为 blank=False) middle_ name = models。CharField (max_length=30，null= True) | blank=True(默认值为 null=True) middle_name= models。CharField (max_length=30，blank=True) | null=True，空白=True 模型。CharField( max_length=30，null= True，blank=True) | | Person.objects.create(名字='Johann '，中间名=None，姓氏='Bach ') | None 被视为 NULL，因此 middle_name 不能为 NULL。 | 由于 null=True，middle_name 可以为 NULL | None 被视为 NULL，因此 middle_name 不能为 NULL，blank=True 表示表单。 | 由于 null=True，middle_name 可以为 NULL | | Person.objects.create(名字='Johann '，姓氏='Bach ') | 未指定的 middle_name 默认为空字符串“”，操作成功，因为“”被视为 not null。 | 未指定的 middle_name 默认为空字符串“”，操作成功，因为“”被视为 not null。 | 未指定的 middle_name 默认为空字符串“”，操作成功，因为“”被视为 not null。 | 未指定的 middle_name 默认为空字符串“”，操作成功，因为“”被视为 not null。 | | Person.objects.create(名字='Johann '，中间名= ' '，姓氏='Bach ') | 显式空字符串“”被视为 not null，操作成功。 | 显式空字符串“”被视为 not null，操作成功。 | 显式空字符串“”被视为 not null，操作成功。 | 显式空字符串“”被视为 not null，操作成功。 | | Django admin 或常规 Django 表单中的中间名为空的表单验证。 | ![A441241_1_En_7_Figa_HTML.jpg](https://gitee.com/OpenDocCN/vkdoc-pythonweb-zh/raw/master/docs/begin-dj/img/A441241_1_En_7_Figa_HTML.jpg)Validation error due to empty middle_name. | ![A441241_1_En_7_Figb_HTML.jpg](https://gitee.com/OpenDocCN/vkdoc-pythonweb-zh/raw/master/docs/begin-dj/img/A441241_1_En_7_Figb_HTML.jpg)Validation error due to empty middle_name. | ![A441241_1_En_7_Figc_HTML.jpg](https://gitee.com/OpenDocCN/vkdoc-pythonweb-zh/raw/master/docs/begin-dj/img/A441241_1_En_7_Figc_HTML.jpg)Record creation valid even with empty middle_name due to blank=True. | ![A441241_1_En_7_Figd_HTML.jpg](https://gitee.com/OpenDocCN/vkdoc-pythonweb-zh/raw/master/docs/begin-dj/img/A441241_1_En_7_Figd_HTML.jpg)Record creation valid even with empty middle_name due to blank=True. |

Tip

下一章将介绍 Django 模型表单及其验证。

预定值:默认值、自动开始、自动开始添加和选择

有时给 Django 模型字段分配预定的值会很有帮助。例如，为了避免在没有提供值时出现空字符串——如表 7-2 中的一些情况所示——您可以在 Django 模型字段上使用default选项(例如，提供一个默认的 id、城市或日期)。在大多数情况下，您将default选项指定为硬编码值或方法引用。清单 7-6 展示了一个使用两种方法的default选项的例子。

def default_city():
    return "San Diego"

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    city = models.CharField(max_length=30,default=default_city)
    state = models.CharField(max_length=2,default='CA')

Listing 7-6.Django model default option use

正如你在清单 7-6 中看到的，我们有两个 Django 模型字段使用了default选项。首先，city字段依赖于default=default_city值——注意语法中缺少括号，这使得它成为对函数的引用——该函数告诉 Django 在每次创建新记录时调用default_city方法来填充字段。

值得一提的是，该方法被放在 Django 模型类之外，而不是在同一个类体中声明；这是为了允许在 Python 2 项目中序列化和支持 Django 模型迁移。 ¹ 接下来在清单 7-6 中，您可以看到state字段使用了default='CA'值，这告诉 Django 在创建新记录时使用硬编码的CA字符串来填充字段。

默认选项的执行完全由 Django/Python 完成(即数据库 DDL 不知道任何默认值)。这意味着当您使用类似清单 7-6 中的模型时，Django/Python 会介入提供默认值。例如，如果您创建一个 Django 模型实例作为Person.objects.create(name='Downtown',address='Main Street #5')，那么city和state值由 Django/Python 填充以创建记录。类似地，如果您转到 Django admin 并试图创建清单 7-6 中模型的实例，那么city和state表单字段会预先填充默认值。

尽管default选项的工作方式与对文本字段、数字和布尔字段的描述一样，但它对日期字段有特殊的行为——特别是models.DateField()和models.DateTimeField()——这很重要，所以让我们来研究一下，在讨论日期的同时，也了解一下与日期和时间模型字段相关的auto_now和auto_now_add选项。

from datetime import date
from django.utils import timezone

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    date = models.DateField(default=date.today)
    datetime = models.DateTimeField(default=timezone.now)
    date_lastupdated = models.DateField(auto_now=True)
    date_added = models.DateField(auto_now_add=True)
    timestamp_lastupdated = models.DateTimeField(auto_now=True)
    timestamp_added = models.DateTimeField(auto_now_add=True)

Listing 7-7.Django model default options for dates and times, as well as auto_now and auto_now_add use

清单 7-7 展示了清单 7-6 中的Store模型的修改版本，其中包含一系列日期字段变化。前两个附加字段date和datetime分别使用了使用 Python 的标准datetime库的带有默认值的DateField和使用 Django 的django.utils.timezone模块的带有默认值的DateTimeField——侧栏包含了关于为什么使用django.utils.timezone模块来创建日期时间值的更多细节。

在这种情况下，如果您基于清单 7-7 中的模型创建一个Store记录，Django/Python 会根据后台库的功能填充date和datetime字段的值。类似地，如果您转到 Django admin 并试图创建清单 7-7 中模型的实例，那么date和datetime表单字段会分别预先填充当前日期和日期时间的默认值。

Don’t Add () Parentheses to Methods in Default Values

如果仔细观察前面清单中的默认值，会发现它们的语法中缺少()，这就产生了一个重要的行为。通过省略()语法，Python 将引用分配给一个方法，并在运行时之前计算表达式，但是如果使用()语法(例如，default=timezone.now())，Python 会在编译时计算表达式。对于返回固定值的函数来说，这不是问题，但是对于返回动态计算值(例如，日期)的函数来说，这很关键；否则，您将获得在编译时计算的单个值(例如，日期或日期时间字段将包含在编译时为所有记录计算的相同值)。

Don’t Use the Basic Datetime.Now for Datetimefield Fields

由于 settings.py 中的 USE_TZ = True，Django 在默认情况下是时区敏感的。这意味着当您处理带有时间的日期(例如，在 DateTimeField 模型字段中)时，您必须提供时区敏感的日期。这就是为什么在清单 7-7 中的模型。datetime field(default = time zone . now)语句使用 Django 的 django.utils.timezone 模块，该模块生成时区感知日期。

在清单 7-7 中，有一对额外的DateField和DateTimeField字段使用了auto_now=True和auto_now_add=True选项。这两个选项的工作方式都类似于default选项——在某种意义上，它们添加了一个默认日期或日期&时间——但行为略有不同。第一个重要区别是default选项可用于多种类型的字段，而auto_now和auto_now_add选项是为DateField和DateTimeField字段设计的。

使用auto_now和auto_now_add选项的字段值在创建记录时生成。每次记录改变时，使用auto_now选项的字段值都会更新，而使用auto_now_add选项的字段值在记录的生命周期内保持冻结。默认情况下，使用auto_now或auto_now_add选项的DateField字段从datetime.date.today()生成它们的值，而使用auto_now或auto_now_add选项的DateTimeField字段从django.utils.timezone.now()生成它们的值。

与带有default选项的字段不同，带有auto_now和auto_now_add选项的字段不能被覆盖。这意味着，即使您创建或更新了一个记录，并为带有auto_now或auto_now_add选项的字段提供了一个值，该值也会被忽略。类似地，在 Django admin 中，默认情况下不显示使用auto_now和auto_now_add选项的字段，因为它们的值不能被修改。最后，值得一提的是auto_now、auto_now_add和default选项是互斥的(即，不能在一个字段中使用多个选项，否则会导致错误)。

如您所见，auto_now选项是跟踪记录的最后修改日期的理想选择，auto_now_add是跟踪记录的创建日期的理想选择，default选项是表单字段上的通用可修改日期。

预定值的另一个场景是使用choices选项将 Django 模型字段限制为一个值列表，以限制开放式值并减少不同的数据和错误(例如，一个状态列表["CA","AR"]，而不是让用户引入Ca、Cali、ar或Arizona)。清单 7-8 展示了一个使用choices选项的 Django 模型字段的例子。

ITEM_SIZES = (
            ('S','Small'),
            ('M','Medium'),
            ('L','Large'),
            ('P','Portion'),
            )

class Menu(models.Model):
    name = models.CharField(max_length=30)

class Item(models.Model):
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)
    size = models.CharField(choices=ITEM_SIZES,max_length=1)

Listing 7-8.Django model choices option

使用choices选项的第一件事是创建一个元组列表，如清单 7-8 所示。ITEMS_SIZES元组具有四个元组，其中第一元组元素表示在数据库中使用的关键字(例如，S、M)，第二元组元素表示第一元组元素的人类友好的表示(例如，Small、Medium)。

接下来，在清单 7-8 中，您可以看到size字段被赋予了choices=ITEM_SIZES值，该值告诉 Django 使用来自ITEM_SIZES的键作为潜在值。注意，在这种情况下，数据库中使用的键都是对应于CharField(max_length=1)数据类型的单字符文本值(例如S、M)，但是您也可以使用数字或布尔值作为键，只要它们匹配目标字段数据类型。

Tip

下一章将介绍带有选择选项的 Django 表单模型。

唯一值:Unique、unique_for_date、unique_for_month 和 unique_for_year

可以强制字段值在所有记录中是唯一的。例如，在清单 7-7 中，如果您将name=models.CharField(max_length=30)改为name=models.CharField(max_length=30, unique=True)，它会告诉 Django 确保所有的Store记录都有惟一的名称值。

Django 在数据库层(即通过添加 DDL UNIQUE SQL 约束)以及 Django/Python 层强制执行unique选项。此外，unique选项对除ManyToManyField、OneToOneField和FileField之外的所有字段类型有效。

为了强制字段和DateField或DateTimeField值的唯一性，Django 提供了unique_for_date、unique_for_month和unique_for_year选项。例如，在清单 7-7 中，为了使name字段的值与date_lastupdated字段的date唯一，您可以使用name = models.CharField(max_length=30, unique_for_date="date_lastupdated")语句告诉 Django 只允许一个记录具有相同的name和date_lastupdated(例如，您不能有两个记录具有name="Downtown"和date_lastupdated="2018-01-01"，但是允许两个记录具有name="Downtown"和不同的date_lastupdated值)。

unique_for_month和unique_for_year选项提供了更大的范围来实施验证。例如，name = models.CharField(max_length=30, unique_for_month="date_lastupdated")语句告诉 Django 在同一个月只允许一个具有相同名称和date_lastupdated值的记录，而name = models.CharField(max_length=30, unique_for_year="date_lastupdated")语句告诉 Django 在同一年只允许一个具有相同name和date_lastupdated值的记录。

由于unique_for_date、unique_for_month和unique_for_year选项的需求更加复杂，这些选项的实施是在 Django/Python 层完成的。此外，由于验证过程的性质，这些选项仅对DateField和DateTimeField字段有效，注意对于DateTimeField情况，仅使用值的日期部分。

表单值:可编辑、帮助文本、详细名称和错误消息

当 Django 模型在表单的上下文中使用时，由 Django 模型字段支持的表单字段可以通过各种模型选项来影响。以下选项与您在上一章 Django 表单中学到的表单选项完全相同，只是这些选项作为模型字段的一部分被分配给影响表单字段。

默认情况下，表单中显示的所有 Django 模型字段都是可编辑的，但是您可以通过使用editable=False选项来改变这种行为。用editable=False设置一个模型字段告诉 Django 在一个表单中完全忽略它(例如，在 Django admin 中),因此任何与表单字段相关的验证都会被忽略。

help_text选项允许在表单域旁边包含额外的文本。清单 7-9 展示了help_text选项的使用。

ITEM_SIZES = (
            ('S','Small'),
            ('M','Medium'),
            ('L','Large'),
            ('P','Portion'),
            )

class Menu(models.Model):
    name = models.CharField(max_length=30)

class Item(models.Model):
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100,help_text="Ensure you provide some description of the ingredients")
    size = models.CharField(choices=ITEM_SIZES,max_length=1)
    calories = models.IntegerField(help_text="Calorie count should reflect <b>size</b> of the item")

Listing 7-9.Django model help_text option

在清单 7-9 中，您可以看到有两个带help_text选项的字段。当基于这个 Django 模型的 Django 表单呈现在模板中时，模型中定义的help_text继续形成最终表单布局的一部分。

默认情况下，Django 模型字段名用于生成 Django 表单字段的标题，该标题使用模型字段名的大写版本。(例如，名称、描述)。您可以使用verbose_name选项配置更详细的表单域标题(例如，models.CharField (max_length=30,verbose_name="ITEM NAME")，输出表单域的ITEM NAME标题)。

如果您试图在表单中保存或更新 Django 模型，并且有任何值不符合底层字段类型，Django 会为不符合的值生成默认错误消息。这些错误消息虽然有用，但本质上是通用的，因此可以使用error_messages选项为每个字段定制这些错误消息。error_messages选项接受一个键值字典，其中键表示错误代码，值表示错误消息。有关error_messages字典结构的详细示例，请参见上一章 Django 表单。

Tip

第九章更详细地介绍了 Django 模型表单。

数据库定义语言(DDL)值:db_column、db_index、db_tablespace、primary_key

默认情况下，Django 根据 Django 模型的字段名生成数据库表的列名。例如，如果 Django 模型字段名为menu，Django 会生成一个名为menu的 DB 列。使用db_column选项(如name = models.CharField(max_length=30,db_column="my_custom_name"))可以覆盖这种行为。Django 用my_custom_name列名生成 DDL。

Django 模型的另一个与数据库相关的选项是db_index选项，它告诉 Django 为字段生成一个数据库索引(例如，size = models.CharField(choices=ITEM_SIZES,max_length=1,db_index=True)为size字段生成一个数据库索引)。请注意，在以下情况下，Django 会自动创建一个数据库索引，因此针对以下场景的db_index=True是多余的:

如果一个字段使用了unique=True选项，Django 会自动为该字段创建一个索引。您可以禁用此行为设置db_index=False。
如果一个字段是ForeignKey数据类型，Django 会自动为该字段创建一个索引。您可以禁用此行为设置db_index=False。

Tip

meta indexes 选项还可以为单个或多个字段定义索引。有关更多详细信息，请参见下一节“元类选项”。

如果使用 PostgreSQL 或 Oracle 数据库，可以通过db_tablespace名称为字段索引指定 DB 表空间。默认情况下，Django 使用项目在settings.py中的DEFAULT_INDEX_TABLESPACE值来确定表空间，但是如果一个字段使用了db_tablespace，那么这个值优先。如果数据库品牌不支持表空间(例如 MySQL 或 SQLite ),则忽略此选项。

最后，primary_key选项允许您为模型定义一个主键。默认情况下，如果没有用primary_key=True语句设置 Django 模型字段，Django 会自动创建一个名为id的AutoField数据类型来保存主键(例如，id = models.AutoField(primary_key=True)。primary_key选项的典型用例是引用其他字段的字段(如OneToOneField)或由于设计限制需要自定义主键。

内置和自定义验证器:验证器

除了前面章节中描述的 Django 模型的数据强制选项(例如，unique、default)，Django 模型还通过validators选项提供值的强制，这允许通过内置或定制方法实现更高级的验证逻辑。

Django 模型在django.core.validators包中提供了一系列内置的验证器方法，供模型数据类型使用。例如，models.EmailField数据类型依赖于django.core.validators.EmailValidator来验证电子邮件值，正如models.IntegerField数据类型使用MinValueValidator和MaxValueValidator验证器来分别执行min_value和max_value选项。

除了 Django 内置的验证器方法，您还可以创建定制的验证器方法。创建定制验证器方法的唯一要求是，方法接受模型字段的输入，并在值不符合预期规则的情况下抛出django.core.exceptions.ValidatorError。清单 7-10 展示了一个使用内置验证器和自定义验证器的模型。

ITEM_SIZES = (
            ('S','Small'),
            ('M','Medium'),
            ('L','Large'),
            ('P','Portion'),
            )

# Import built-in validator
from  django.core.validators import MinLengthValidator

# Create custom validator
from django.core.exceptions import ValidationError

def calorie_watcher(value):
    if value > 5000:
        raise ValidationError(
            ('Whoa! calories are %(value)s ? We try to serve healthy food, try something less than 5000!'),
            params={'value': value},
        )
    if value < 0:
        raise ValidationError(
            ('Strange calories are %(value)s ? This can\'t be, value must be greater than 0'),
            params={'value': value},
        )

class Menu(models.Model):
    name = models.CharField(max_length=30)

class Item(models.Model):
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30,validators=[MinLengthValidator(5)])
    description = models.CharField(max_length=100)
    size = models.CharField(choices=ITEM_SIZES,max_length=1)
    calories = models.IntegerField(validators=[calorie_watcher])

Listing 7-10.Django model field validators option with built-in and custom validator

清单 7-10 中的第一个validators选项使用内置的MinLengthValidator验证器类来强制name字段的值至少包含 5 个字符。清单 7-10 中的第二个validators选项使用定制的calorie_watcher验证器方法来强制calories字段的值符合某个范围，并在不符合该范围的情况下使用定制消息。值得一提的是，可以使用列表语法在单个字段上使用多个验证器方法(例如，validators=[MinLengthValidators(5),MaxLengthValidators(100)])。

Django 模型默认和定制行为

当你创建一个 Django 模型类时，它总是从django.db.models.Model类继承它的行为，如清单 7-1 所示。这个 Django 类提供了一个具有大量功能的 Django 模型，包括通过save()和delete()等方法进行的基本操作，以及模型的命名约定和查询行为。

在大多数情况下，django.db.models.Model类提供的默认行为就足够了，但是在其他情况下，您可能想要提供自定义行为。接下来，我将列举通过django.db.models.Model类提供的 Django 模型的功能。

模型方法

所有 Django 模型都继承了一系列操作方法，包括保存、删除、验证、加载以及将定制逻辑应用于模型数据。在接下来的部分中，我将描述这些方法的默认行为以及如何定制它们的行为。

save()方法

save()方法为 Django 模型提供了最常见的操作之一:将记录保存(即创建或更新)到数据库。一旦创建或引用了 Django 模型实例，就可以调用save()方法来创建/更新数据库上的实例。清单 7-11 说明了这个过程。

# Import Django model class
from coffeehouse.stores.models import Store

# Create a model Store instance
store_corporate = Store(name='Corporate',address='624 Broadway',city='San Diego',state='CA',email='corporate@coffeehouse.com')

# Invoke the save() method to create/save the record
# No record id reference, so a create operation is made and the reference is updated with id
store_corporate.save()

# Change field on instance
store_corporate.city='625 Broadway'

# Invoke the save() method to update/save the record
# Record has id reference from prior save() call, so operation is update
store_corporate.save()

Listing 7-11.Django model use of the save() method

在清单 7-11 中，对同一引用的save()方法进行了两次调用；第一个在数据库上创建记录，第二个更新数据库上的记录。

你能告诉我 Django 如何知道何时用相同的save()方法创建和更新记录吗？它不在众目睽睽之下，所以如果你找不到它也不用担心。

在本章的第一节中，当您创建 Django 模型时，我提到 Django 会自动添加一个id字段作为所有 Django 模型的主键，以使记录的搜索更加容易和高效。Django 使用这个id主键来确定save()方法是否执行创建或更新操作。

尽管在清单 7-11 中没有显式id主键值的痕迹，但是在 Django 创建一个实例后，模型实例会获得一个id值。清单 7-11 中第一次调用save()方法时，Django 试图创建一个新记录，因为它在实例上找不到id主键值。但是，如果创建操作成功，数据库会给记录分配一个返回给 Django 的id主键值，Django 会用这个id主键值更新引用。

在同一个模型引用上对save()方法的后续调用中，Django 检测到id主键值的存在，并基于这个id主键值执行更新操作。如果您想知道，如果您将一个显式的id主键值添加到一个记录引用中，Django 还会执行一个更新，因为它会查找这个标志来确定是创建还是更新一个记录，所以请注意放置一个显式的id主键值会更新/覆盖与给定的id主键值相关联的数据库记录。

既然您已经对 Django 模型的save()方法的默认行为有了很好的理解，我将描述一下save()方法的各种可用选项。save()方法接受一系列参数来覆盖它的默认行为；表 7-3 说明了这些参数、它们的行为以及它们的默认值。

表 7-3。

Django model save() method arguments

| 争吵 | 默认 | 描述 | | --- | --- | --- | | 强制插入 | force_insert=False | 显式地告诉 Django 在记录上强制执行创建操作(例如，保存(force_insert=True)。这很少使用，但是在您不依赖或不能依赖 Django 检测创建操作(即，通过 id 主键)的情况下会很有帮助。 | | 强制更新 | 强制更新=假 | 显式地告诉 Django 在记录上强制执行更新操作(例如，保存(force_update=True)。这种方法很少使用，但是在不依赖或不能依赖 Django 检测更新操作的情况下(例如，通过 id 主键)会很有帮助。 | | 使用 | using=DEFAULT_DB_ALIAS，其中 DEFAULT_DB_ALIAS 是一个常量，值为 DEFAULT | 允许 save()对不是 settings.py 中默认值的数据库执行操作(例如..。save(using='oracle ')对 oracle 数据库执行操作，其中 oracle 是 settings.py 中 DATABASES 变量的一个键)请参阅多数据库一章中的后面一节。 | | 更新 _ 字段 | 更新字段=无 | 接受要更新的字段列表(例如。save(update_fields=['name'])仅更新记录的名称值。当您拥有大型模型并希望进行更高效/更细粒度的更新时，这很有帮助，因为在默认情况下，Django 会更新所有的模型字段。 | | 犯罪 | 提交=真 | 确保将记录保存到数据库。在某些情况下(例如，模型表单或关系操作)，commit 被设置为 False 以创建模型实例而不保存它。这允许进行额外的操作(在表单、关系上),并基于它们的结果，决定进行标准的 save()调用以将记录写入数据库。 |

表 7-3 中您可能使用最多的选项是update_fields，因为它通过有选择地选择要更新的字段来提高性能。然而，表格 7-3 给了你完整的选项系列，以防你用save()方法碰到边缘情况。

最后，为了结束我们对save()方法的讨论，可以在 Django 模型上定义save()方法的实现，以便在调用该方法时执行定制逻辑。清单 7-12 说明了这个过程。

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)

    def save(self, *args, **kwargs):
        # Do custom logic here (e.g. validation, logging, call third party service)
        # Run default save() method
        super(Store,self).save(*args, **kwargs)

Listing 7-12.Django model with custom save() method

注意清单 7-12 中的save()方法是与 Django 模型的字段一起声明的。在这种情况下，当对这种类型的模型(例如，downtown.save())的引用调用save()时，Django 试图运行模型的自定义save()方法。这在您希望在创建或更新模型实例时执行其他操作(例如，记录消息、调用第三方服务)的情况下很有帮助。自定义save()方法super(Store,self).save(*args, **kwargs)中的最后一个片段告诉 Django 从django.db.models.Model运行基础save()方法。

Tip

参见本章后面的 Django 信号部分，在模型的 save()方法运行之前或之后执行逻辑。

delete()方法

delete()方法用于通过引用从数据库中删除记录。例如，如果在清单 7-11 中调用store_corporate.delete()——其中store_corporate是记录引用——Django 从数据库中删除记录。在底层，delete()方法依赖于id主键来删除记录，所以引用需要有id值来调用delete()方法。

当在引用上调用delete()方法时，它的id主键值被删除，但是记录的剩余值仍保留在内存中。另外，delete()方法用删除记录的数量来响应(例如，(4, {u'stores.Store_amenities': 3, u'stores.Store': 1}，表示总共删除了 4 条记录，其中有 1 条Store记录和 3 条stores.Store_amenities—stores.Store表示主Store模型上的一个关系。

与save()方法类似，delete()方法也支持两个参数:using=DEFAULT_DB_ALIAS和keep_parents=False。using参数允许您指定一个替代数据库来执行delete()操作——参见表 7-3 了解更多关于此类参数的详细信息以及本章后面的多数据库部分。当delete()操作发生在一个有关系的模型上，并且您希望保持父模型的数据不变——或者被删除——这是默认设置——时,keep_parents参数非常有用。关于使用keep_parents的更多细节将在本章后面的 Django 模型关系部分给出。

最后，还可以在 Django 模型类上定义一个定制的delete()方法——就像清单 7-12 中的save()——在删除记录时执行定制的逻辑(例如，创建审计跟踪)。

Tip

在模型的 delete()方法运行之前或之后执行逻辑，请参阅本章后面的 Django 信号部分。

验证方法:clean_fields()、clean()、validate_unique()和 full_clean()

当您使用save()方法创建或更新 Django 模型实例时，Django 会强制实例值符合模型定义的值。例如，如果您使用模型字段name = models.CharField(max_length=30)，Django 会强制执行name值，它是一个最多包含 30 个字符的文本字段。

理解 Django 模型实例验证最重要的部分是它是在两层上完成的:在数据库层和 Django/Python 层，这两层都是通过您在上一节中了解的模型数据类型实现的。

我们先分析一下数据库层验证层。一旦您有了 Django 模型并创建了它的初始迁移——如本章第一节“迁移和 Django 模型工作流”所述——Django 生成数据库 DDL(数据定义语言)来根据模型定义创建一个数据库表(例如，Django 模型字段CharField(max_length=30)生成一个varchar(30) NOT NULL数据库列类型)。因此，由于这个初始数据库 DDL，所有不符合验证规则的 Django 模型值肯定会在执行验证的数据库层被拒绝。

现在让我们分析 Django/Python 验证层。尽管用于字段的 Django 模型数据类型(例如,CharField(max_length=30)))可以给人一种它们自动作用于模型实例的印象，但是 Django/Python 验证层要求您在模型实例上执行验证方法来实施验证。如果不使用这些验证方法——这是本节的主题——数据库验证层是模型字段数据类型的唯一执行者。

尽管依赖数据库层的验证是完全可以接受的，但是在 Django/Python 层使用模型验证的优势在于支持更复杂的验证规则，并且减少了最终会被数据库拒绝的操作的数据库负载。然而，与在 Django 模型第一次迁移后自动完成的数据库层验证不同，Django/Python 层验证要求您使用以下一些模型方法。

让我们首先探索 Django 模型验证clean_fields()方法。清单 7-13 展示了一个模型定义，后面是一个使用clean_fields()方法的调用序列。

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30,unique=True)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)

# Create a model Store instance, that violates the max_length rule
store_corporate = Store(name='This is a very long name for the Corporate store that exceeds the 30 character limit',address='624 Broadway',city='San Diego',state='AZ',email='corporate@coffeehouse.com')

# No error yet

# You could call save() and let the database reject the instance...
# But you can also validate at the Django/Python level with the clean_fields() method
store_corporate.clean_fields()
Traceback (most recent call last):
    raise ValidationError(errors)
ValidationError: {'name': [u'Ensure this value has at most 30 characters (it has 84).']}

Listing 7-13.Django model use of validation clean_fields() method

首先，注意清单 7-13 中的模型名称字段使用了max_length=30选项来强制将这类值限制在 30 个字符以内。在模型定义之后，您可以看到store_corporate实例用一个大于 30 个字符的值破坏了这个规则，这意味着 Django 在实例创建时没有检测到破坏的模型规则。

虽然您可以尝试在最后一个实例上调用save()并让数据库通过它的 DDL 拒绝操作，但是您可以在实例上调用clean_fields()方法来告诉 Django 根据模型日期类型检查实例的值并引发一个错误。

还要注意清单 7-8 中的clean_fields()方法的输出是带有字典的ValidatioError数据类型。最后一个字典遵循键-值模式'<model_field>'-'[<error_message_list>]'，使得识别多个验证错误和重用这些数据用于其他目的(例如，日志记录、在模板中显示错误)变得容易。

虽然clean_fields()方法根据数据类型单独验证模型值，但是clean()方法可以用于实施更复杂的规则(例如，关系或特定值)。与您可以直接调用的clean_fields()方法不同，您必须用验证逻辑定义clean()方法的实现，如清单 7-14 所示。

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30,unique=True)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    def clean(self):
        # Don't allow 'San Diego' city entries that have state different than 'CA'
        if self.city == 'San Diego' and self.state != 'CA':
            raise ValidationError('Wait San Diego is CA!, are you sure there is another San Diego in %s ?' % self.state)

# Create a model Store instance, that violates city/state rule
store_corporate = Store(name='Corporate',address='624 Broadway',city='San Diego',state='AZ',email='corporate@coffeehouse.com')

# To enforce more complex rules call the clean() method implemented on a model
store_corporate.clean()
Traceback (most recent call last):
    raise ValidationError('Wait San Diego is in CA!, are you sure there is another San Diego in %s ?' % (self.state))
ValidationError: [u'Wait San Diego is in CA!, are you sure there is another San Diego in AZ ?']

Listing 7-14.Django model use of validation clean() method

注意，在清单 7-14 中，Django 模型类定义了clean()方法，该方法规定如果一个实例的城市值为San Diego,那么它的州必须为CA,如果不满足这个条件，就会产生一个ValidationError错误。接下来，当在违反该规则的实例上调用clean()方法时，会引发一个ValidationError错误，就像clean_fields()方法一样。

您可以使用的另一个 Django 验证机制是clean_unique()方法，它强制使用唯一选项的字段中没有两个实例具有相同的值。清单 7-15 说明了使用clean_unique()的方法。

Note

上一节关于 Django 模型数据类型的内容描述了 Django 模型字段的各种唯一值选项:unique、unique_for_date、unique_for_month 和 unique_for_year。

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30,unique=True)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)

# Create a model Store instance
store_corporate = Store(name='Downtown',address='624 Broadway',city='San Diego',state='AZ',email='corporate@coffeehouse.com')

# Save instance
store_corporate.save()

# Create another instance to violate uniqueness of address field
store_uptown = Store(name='Uptown',address='624 Broadway', city='San Diego',state='CA')

# You could call save() and let the database reject the instance...
# But you can also validate at the Django/Python level with the validate_unique() method
store_uptown.validate_unique()
Traceback (most recent call last):
    raise ValidationError(errors)
ValidationError: {'address': [u'Store with this Address already exists.']}

Listing 7-15.Django model use of validation clean_unique() method

with unique* fields

看看清单 7-15 中商店模型的address字段如何使用unique=True，它告诉 Django 不允许两个Store实例具有相同的address值。接下来，我们用address='624 Broadway'创建一个Store实例，并将其保存到数据库中。紧接着，我们用相同的address='624 Broadway'值创建另一个Store实例，但是因为地址模型字段有unique选项，这个新实例违反了规则。

因此，当您在store_uptown引用上调用validate_unique()方法时，Django 会引发一个ValidationError异常，表明数据库中已经有一个具有相同地址的Store记录。注意，即使您没有调用validate_unique()方法，数据库最终也会拒绝重复的记录，因为unique=True会产生必要的 DDL 来强制执行唯一的address值。

除了对标有唯一选项的字段执行验证的clean_unique函数之外，clean_unique方法还对在模型的Meta类中声明的unique_together选项执行验证。清单 7-16 中说明了这种变化。

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30,unique=True)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    email = models.EmailField()
    class Meta:
        unique_together = ("name", "email")

# Create instance to show use of validate_unique() via Meta option
store_downtown_horton = Store(name='Downtown',address'Horton Plaza',city='San Diego',state='CA',email='downtown@coffeehouse.com')
# Save intance to DB
store_downtown_horton.save()

# Create additional instance that violated unique_together rule in Meta class
store_downtown_fv = Store(name='Downtown',address'Fashion Valley',city='San Diego',state='CA',email='downtown@coffeehouse.com')

# You could call save() and let the database reject the instance but lets use validate_unique
store_downtown_fv.validate_unique()
Traceback (most recent call last):
ValidationError: {'__all__': [u'Store with this Name and Email already exists.']}

Listing 7-16.Django model use of validation clean_unique() method

with Meta unique_together

注意清单 7-16 中的类如何声明Meta类后跟unique_together = ("name", "email")，这告诉 Django 不允许两个Store实例具有相同的name和email值。

接下来，用相同的name和email值创建两个Store记录。因为这违反了 Django 模型元选项unique_together = ("name", "email")，在您保存第一条记录store_downtown_horton并对第二条记录store_downtown_fv调用validate_unique()方法后，Django 抛出一个ValidationError异常，表明数据库中已经有一条Store记录具有相同的name和email值。在本节的最后，我将更详细地描述 Django 模型的元类选项。

最后，所有 Django 模型上可用的最后一个验证方法是full_clean()方法，这是运行clean_fields()、clean()和validate_unique()方法的快捷方式——按这个顺序。

数据加载方法:Refresh_from_db()、from_db()和 get_deferred_fields()方法

如果您想用数据库中的数据更新一个预先存在的模型实例，或者因为数据库被另一个进程更新，或者您意外地(或故意地)更改了模型实例并想让它再次反映数据库中的数据，那么refresh_from_db()方法是一个有用的帮助。使用refresh_from_db()方法就像在模型引用上执行它一样简单(例如，downtown.refresh_from_db()从数据库中的值更新downtown实例)。

尽管调用refresh_from_db()方法时通常不带参数，但它支持两个可选参数。using参数可用于指定执行刷新操作的备用数据库，这种机制就像在save()和delete()方法中使用的选项一样，如表 7-3 所述。fields参数可用于有选择地刷新某些模型字段；如果没有提供字段参数列表，那么refresh_from_db()方法刷新所有模型字段。

在大多数情况下，Django 模型实例的初始加载机制是合理且足够的。然而，如果你想定制默认的加载机制，你可以定义from_db()方法。与可以在模型实例上调用的refresh_from_db()方法不同，from_db()方法不能被直接调用，而是作为模型类的一部分，在每次从数据库数据创建模型实例时被调用。那么什么是from_db方法的好理由呢？如果希望推迟加载模型数据。

例如，如果您开始处理大型 Django 模型(例如，超过 10 个字段)，您会很快注意到一次访问大量数据带来的性能下降。为了最小化这种性能影响，您可以创建一个from_db方法来延迟模型字段数据的加载，而不是让 Django 一次加载整个字段数据集，默认情况下它会这样做。

补充延迟模型字段功能的是get_deferred_fields()方法，它返回一个已经被延迟加载的模型字段列表。虽然from_db()和get_deferred_fields()方法没有refresh_from_db()方法那么多的使用场景，但是一旦您处理更大更复杂的模型，您可能会遇到对这两种模型方法的需求。下一章关于 CRUD 操作的部分将更详细地描述这些方法的使用。

自定义方法

到目前为止，我描述的所有方法都来自 Django 的django.db.models.Model类。虽然学习如何使用这些方法并为它们提供自己的实现很重要，但这并不一定意味着 Django 模型类仅限于使用这些方法。您可以使用您自己的定制模型类方法，如清单 7-17 所示。

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)

    def latitude_longitude(self):
        # Call remote service to get latitude & longitude
        latitude, longitude = geocoding_method(self.address, self.city, self.state)
        return latitude, longitude

Listing 7-17.Django model with custom method

清单 7-17 中的latitude_longitude方法赋予 Django 模型在模型实例上提供通用计算的能力。例如，对于一个名为downtown的商店实例，您可以调用downtown.latitude_longitude()来获得一个基于实例的address、city和state值的结果，这些值由一个远程服务辅助。这种类型的定制方法很有帮助，因为它支持封装，将在 Django 模型上操作的逻辑保留在它所属的地方——模型类本身。

模型管理器字段:对象

objects字段——技术上称为默认 Django 模型管理器——在所有 Django 模型上都可用，负责管理与 Django 模型实例相关的所有查询操作。这意味着当您执行 Django 模型查询操作(例如，创建、读取、更新或删除)时，您将最终使用 Django 模型的objects字段或模型管理器。

Django 模型的objects引用直接用于模型类，而不是模型的实例。例如，要读取 id=1 的Store模型记录，您可以使用Store.objects.get(id=1)语法，要删除所有的Store模型记录，您可以使用Store.objects.all().delete()语法。

模型管理器的objects字段没有被明确声明为 Django 模型的一部分——正如清单 7-1 中描述的那样，它与 Django 模型的id字段放在一起——但是它仍然存在于所有 Django 模型中。然而，您可以定制默认的模型管理器来使用另一个字段名称(例如，如果您需要一个名为objects的 Django 模型字段，您可以定制模型管理器来命名为mgr)。清单 7-18 展示了一个模型类，它将默认的模型管理器重命名为使用mgr引用名。

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    mgr = models.Manager()
Listing 7-18.Django default model manager renamed

正如您在清单 7-18 中看到的，您用models.Manager()显式声明了一个模型字段，以将另一个字段标记为默认模型管理器。如果您以这种方式覆盖默认经理，您将使用Store.mgr.get(id=1)语法读取带有id=1的记录，或者使用Store.mgr.all().delete()语法删除所有商店记录，而不是默认的模型经理objects语法。

Note

Django 模型查询的下一章致力于探索默认模型管理器或objects引用的功能方面，包括多记录的 CRUD 操作和一些与QuerySet类相关的微妙行为，以及模型管理器。

模型元类和选项

在前面关于模型验证方法的部分中——在清单 7-16 中——我利用了 Django 模型上的Meta类来加强模型字段值的唯一性。在这一节中，我将详述 Django 模型的元类的用途和可用选项。

Django 模型中的Meta类旨在从整体上定义 Django 模型的行为，这与 Django 模型数据类型(例如models.CharField)不同，后者定义 Django 模型字段上的粒度行为(例如，模型字段数据的长度可以是 30 或 50 个字符)。

Django Meta类及其选项总是在 Django 模型的数据类型之后声明，如清单 7-19 所示。

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)

    class Meta:
        ordering = ['-state']

Listing 7-19.Django model with Meta class and ordering option

在清单 7-19 中，您可以看到class Meta:语句声明了ordering = ['-state']选项。在这种情况下，ordering选项告诉 Django，当对模型进行查询时，它按照state字段以降序对结果进行排序。ordering元选项很有帮助，因为它覆盖了默认的模型查询顺序——这是由模型的id决定的——并且它避免了不断显式声明模型查询排序顺序的需要。

现在您已经对 Django 模型的Meta类有了基本的了解，在接下来的章节中，我将按类别对各种元选项进行分类，这样您就可以很容易地识别它们并适当地使用它们。

数据库定义语言(DDL)表选项:db_table、db_tablespace、managed、required_db_vendor、required_db_features 和 unique_together

默认情况下，Django 模型的数据库表名基于应用名称和模型，全部是小写字母，用下划线分隔。例如，对于名为stores的应用，名为Amenity的模型类默认使用stores_amenity数据库表。您可以使用 meta db_table选项为 Django 模型定义一个不同的数据库表名。

默认情况下，如果 Django 项目的后台数据库品牌(例如 Oracle)支持表空间的概念，Django 将使用settings.py中的DEFAULT_TABLESPACE变量作为默认表空间。可以通过 meta db_tablespace选项为 Django 模型指定一个替代表空间。注意，如果 Django 项目的后台数据库不支持表空间的概念，这个选项将被忽略。

所有 Django 模型都遵循图 7-1 中 Django 模型工作流程中描述的生命周期。作为这个生命周期的一部分，Django 管理为每个 Django 模型创建和/或销毁后台数据库表的 DDL。如果您想禁止 Django 对数据库执行模型的默认 DDL，可以使用 meta managed=False选项。当模型的后台数据库表是通过其他方式创建的，并且您不希望 Django 干扰这个表的管理时,managed=False选项非常有用。

因为 Django 可以与不同的数据库后端(例如 MySQL、Oracle、PostgreSQL)一起工作，所以您可能会遇到这样的情况:某些模型定义被设计为与并非所有数据库后端都可用的特性一起工作。为了确保针对某个数据库后端部署 Django 模型，可以使用两个元类选项。

required_db_vendor选项接受值sqlite、postgresql、mysql和oracle，以确保项目的底层数据库连接是给定供应商的；如果连接与指定的供应商不匹配，则不会针对数据库迁移模型。

required_db_features选项用于确保支持数据库连接启用了给定的特性列表，如果连接没有启用指定的特性列表，则模型不会针对数据库进行迁移。

Django 在django.db.backends.base.features.py中定义了超过 75 个数据库特性。一旦与数据库建立了连接，您就可以通过以下方式获得它所支持的 Django 特性:

from django.db import connection
dir(connection.features)

前面的代码片段输出了连接到 Django 项目的数据库所支持的特性。所有品牌都支持大多数 Django 数据库特性，因此required_db_features选项只要求您声明深奥的数据库特性，以确保底层 Django 数据库可以支持给定的模型(例如，gis_enabled确保数据库支持 Django 的地理信息系统模型特性，can_share_in_memory_db是 SQLite 支持的特性，但 MySQL 不支持，is_sql_auto_is_null_enabled是 MySQL 支持的特性，但 SQLite 不支持)。

unique_together选项强制没有两个模型记录具有相同的一对值。例如，unique_together('city','state')确保只有一个记录具有城市/州值(例如，加利福尼亚州圣地亚哥)，并拒绝所有其他创建具有相同城市/州值的记录的尝试。unique_together选项创建 DDL 来在数据库级别执行这个规则。unique_together选项还支持通过元组列表指定多个唯一字段对的能力(例如，unique_together(('city','state'),('city','zipcode'))强制城市/州和城市/邮政编码字段都是唯一的)。

数据库定义语言(DDL)索引选项:Indexes 和 index_together

索引在关系数据库记录的高效查找中起着重要的作用。简而言之，索引是一种特殊的结构，它包含某些记录列值，可以确保查询速度比查询主数据库表中的完整记录值更快。

Django 元类提供了两个选项来生成必要的 DDL(例如，创建索引...)来创建 Django 模型字段的数据库索引:indexes和index_together。

Tip

默认情况下，标记为主键和唯一的字段不需要显式创建索引。请参阅前面模型数据类型中的“db_index”、“primary_key”一节。

index元选项接受一列models.Index引用。一个model.Index引用接受一个fields值——它本身是一个创建索引的模型字段列表——和一个可选的name值——它是一个命名索引的字符串。清单 7-20 展示了index元选项的使用。

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)

    class Meta:
        indexes = [
             models.Index(fields=['city','state']),
             models.Index(fields=['city'],name='city_idx')
         ]

Listing 7-20.Django model with meta class and index option

如清单 7-20 所示，Store模型定义了两个索引。用于city和state字段的两字段索引，以及用于名为city_idx的city字段的索引。如果没有为索引提供name值，Django 会自动为索引命名。

Tip

默认情况下，Django 为所有关系数据库品牌创建 B *树索引。但是，如果您使用 PostgreSQL，Django 也支持 Brin 和 Gin 索引。 ²

index_together元选项允许您在 Django 模型上定义多字段索引，就像索引元选项中的model.Index引用一样。唯一的区别是index_together选项是元类的顶级选项(例如，index_together=['city','state']相当于清单 7-20 中的第一个索引)。

命名约定选项:详细名称、详细名称复数、标签、标签下限和应用标签

默认情况下，Django 模型由它们的类名引用。在大多数情况下，依赖这个名字是没有问题的——就像清单 7-20 中的类Store,一个Store就是你看到的商店。但是在其他情况下，一个模型类名可以使用一个缩略词或缩写词，虽然对于开发来说是合理的，但是对于其他人来说是不可表达的(例如，在一个用户界面(UI)元素上，比如一个模板或 Django admin)。

Django 模型可以使用verbose_name和verbose_name_plural元类选项来指定更明确的模型名称。例如，如果一个模型类被命名为SSN，您可以声明元类选项verbose_name='Social Security Number'来在依赖于模型实例的 ui 上使用这个最后的值。默认情况下，当引用一个 Django 模型类的多个实例时，Django 通过附加一个s来复数化一个模型类(例如，Store变成了Stores)。verbose_name_plural元类选项允许您在字母 s 不适用时定义一个定制的复数值(例如，带有verbose_name_plural='Strawberries'的模型类Strawberry在复数上下文中变成了Strawberries，而不是默认的不正确的Straberrys)。

要访问 Django 模型元类的verbose_name和verbose_name_plural值，可以使用语法<class_name>._meta.verbose_name和<class_name>._meta.verbose_name_plural.

Tip

如果您想为单个模型字段分配一个 verbose name 值，请参阅上一节中关于 Django 模型数据类型的 verbose_name。

Django 模型标签指的是一个<app_name>.<model_class>的组合，当模型被用作表单或 UI 组件的一部分时，这有时是必要的。Django 模型元类提供了label和label_lower只读属性——只读意味着属性值不能被设置(例如，像其他元属性如verbose_name)而只能作为元类的一部分读取。例如，如果在stores应用中定义了一个Store模型，语句Store._meta.label输出stores.Store。并且label_lower属性输出小写标签值，包括使用 camel case ³ 的类(例如对于stores app 中的模型类StoreFront，StoreFront._meta.label输出stores.StoreFront)。并且Store._meta.label_lower输出stores.storefront。

Django 应用是所有 Django 模型不可或缺的一部分，因为它定义了模型的默认数据库表前缀、模型迁移的位置以及模型的默认引用标签。元类app_label属性允许您为 Django 模型分配一个显式的应用名称。Django meta app_label优先于默认的应用模型命名机制。本章中关于将 Django 模型放在models.py之外的最后一节包含了关于 meta app_label选项的更多细节。

继承元选项:抽象和代理

meta abstract选项允许 Django 模型作为没有后台数据库表的基类，但是作为其他 Django 模型类的基础。清单 7-21 展示了一组使用abstract选项的 Django 模型。

from django.db import models

class Item(models.Model):
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)
    class Meta:
        abstract = True

class Drink(Item):
    mililiters = models.IntegerField()

Listing 7-21.Django model abstract option

清单 7-21 中的Item模型类是抽象的，这意味着它的行为就像跨编程语言的其他抽象类一样。 ⁴ 对于 Django 模型类，这意味着没有为该类型模型创建数据库表，也不能从中创建实例。然而，可以使用抽象模型作为其他 Django 模型的基础。

在清单 7-21 中，你可以看到Drink模型类继承了Item类的行为(相对于标准的 Django models.Model类)。注意，Drink类声明了额外的mililiters字段，但是因为它从Item类继承了它的行为，所以Drink类也获得了模型Item类字段(也就是说，Drink类变成了一个三字段模型，具有一个包含三列的数据库表——name、description和mililiters)。

meta proxy选项也是为 Django 模型继承场景设计的。但是不像abstract选项中父类被声明为抽象的，子类继承它们的行为，proxy选项被设计成让子类访问父类，而不用让子类成为成熟的模型类。标有 meta proxy选项的类使它们能够对父类及其数据库表执行操作，而无需拥有自己的数据库表。

例如，Store模型类可以有多个模型代理(例如，FranchiseStore，EmployeeOwnedStore)，其中每个代理类定义自己对Store模型的操作，而不将Store数据复制到单独的表中。Django 模型代理非常适合保护父类免受模型更改(例如，定制模型管理器或定制操作)的影响，同时仍然保留对父类的数据库表的访问。

查询元选项:排序、order_with_respect_to、get_latest_by、default_manager_name、base_manager_name、default_related_name 和 select_on_save

当您进行 Django 模型查询时——这将在下一章中详细解释——有许多种默认行为与它们的操作相关联。如果希望使用非默认的查询行为，可以显式创建带有显式参数的查询。然而，一遍又一遍地创建显式查询会令人厌倦；相反，您可以依赖本节中解释的元选项来分配模型的默认查询行为。

ordering元选项用于定义模型实例列表的默认排序。虽然您可以使用order_by()方法来定义一组模型实例的顺序(例如，Store.objects.all().order_by('-name')，按照名称降序排列所有商店对象)，但是您可以使用ordering元选项(例如，Store模型上的ordering=[-name])来确保模型实例列表总是被排序，而不需要order_by()方法(例如，Store.objects.all()使用ordering元选项来确定查询顺序)。

order_with_respect_to元选项也用于定义默认的排序查询行为，但是是在模型关系的上下文中。如果您在一个有关系的模型上执行查询，并且您想要在相关模型中的一个字段上建立默认排序，那么您可以使用order_with_respect_to元选项。

get_latest_by元选项用于为使用latest()和earliest()方法的查询指定默认模型字段。latest()和earliest()方法都指定了一个字段，通过该字段获取最新或最早的模型记录(例如，Receipt.objects.latest('date')以按日期获取最新的收据模型实例)。您可以使用get_latest_by元选项，这样用latest()和earliest()方法进行的查询就不需要参数。

所有模型都依赖于objects字段作为它们的默认模型管理器，如前面的“模型管理器字段”一节所述。在一个模型有多个模型管理器并且您必须指定一个默认管理器的情况下，使用default_manager_name元选项。在基础模型管理器不合适的情况下，base_manager_name元选项用于指定基础模型管理器——默认为django.db.models.Manager。下一章将更详细地描述使用定制模型管理器和这些元选项。

default_related_name元选项用于定义作为相关对象的字段的反向名称。这个反向命名的概念将在本章后面的模型关系一节中详细解释。

select_on_save元选项是 Django 遗留选项，它告诉 Django 使用模型的save()方法算法的 Django 1.6 之前的版本。该算法的行为不同于本章前面解释的save()方法的行为。

权限元选项:默认权限和权限

所有 Django 模型都被赋予了一组操作对象模型实例的权限。这些权限是 Django 内置用户管理系统不可或缺的一部分，被 Django 管理员广泛使用，并可以集成为 Django 项目一般权限工作流的一部分。

默认情况下，所有 Django 模型都通过设置为('add','change','delete')的 meta default_permissions被授予了添加、更改和删除对象实例的权限——谁可以实际添加、更改和删除实例将在 Django 用户管理和 Django 管理员一章中介绍。您可以在模型类上声明一个显式的元default_permissions值来撤销一个默认权限(例如，如果您不想分配权限，可以使用空元组()，或者使用('add','change')来拒绝模型类的删除权限)。

permissions meta 属性旨在为 Django 模型分配定制权限。例如，您可以为 Django 模型分配定制权限，以允许不同于一般添加、更改、删除操作的任务(例如，商店模型上的can_do_refunds)。permissions元属性接受元组权限列表，其中每个元组由引用权限代码和详细的权限描述组成(例如(('can_do_refunds','Can refund customers'),) ))。关于 Django 用户管理的后续章节将讨论定制权限的主题。

Django 模型中的关系

Django 模型默认在关系数据库系统(RDBMS)上运行，因此它们也支持彼此之间的关系。简而言之，数据库关系用于根据键或 id 关联记录，从而改善数据维护、查询性能和减少重复数据等。

Django 模型支持关系数据库系统支持的三种关系:一对多、多对多和一对一。

Django 模型中的一对多关系

一对多关系意味着一个模型记录可以有许多其他与其相关联的模型记录。例如，一个Menu模型记录可以有许多与之相关的Item模型记录，而一个Item属于一个Menu记录。要在 Django 模型中定义一个一对多的关系，您可以在有很多记录的模型上使用ForeignKey数据类型(例如在Item模型上)。清单 7-22 展示了一个一对多 Django 关系的例子。

from django.db import models

class Menu(models.Model):
    name = models.CharField(max_length=30)

class Item(models.Model):
    menu = models.ForeignKey(Menu)
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)

Listing 7-22.One to many Django model relationship

清单 7-22 中的第一个 Django 模型是Menu并具有name字段(例如Menu实例可以是Breakfast、Lunch、Drinks等)。).接下来，在清单 7-22 中是Item Django 模型，它有一个menu字段，它本身有models.ForeignKey(Menu)定义。models.ForeignKey()定义创建一对多关系，其中第一个参数Menu表示关系模型。

除了创建一对多关系的数据库级好处(例如，改进的数据维护)，Django 模型还提供了一个 API 来简化与这种关系相关的数据的访问，这将在下一章关于跨 Django 模型关系的 CRUD 记录中解释。

Django 模型中的多对多关系

多对多关系意味着许多记录可以有许多其他相互关联的记录。例如，Store模型记录可以有许多Amenity记录，就像Amenity记录可以属于许多Store记录一样。要在 Django 模型中定义多对多关系，可以使用ManyToManyField数据类型。清单 7-23 展示了一个多对多 Django 关系的例子。

from django.db import models

class Amenity(models.Model):
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    email = models.EmailField()
    amenities = models.ManyToManyField(Amenity,blank=True)

Listing 7-23.Many to many Django model relationship

清单 7-23 中的第一个 Django 模型是Amenity，它有name和description字段。接下来，在清单 7-23 中是具有amenities字段的Store Django 模型，它本身具有models.ManyToManyField(Amenity,blank=True)定义。models.ManyToManyField()定义通过连接表 ⁵ 创建多对多关系，其中第一个参数Amenity指示关系模型，可选的blank=True参数允许创建Store记录，而不需要amenities值。

在这种情况下，Django 创建的连接表用于保存Amenity之间的关系，并通过各自的键存储记录。尽管您不需要直接操作连接表，但出于引用的目的，Django 使用语法<model_name>_<model_field_with_ManyToManyField>来命名它(例如，对于存储在stores_store表中的Store模型记录和存储在stores_amenity table表中的Amenity模型记录，连接表是stores_store_amenities)。

除了创建多对多关系的数据库级好处(例如，改进的数据维护)，Django 模型还提供了一个 API 来简化与这种关系相关的数据的访问，这将在下一章关于跨 Django 模型关系的 CRUD 记录中解释。

Django 模型中的一对一关系

一对一关系意味着一个记录与另一个记录相关联。如果您熟悉面向对象编程，RDBMS 中的一对一关系类似于使用 is a 规则的面向对象继承(例如，汽车对象是车辆对象)。

例如，通用Item模型记录可以与Drink模型记录具有一对一的关系，其中后者记录保存特定于饮料的信息(例如，咖啡因含量)，而前者记录保存关于物品的通用信息(例如，价格)。要在 Django 模型中定义一对一的关系，可以使用OneToOneField数据类型。清单 7-24 展示了一个一对一 Django 关系的例子。

from django.db import models

class Menu(models.Model):
    name = models.CharField(max_length=30)

class Item(models.Model):
    menu = models.ForeignKey(Menu)
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)
    calories = models.IntegerField()
    price = models.FloatField()

class Drink(models.Model):
    item = models.OneToOneField(Item,on_delete=models.CASCADE,primary_key=True)
    caffeine = models.IntegerField()

Listing 7-24.One to one Django model relationship

列表 7-24 中的第一个 Django 模型是 Item，与列表 7-22 中的模型相似，只是列表 7-24 中的版本增加了calories和price字段。接下来，在列表 7-24 中是Drink模型，它有item字段，本身也有models.OneToOneField(Amenity,on_delete=models.CASCADE,primary_key=True)定义。

models.OneToOneField()定义创建了一对一的关系，其中第一个参数项表示关系模型。第二个参数on_delete=models.CASCADE告诉 Django，如果关系记录(即Item,)被删除，它的另一个记录(即Drink)也将被删除；最后一个参数防止了孤立数据。最后，primary_key=True告诉 Django 使用关系 id(即Drink.id)作为主键，而不是使用单独的默认列id，这种技术使得跟踪关系更加容易。

除了创建一对一关系的数据库级好处(例如，改进的数据维护)，Django 模型还提供了一个 API 来简化与这种关系相关的数据的访问，这将在下一章关于跨 Django 模型关系的 CRUD 记录中解释。

关系模型数据类型的选项

之前，您研究了 Django 数据类型和许多选项，以定制它们处理数据的方式，比如限制值、允许空值和 null 值、建立预定值以及实施 DDL 规则。在本节中，您将了解 Django 关系模型数据类型的可用选项。

Note

除非另有说明，否则通用模型数据类型部分中描述的选项(例如，空白、唯一)适用于关系模型数据类型。

数据完整性选项:on_delete

所有的模型关系都会在彼此之间产生依赖关系，所以一个重要的行为是当一方被移除时，另一方会发生什么。on_delete选项就是为了这个目的而设计的，它决定当一方被删除时，如何处理关系另一方的记录。

例如，如果一个Item模型有一个指向一个Menu模型的menu ForeignKey()字段(如清单 7-22 ，一个一对多的关系:一个Item总是属于一个Menu，一个Menu有多个Items)，如果删除相关的Menu模型实例，那么Item模型记录会发生什么？Item型号记录也删除了吗？

on_delete选项可用于所有三种关系模型数据类型，并支持以下值:

on_delete=models.CASCADE(默认)。-当相关实例被删除时，自动删除相关记录(例如，如果Menu早餐实例被删除，引用Menu早餐实例的所有Item记录也被删除)。
on_delete=models.PROTECT。-防止相关实例被删除(例如，如果Item上的menu字段使用ForeignKey(Menu,on_delete=models.PROTECT)，任何删除由Item实例引用的Menu实例的尝试都会被阻止)。
on_delete=models.SET_NULL。-当相关实例被删除时，将 NULL 分配给相关记录，注意这要求该字段也使用null=True选项(例如，如果Menu早餐实例被删除，所有引用Menu早餐实例的Item记录将 NULL 分配给它们的menu字段值)。
on_delete=models.SET_DEFAULT。-当相关实例被删除时，为相关记录分配一个默认值，注意这要求该字段也使用一个default选项值(例如，如果Menu早餐实例被删除，所有引用Menu早餐实例的Item记录被分配一个默认的Menu实例给它们的menu字段值)。
on_delete=models.SET。-当相关实例被删除时，通过一个可调用函数为相关记录分配一个值集(例如，如果删除了Menu早餐实例，则所有引用Menu早餐实例的Item记录都将通过一个可调用函数为其menu字段值集分配一个实例)。
on_delete=models.DO_NOTHING。-删除相关记录时不采取任何措施。这通常是一种糟糕的关系数据库实践，因此默认情况下，数据库会生成一个错误，因为您留下了没有值、null 或其他值的孤立记录。如果使用该值，必须确保数据库表不实施参照完整性。

引用选项:Self、文字字符串和 parent_link

模型关系有时有递归关系。这是具有父子关系的一对多关系模型中的常见场景。例如，Category模型可以有一个parent字段，它本身是另一个Category模型，或者Person模型可以有一个relatives字段，它本身是其他Person模型。要定义这种类型的关系，您必须使用'self'关键字来引用同一个模型，如清单 7-25 所示。

from django.db import models

class Category(models.Model):
    menu = models.ForeignKey('self')

class Person(models.Model):
    relatives = models.ManyToManyField('self')

Listing 7-25.One to many Django model relationship with self-referencing model

尽管模型关系数据类型通常通过模型对象引用(例如models.ForeignKey(Menu))来表达它们的关系，但是使用文字字符串来引用模型(例如models.ForeignKey('Menu'))也是有效的。当模型定义顺序不允许您引用还不在范围内的模型对象时，这种技术是有用的，并且这种技术通常被称为模型“延迟加载”。

parent_link=True选项是继承模型类时使用的一对一关系(即models.OneToOneField数据类型)的专用选项，用于帮助指示子类字段应该用作到父类的链接。

反向关系:相关名称、相关查询名称和对称

当您使用关系模型数据类型时，Django 会自动建立带有_set引用的数据类型之间的反向关系。清单 7-26 说明了这种机制。

from django.db import models

class Menu(models.Model):
    name = models.CharField(max_length=30)

class Item(models.Model):
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)
    price = models.FloatField(blank=True,null=True)

breakfast = Menu.objects.get(name='Breakfast')
# Direct access
all_items_with_breakfast_menu = Item.objects.filter(menu=breakfast)

# Reverse access through instance
same_all_items_with_breakfast_menu = breakfast.item_set.all()

Listing 7-26.One to many Django model relationship with reverse relationship references

正如您在清单 7-26 中看到的，Django 关系之间有两条路由。直接途径包括使用带有关系定义的模型；在这种情况下，Item用一个Menu早餐实例获得所有的Item记录。为此，使用Item并过滤menu ForeignKey参考(例如Item.objects.filter(menu=breakfast))。

但是也可以使用一个Menu实例(例如，清单 7-26 中的breakfast)并用一个menu实例获取所有的Item记录；这就是所谓的反向关系或路径。正如您在清单 7-26 中看到的，反向关系使用了<model_instance>.<related_model>_set语法(例如，breakfast.item_set.all()使用breakfast实例获取所有Item记录)。现在你知道什么是反向关系，让我们来探索与这个术语相关的选项。

related_name选项允许您定制名称或禁用反向模型关系。与清单 7-26 中的_set语法相比，重命名反向关系提供了更直观的语法，而当相关模型在其他上下文中使用，并且出于可访问性原因需要阻止对反向关系的访问时，禁用反向关系很有帮助。

例如，在清单 7-26 中，反向关系使用breakfast.item_set.all()语法，但是如果您将字段更改为models.ForeignKey(...related_name='menus')，您可以使用反向关系breakfast.menus.all()语法。要禁用反向关系，您可以在 related_name 值上使用+(加号)(如models.ForeignKey(...related_name='+'))。

反向关系也可以作为查询的一部分，如清单 7-27 所示。

# Based on models from listing 7-26

# Direct access, Item records with price higher than 1
Items.objects.filter(price__gt=1)

# Reverse access query, Menu records with Item price higher than 1
Menu.objects.filter(item__price__gt=1)

Listing 7-27.One to many Django model relationship with reverse relationship queries

注意清单 7-27 中的Menu查询如何使用item引用通过其Item关系过滤所有的Menu记录。默认情况下，反向关系查询使用模型的名称，所以在这种情况下，相关的Menu模型是Item；因此查询字段是item。但是，如果在字段上定义了related_name选项，则该值优先。例如，对于models.ForeignKey(...related_name='menus')，清单 7-27 中的反向查询变成了Menu.objects.filter(menus__price__gt=1)，所有这些都将我们带到了related_query_name选项。

在您希望反向查询具有不同字段值的情况下，related_query_name选项用于覆盖related_name选项值。例如，使用models.ForeignKey(...related_name='menus',related_query_name='onlyitemswith')，清单 7-26 中菜单的反向关系引用仍然有效，但是清单 7-27 中的反向关系查询将变为Menu.objects.filter(onlyitemswith__price__gt=1)。

覆盖多对多关系的边缘情况是symmetrical选项。如果你创建一个引用自身的多对多关系——如清单 7-25 和'self'语法所示——Django 假设关系是对称的(例如，所有的Person实例都是relatives的，因此不需要反向关系，因为这是多余的),这样自引用多对多关系就放弃了向字段添加一个_set反向关系。可以用symmetrical=False强制 Django 维持反向关系。

Tip

下一章将更详细地介绍 Django 模型关系查询。

数据库选项:to_field、db_constraint、可切换、through、through_fields 和 db_table

默认情况下，Django 模型关系建立在模型的主键上，而主键本身默认为模型的id字段。例如，字段menu = models.ForeignKey(Menu)存储来自Menu实例的id作为关系引用。您可以用to_field选项覆盖这个默认行为，并指定一个不同的字段来建立关系引用。注意，如果分配了一个to_field值，该域必须用unique=True设置。

默认情况下，Django 遵循关系数据库约定，并在数据库级别约束关系。默认为True的db_constraint选项允许你通过给它分配一个False值来绕过这个约束。只有当您预先知道数据库中的数据关系被破坏并且不需要在数据库级别进行约束检查时，才应该使用设置db_constraint=False。

swappable选项旨在影响包含关系并可与其他模型交换的模型的迁移。除非您实现了一个具有模型交换特性的非常复杂的模型层次结构，否则这个选项主要是为 Django 的内置User模型设计的，它使用一个关系，并且经常被定制的用户模型替换掉。关于用户管理的章节包含了关于这个选项的更多细节。

特定于多对多模型关系(即models.ManyToManyField数据类型)through、through_fields & db_table选项影响这些类型关系中使用的连接表。如果您想更改多对多连接表的默认名称，您可以使用db_table选项指定一个自定义连接表名称。

默认情况下，多对多关系的连接表存储最少量的信息:关系的 id 和每个模型关系的 id。可以指定一个单独的模型作为连接表，并存储关于多对多关系的附加信息(例如，through=MyCustomModel使用MyCustomTable模型作为多对多连接表)。如果您定义了一个through选项，那么也有必要使用through_fields来告诉 Django 新模型中的哪些字段用于存储模型关系的引用。

表单值:限制 _ 选择 _ 到

当带有关系的 Django 模型在表单的上下文中使用时，限制显示关系的数量可能是有用的，甚至是必要的。例如，如果您使用一个与一个Menu模型有关系的Item模型，如果您有数百个Item记录，那么将整个Item记录集显示为表单(例如，在 Django admin 中)是不切实际的。

可以在关系模型类型上使用limit_choices_to来过滤表单中显示的记录数量。limit_choices_to可以声明内联引用字段过滤器(如limit_choices_to={'in_stock':True})或执行更复杂逻辑的可调用程序(如limit_choices_to=my_complex_method_limit_picker)。

Tip

下一章将更详细地介绍 Django 模型表单。

Django 模型交易

事务在模型数据操作的完整性中扮演着重要的角色。当您在第一章为 Django 项目设置数据库时，在表 1-3 中描述的许多默认选项中，有以下与事务相关的设置:

AUTOCOMMIT = True
ATOMIC_REQUESTS = False

设置为True的AUTOCOMMIT选项确保所有更改数据的操作(即创建、更新和删除)在它们自己的事务中运行，并且根据结果，如果成功，自动提交到数据库，如果失败，则回滚。AUTOCOMMIT=True设置符合大多数应用的期望，因为它减少了显式标记操作 final 的需要，并提供了合理的行为(即，如果数据操作成功，它将成为 final[也称为 commit]，如果不成功，它将被还原[也称为 rolled back])。

然而，有时需要将更改数据的操作组合成更大的事务——要么全有要么全无的任务。

Tip

如果设置 AUTOCOMMIT = False，则需要显式声明提交。更实际的选择是保留默认的 AUTOCOMMIT = True，并根据具体情况显式声明更大的事务。

每个请求的事务:ATOMIC_REQUESTS 和 Decorators

Django 支持默认禁用的ATOMIC_REQUESTS选项。ATOMIC_REQUEST用于在对 Django 应用的每个请求上打开一个事务。通过设置ATOMIC_REQUEST=True，它可以确保只有在响应成功时，请求中包含的数据操作(即视图方法)才会被提交。

当您希望视图方法中的逻辑成为一个要么全有要么全无的任务时，Django 原子请求会很有帮助。例如，如果视图方法执行与数据相关联的五个子任务(例如，信用卡验证过程、发送电子邮件)，则确保只有当所有子任务都成功时，数据操作才被认为是最终的，并且如果只有一个子任务失败，则所有子任务都被回滚，就像什么都没发生一样，这可能是有帮助的。

由于ATOMIC_REQUEST=True为 Django 应用上的每个请求打开一个事务，这可能会对高流量应用造成性能影响。由于这个因素，当ATOMIC_REQUEST=True时，也可以选择性地禁用某些请求上的原子请求，或者当ATOMIC_REQUEST=False时，选择性地启用某些请求上的原子请求。清单 7-28 展示了如何有选择地激活和停用原子请求。

from django.db import transaction

# When ATOMIC_REQUESTS=True you can individually disable atomic requests

@transaction.non_atomic_requests
def index(request):
    # Data operations with transactions commit/rollback individually
    # Failure of one operation does not influence other
    data_operation_1()
    data_operation_2()
    data_operation_3()

# When ATOMIC_REQUESTS=False you can individually enable atomic requests

@transaction.atomic
def detail(request):
    # Start transaction.
    # Failure of any operation, rollbacks other operations
    data_operation_1()
    data_operation_2()
    data_operation_3()
    # Commit transaction if all operation successful

Listing 7-28.Selectively activate and deactivate atomic requests with @non_atomic_requests and @atomic

正如您在清单 7-28 中看到的，如果您决定使用 ATOMIC_REQUESTS=True，那么您可以使用django.db.transaction包中的@transaction.non_atomic_requests装饰器来禁用 view 方法上的每个请求的事务。如果您决定保留默认的ATOMIC_REQUESTS=False，那么您可以使用来自同一个django.db.transaction包的@transaction.atomic装饰器在一个视图方法上启用每个请求的事务。

上下文管理器和回调:atomic()和 on_commit()

除了AUTOCOMMIT和ATOMIC_REQUEST事务配置以及视图方法事务装饰器之外，还可以在中间范围内管理事务。即，比单个数据操作更粗糙的事务(例如，save())，但比原子请求更精细的事务(例如，视图方法)。

Python with关键字可以调用负责管理事务的上下文管理器 ⁶ 。事务的上下文管理器使用相同的django.db.transaction.atomic()方法——在清单 7-28 中用作装饰器——但是在方法体中，如清单 7-29 所示。

from django.db import transaction

def login(request):
    # With AUTO_COMMIT=True and ATOMIC_REQUEST=False
    # Data operation runs in its own transaction due to AUTO_COMMIT=True
    data_operation_standalone()

    # Open new transaction with context manager
    with transaction.atomic():
        # Start transaction.
        # Failure of any operation, rollbacks other operations
        data_operation_1()
        data_operation_2()
        data_operation_3()
        # Commit transaction if all operation successful

    # Data operation runs in its own transaction due to AUTO_COMMIT=True
    data_operation_standalone2()

Listing 7-29.Transactions with context managers

正如您在清单 7-29 中看到的，与运行在整个视图方法作用域上的原子请求相比，在方法内部生成事务而不影响其整个作用域是可能的。此外，Django 事务还支持回调，通过回调，一旦事务成功(即提交)，就可以运行任务。

回调是通过on_commit()方法支持的，它也是django.db.transaction包的一部分。on_commit()方法的语法如下:

transaction.on_commit(only_after_success_operation)

transaction.on_commit(lambda: only_after_success_with_args('success'))

on_commit()方法的参数可以是在成功事务后运行的非参数函数，或者是包装在lambda语句中的函数(如果在成功事务后运行的函数需要参数)。

一旦声明该方法的事务成功，就会触发transaction.on_commit()方法。如果在声明transaction.on_commit()方法的地方运行的事务失败了，那么on_commit()回调就不会被调用。如果在声明transaction.on_commit()方法的时候没有事务在运行，那么on_commit()回调会被立即触发。

Tip

在模型的 save()方法上使用 commit = False–如表 7-3 中所述–以避免事务(即写操作)并仍然在内存中创建模型对象。

Django 模型迁移

在本章的开始，您已经了解了 Django 模型是如何与迁移紧密联系在一起的。概括地说，迁移包括将 Django 模型在应用的models.py文件中的演变注册到“迁移文件”中，目的是以后检查这些models.py变化并将其应用到数据库中。

本质上，迁移文件在数据库和对定义在models.py文件中的 Django 项目模型所做的更改之间充当缓冲。由于数据是项目中如此微妙的一部分，迁移文件提供了非常理想的功能，例如在提交之前预览数据库更改的能力(例如，清单 7-4 中的sqlmigrate)以及在models.py文件状态下返回到某个时间点的能力，恢复通常复杂的 DDL 结构更改。

迁移文件创建

manage.py makemigrations命令是创建迁移文件的入口点。如果您不带参数地执行这个命令，Django 会检查所有在INSTALLED_APPS变量中声明的应用的models.py文件，并为其models.py内容在之前的迁移中已经改变的应用创建一个迁移文件。表 7-4 描述了最常见的makemigrations参数及其用途。

表 7-4。

Django most-used makemigrations arguments

| 争吵 | 描述 | | --- | --- | | | 指示特定应用的 models.py 文件(例如，manage.py makemigrations stores，仅检查/创建 stores 应用中 models.py 的迁移)。 | | -预演 | 模拟迁移创建，而不创建实际的迁移文件。 | | -空的 | 不管 models.py 文件是否被更改，都创建一个空的迁移文件。 | | -名称“我的迁移文件” | 使用自定义名称创建迁移文件，而不是默认的“auto_ 。请注意，用于迁移文件的前导序列号(例如 0001、0002)不是自定义的，因为这是识别迁移顺序的最佳做法。 | | -合并 | 从两个冲突的迁移文件创建合并的迁移。当同一个应用中存在多个序列号文件(例如，0002_unique_constraints.py、0002_field_update.py)时需要，通常是由于多人创建了重复的序列号(例如，当您尝试在这些情况下进行迁移时，Django 会抛出错误“检测到冲突的迁移”，建议您使用-merge 来解决问题)。 |

如表 7-4 所示，makemigrations命令提供了多种创建迁移文件的方法。您可以创建空的迁移文件，可以模拟迁移文件的创建以首先检查更改，还可以创建具有特定名称的迁移文件，等等。

Tip

请记住，您可以使用 sqlmigrate 命令预览迁移文件生成的 SQL，并使用 migrate 命令将迁移文件应用到数据库。有关模型迁移命令的其他示例，请参见本章的第一节。

迁移文件重命名

迁移文件不是一成不变的，因此可以重命名迁移文件。重命名迁移文件需要采取的步骤取决于迁移是否已应用于数据库。要确定一个迁移文件相对于数据库的状态，执行python manage.py showmigrations，如果一个迁移文件旁边有一个X，这意味着它已经被应用到数据库。

对于尚未应用到数据库的迁移，您可以直接在migrations文件夹中将迁移文件重命名为更具描述性的名称。在这一点上，迁移文件只是模型变更的一个表示，其他人不知道，所以如果需要的话，您甚至可以删除迁移文件。

Caution

迁移文件应始终保持序列号前缀(例如 0001、0002)，因为这样可以减少迁移文件顺序方面的混乱。

对于已应用于数据库的迁移，您有两种选择。第一个选项是重命名迁移文件，改变保存迁移活动的数据库表以反映这个新名称，并更新其他迁移文件依赖项(如果有)以反映这个新名称。重命名migrations文件夹中的迁移文件后，访问django_migrations数据库表，查找具有旧迁移文件名的记录，并将其更新以反映新的迁移名称。接下来，如果有一个比您要重命名的文件更新的迁移文件，更新的迁移文件将有一个dependencies语句——在迁移文件结构一节中描述——它必须用新名称更新。

第二种方法是回滚到要重命名的迁移文件之前的迁移，此时您可以简单地重命名该迁移文件(作为未应用的数据库迁移文件),然后将迁移过程重新应用到最近的迁移文件。下一节将更详细地描述迁移文件回滚。

迁移文件挤压

一个经历多次更改的models.py文件可以生成几十个甚至上百个迁移文件。在这些情况下，可以将多个迁移文件压缩到一个迁移文件中，以简化文件迁移管理。注意术语“挤压”与技术上更准确的术语“合并”相对，因为迁移文件合并指的是冲突的迁移文件，参见表 7-4 中的- merge 选项。

manage.py squashmigrations命令旨在压缩多个迁移文件，其语法如下:

manage.py squashmigrations <app_name> <squash_up_to_migration_file_serial_number>

如您所见，squashmigrations命令要求您指定要压缩迁移文件的应用，以及要压缩到的迁移序列号(例如，squashmigrations stores 0004从迁移文件0001、0002、0003和0004中为stores应用生成一个迁移文件)。

squashmigrations命令还支持一个额外的位置参数来改变默认0001的挤压过程的开始(例如squashmigrations stores 0002 0004，从迁移文件0002、0003和0004)生成一个迁移文件)

像所有文件合并机制一样，总有可能squashmigrations无法产生自动结果，在这种情况下，它会生成“需要手动移植”的消息，需要手动编辑压缩的迁移文件(例如，就像 git 等平台中的其他文件合并冲突操作一样)。

压缩的迁移文件遵循命名约定:

<initial_serial_number>_squashed_<up_to_serial_number>_<date>.py

您可以像重命名常规迁移文件一样重命名压缩的迁移文件；根据压缩的迁移文件是否已经应用到数据库，只需遵循上一节中描述的相同步骤。

压缩的迁移文件接管未压缩的迁移文件的职责。只要您愿意，您可以保留旧的(未压缩的)迁移文件，但是它们只在压缩的迁移文件应用到数据库之前继续发挥作用。在幕后，压缩的迁移文件使用replaces迁移字段——在下一节中描述——来指示它替换哪些迁移文件。因此，一旦您将压缩的迁移文件应用到数据库，就会忽略replaces中的迁移文件。

迁移文件结构

尽管迁移文件是基于对models.py文件所做的更改以及属于同一models.py文件的先前迁移文件自动创建的，但这并不意味着您不能或不必更改迁移文件的内部结构。清单 7-30 展示了 Django 迁移文件的基本结构。

from django.db import migrations, models

class Migration(migrations.Migration):

    initial = True

    replaces = [
    ]

    dependencies = [
    ]

    operations = [
    ]

Listing 7-30.Django migration file basic structure

首先，注意清单 7-30 中所有的迁移文件都包含一个名为Migration的类，它继承了django.db.migrations.Migration的行为。这允许迁移自动接收一系列默认行为，类似于 Django 模型类如何从django.db.models.Model类继承它们的行为。

在每个Migration类中有一系列决定迁移文件动作的字段。initial字段是一个布尔值，出现在每个应用的初始迁移文件上(即带有0001序列号的迁移文件)。replaces字段是一个列表字段，压缩迁移文件使用它来声明它替换哪些迁移文件，当您创建压缩迁移文件时，该值会自动填充。

dependencies和operations字段是迁移文件中最常见的两个字段。虽然它们在创建迁移文件后会自动填充，就像其他迁移文件字段一样，但如果您需要调整迁移文件执行的逻辑，这两个字段是您最有可能更改的字段。

dependencies字段是具有('<app_name>','<migration_file>')语法的元组列表，其中每个元组代表一个迁移依赖。例如，默认情况下，名为 about 的应用的第二个迁移文件包含以下dependencies值:

dependencies = [
    ('about', '0001_initial'),
]

这告诉 Django 迁移文件依赖于about应用中迁移文件0001_initial的执行，确保最后一个迁移文件首先运行。

编辑dependencies字段最常见的场景是添加应用间迁移文件依赖关系。例如，如果online应用依赖于stores应用通过其0002_data_population迁移文件创建的数据，您可以向online应用的第一个迁移文件添加依赖元组，以确保它在stores迁移文件(例如('stores', '0002_data_population'))之后运行。

Tip

要引用应用中的第一个迁移文件，您可以使用 first 引用(例如，(' stores '，' first ')，要引用应用中的最后一个迁移文件，您可以使用 latest 引用(例如，(' stores '，' latest ')。

operations字段声明了迁移操作的列表。 ⁷ 迁移操作包括由迁移执行的所有数据库相关任务。如果您想知道 Django 如何生成 DDL 来创建、删除、更改或重命名模型背后的数据库表，这都是基于迁移操作的。

在大多数情况下，Django 基于对一个models.py文件中的模型所做的更改来生成迁移操作。例如，如果您添加一个新的模型，那么下一个迁移文件包含一个django.db.migrations.operations.CreateModel()迁移操作；如果您在models.py中重命名一个模型，那么下一个迁移文件包括来自同一个django.db.migrations.operations包的RenameModel()操作；当您更改一个模型字段(AlterModel())、添加一个索引(AddIndex())并对一个models.py文件中的模型执行所有其他可能的修改时，也会发生同样的机制。

编辑迁移文件中的operations字段的最常见场景是添加非 DDL 操作(例如，SQL DML-数据操作语言),这些操作不能作为模型更改的一部分反映出来。例如，您可以通过RunSQL迁移操作将 SQL 查询作为迁移文件的一部分插入，也可以通过RunPython迁移操作将 Python 逻辑作为迁移文件的一部分运行。“Django 模型初始数据设置”一节描述了如何使用RunSQL和RunPython迁移操作。

迁移文件回滚

通过回滚迁移文件，可以将数据库恢复到 Django 模型的先前状态。将数据库恢复到以前的迁移文件非常简单，只需向应用迁移文件的同一个migrate命令传递一个额外的参数。例如，migrate stores 0001语句告诉 Django 将stores应用迁移到0001迁移文件中，如果应用的数据库状态在更新的迁移文件中(例如0004，Django 回滚迁移文件，直到数据库反映出0001迁移文件。

但是，尽管迁移文件回滚命令很简单，实际的回滚过程却一点也不简单。由于迁移文件可以包含多个 DDL 和 DML 操作(如前一节所述),因此某些迁移操作被认为是不可逆的。这意味着一旦应用了迁移，Django 就不能确定如何撤销它。

当使用不可逆操作在迁移上尝试回滚时，Django 抛出错误django.db.migrations.exceptions.IrreversibleError。当然，不可逆并不意味着不可能，但它确实意味着要做额外的工作才能使迁移文件可逆。

大多数不可逆的迁移操作发生在 DDL 迁移操作(如RunSQL, RunPython)上，其中您执行某些逻辑作为迁移文件的一部分。要使这些类型的迁移操作可逆，您同样必须提供逻辑来恢复作为迁移文件一部分应用的逻辑。“Django 模型初始数据设置”一节描述了如何为RunSQL和RunPython迁移操作创建反向操作。

Django 模型数据库任务

Django 可以在 Django 模型上执行数据库级的任务，这些任务通常由数据库工具来完成。Django 项目的manage.py命令提供了几个管理子命令，用于备份、加载和删除链接到 Django 模型的数据库表中的数据，以及从数据库表中重新创建 Django 模型和向数据库发出交互命令。

备份数据:Fixtures、dumpdata、loaddata 和 inspectdb

dumpdata和loaddata命令是 Django 的数据备份和加载工具，类似于数据库中包含的原生工具(如 MySQL mysqldump，Postgres pg_dump)。

Django 使用术语 fixture 来指代由dumpdata和loaddata命令创建和使用的数据结构。因为 Django fixtures 是为 Django 模型实例数据设计的，所以它们的结构基于更好地描述这种类型数据的格式。默认情况下，Django fixtures 使用 JSON (JavaScript 对象表示法)格式，但是也可以用 XML 和 YAML 创建 fixture。

dumpdata命令输出链接 Django 模型的数据库表数据。它接受各种选项，下面的示例中描述了最常见的选项:

manage.py dumpdata > all_model_data.json。-输出所有项目模型的数据，并将其放入all_model_data.json文件。
manage.py dumpdata stores --format xml。-以 XML 格式输出stores应用中所有型号的数据。
manage.py dumpdata about.contact --indent=2。-用两个空格缩进为about应用中的Contact模型输出数据-缩进使得输出更具可读性。
manage.py dumpdata items.menu –pk=1,2,3 --format yaml。-从items应用以 YAML 格式输出带有主键(即id值)1,2,3的Menu模型记录。

Note

要输出 YAML，您需要 PyYAML 包(例如，pip install PyYAML)。

manage.py loaddata命令用于加载由dumpdata生成的夹具文件。这意味着调用loaddata就像执行manage.py loaddata <fixture_file_name>一样简单。loaddata命令可以接受夹具文件的相对或绝对路径，但除此之外，它还在应用内的fixtures文件夹中搜索夹具文件。下一节“Django 模型初始数据设置”描述了在应用中使用 fixtures 的过程。

manage.py loaddata命令最重要的变化是它可以接受多个夹具文件作为参数(如loaddata <fixture_1>, <fixture_2>, <fixture_3>)，如果夹具文件有相互依赖性，这是必要的；并且它可以将夹具的搜索/加载限制到某些应用(例如，manage.py loaddata menu --app items，搜索/加载一个名为menu的夹具文件，但是只在items应用内，具体来说是在它的fixtures文件夹内)。

manage.py inspectdb是一个逆向工程过程，输出从数据库表生成的 Django 模型。注意manage.py inspectdb输出一个模型类的单个流，所以如果模型类被放在不同的models.py文件中，它需要重新安排输出。

删除数据:Flush、sqlflush 和 sqlsequencereset

Django 还提供了flush和sqlflush命令来删除链接到 Django 模型的数据库表的内容。manage.py flush命令触发实际的删除过程，而manage.py sqlflush输出删除 Django 模型数据库表中所有数据所需的 SQL(即flush触发的逻辑)。

manage.py sqlsequenereset命令输出所需的 SQL 来重置给定应用的数据库序列所使用的逻辑(例如，manage.py sqlsequencereset stores输出重置stores应用中的模型所使用的序列所需的 SQL)。数据库使用序列为某些 Django 模型字段(如id字段)自动增加值，当序列值变得不同步时，该命令用于修复问题。

与数据交互:dbshell

有时，为了执行复杂的任务或查询，不可避免地需要直接连接到与 Django 项目相关的数据库。manage.py dbshell命令被设计成使用 Django 项目settings.py文件中的凭证连接到 Django 项目的数据库，从而避免了输入凭证来访问数据库的需要。

根据您使用的数据库品牌，dbshell命令为每个数据库品牌的内置工具打开一个交互式命令行 shell:PostgreSQL 到dpsql环境，MySQL 到mysql环境，SQLite 到sqlite3环境，Oracle 到sqlplus环境。

Django 模型初始数据设置

在很多情况下，在 Django 模型上加载一组预定义的数据记录是有帮助的或者是必要的。Django 允许您加载预定义的记录，方法是用 Python 对它们进行硬编码；使用带有 SQL 语句的标准 SQL 脚本；或者使用 fixture 文件，这是上一节描述的 Django 导出/导入格式。

加载一组预定义数据记录的第一步是生成一个空迁移文件来处理实际的数据加载过程。清单 7-31 展示了如何生成一个空的迁移文件。

[user@coffeehouse ∼]$ python manage.py makemigrations --empty stores
Migrations for 'stores':
  0002_auto_20180124_0507.py:
Listing 7-31.Create empty Django migration file to load initial data for Django model

正如您在清单 7-31 中看到的，Django 为 stores 应用创建了空的迁移文件0002_auto_20180124_0507.py。此时，您可以按照上一节中的描述轻松地重命名迁移文件。一旦您有了一个空的 Django 迁移，让我们探索修改它的不同方法来为 Django 模型设置初始数据。

Python 迁移文件中的硬编码预定义记录

设置初始数据的最简单方法是对预定义的数据记录集进行硬编码，并使其成为迁移文件本身的一部分。清单 7-32 展示了一个修改过的迁移文件，其中包含要加载到数据库中的硬编码模型对象。

# -*- coding: utf-8 -*-
from __future__ import unicode_literals

from django.db import models, migrations

def load_stores(apps, schema_editor):
    Store = apps.get_model("stores", "Store")
    store_corporate = Store(id=0,name='Corporate',address='624 Broadway',city='San Diego',state='CA',email='corporate@coffeehouse.com')
    store_corporate.save()
    store_downtown = Store(id=1,name='Downtown',address='Horton Plaza',city='San Diego',state='CA',email='downtown@coffeehouse.com')
    store_downtown.save()
    store_uptown = Store(id=2,name='Uptown',address='1240 University Ave',city='San Diego',state='CA',email='uptown@coffeehouse.com')
    store_uptown.save()
    store_midtown = Store(id=3,name='Midtown',address='784 W Washington St',city='San Diego',state='CA',email='midtown@coffeehouse.com')
    store_midtown.save()

def delete_stores(apps, schema_editor):
    Store = apps.get_model("stores", "Store")
    Store.objects.all().delete()

class Migration(migrations.Migration):

    dependencies = [
        ('stores', '0001_initial'),
    ]

    operations = [
        migrations.RunPython(load_stores,delete_stores),
    ]

Listing 7-32.Load initial data with hard-coded data in Django migration file

添加到空迁移文件中的第一件事是operations[]列表中的migrations.RunPython(load_stores,delete_stored)行。RunPython方法运行 Python 代码，其第一个参数指示运行load_stores方法，第二个参数是可选的，称为反向代码，在回滚迁移时运行，这在上一节“迁移文件回滚”中提到过

清单 7-32 中的load_stores方法包含硬编码的数据记录。这个方法首先获取一个对Store模型的引用，然后创建三个不同的实例，然后保存到数据库中。delete_stores方法与load_stores方法相反——因为它的目的是回滚应用的数据——删除Store实例。

一旦将清单 7-32 中所示的内容添加到一个空的迁移文件中，您只需要用migrate命令触发迁移，将数据加载到数据库中。

带有 SQL 语句的 SQL 脚本

在其他情况下，您可能已经在 SQL 脚本中有了一组预定义的记录来填充数据库表。清单 7-33 展示了一个示例 SQL 脚本来填充与Store模型相关的表。

INSERT INTO stores_store (id,name,address,city,state,email) VALUES (0,'Corporate','624 Broadway','San Diego','CA','corporate@coffeehouse.com');
INSERT INTO stores_store (id,name,address,city,state,email) VALUES (1,'Downtown','Horton Plaza','San Diego','CA','downtown@coffeehouse.com');
INSERT INTO stores_store (id,name,address,city,state,email) VALUES (2,'Uptown','1240 University Ave','San Diego','CA','uptown@coffeehouse.com');
INSERT INTO stores_store (id,name,address,city,state,email) VALUES (3,'Midtown','784 W Washington St','San Diego','CA','midtown@coffeehouse.com');
Listing 7-33.SQL script with SQL statements

按照惯例，Django 以其存储数据的 Django 模型命名 SQL 脚本，并将 SQL 脚本放在模型所在的应用内名为sql的子文件夹中。例如，清单 7-33 的内容是针对stores app 中的Store车型的，因此会放在项目文件夹stores/sql/store.sql中。一旦在 Django 项目的目录结构中有了 SQL 脚本，就可以将其设置为 Django 模型的初始数据。清单 7-34 展示了一个修改后的迁移文件，用于将数据从清单 7-33 中的 SQL 脚本加载到数据库中。

# -*- coding: utf-8 -*-
from __future__ import unicode_literals

from django.db import models, migrations

def load_stores_from_sql():
    from coffeehouse.settings import PROJECT_DIR
    import os
    sql_statements = open(os.path.join(PROJECT_DIR,'stores/sql/store.sql'), 'r').read()
    return sql_statements

def delete_stores_with_sql():
    return 'DELETE from stores_store;'

class Migration(migrations.Migration):

    dependencies = [
        ('stores', '0001_initial'),
    ]

    operations = [
        migrations.RunSQL(load_stores_from_sql(), delete_stores_with_sql()),
    ]

Listing 7-34.Load initial data with SQL script in Django migration file

Note

用于加载 SQL 语句的 RunSQL 方法依赖于 sqlparse 包。因此，如果您计划使用这个功能，您需要安装这个包(例如，pip install sqlparse)。

添加到空迁移文件中的第一件事是operations[]列表中的migrations.RunSQL(load_stores_from_sql(),delete_stores_with_sql())行。RunSQL方法运行 SQL 语句，其第一个参数指示运行load_stores方法，第二个参数——可选——称为反向代码，在回滚迁移时运行——如前一节“迁移文件回滚”所述

清单 7-34 中的load_stores_from_sql方法在stores/sql/store.sql从主项目目录的相对路径中读取 SQL 脚本的内容，并返回文件中的 SQL 语句。在这种情况下，相对路径由 Django 项目的settings.py文件中定义的PROJECT_DIR变量提供，SQL 脚本使用 Python 的标准open方法读取。delete_stores_from_sql方法与load_stores_from_sql方法相反——因为它的目的是回滚应用的数据——删除Store实例。

一旦将清单 7-34 中所示的内容添加到一个空的迁移文件中，您只需要用migrate命令触发迁移，将数据加载到数据库中。

Django 夹具文件

在 Django 模型中加载初始数据的另一种方法是通过 fixture 文件。fixture 文件是一种 Django 特定的格式，用于管理 Django 模型的数据导出/导入，在前面关于 Django 模型数据库任务的部分中有所描述。清单 7-35 展示了一个 JSON fixture 文件来填充与Store模型相关的表。

[{
  "fields": {
    "city": "San Diego",
    "state": "CA",
    "email": "corporate@coffeehouse.com",
    "name": "Corporate",
    "address": "624 Broadway"
  },
  "model": "stores.store",
  "pk": 0
},
{
  "fields": {
    "city": "San Diego",
    "state": "CA",
    "email": "downtown@coffeehouse.com",
    "name": "Downtown",
    "address": "Horton Plaza"
  },
  "model": "stores.store",
  "pk": 1
}]
Listing 7-35.Django fixture file with JSON structure

Tip

使用 dumpdata 生成夹具文件，如“模型数据库任务”一节中所述

按照惯例，Django 以 Django 模型命名夹具文件，它存储数据并将夹具文件放在模型所在的应用内名为fixtures的子文件夹中。比如 7-35 列表内容是针对stores app 中的Store车型；因此它们被放在项目文件夹stores/fixtures/store.json中。一旦在 Django 项目的目录结构中有了 fixture 文件，就可以采取下一步将它设置为 Django 模型的初始数据。

清单 7-36 展示了一个修改后的迁移文件，用于将数据从清单 7-35 中的夹具文件加载到数据库中。

# -*- coding: utf-8 -*-
from __future__ import unicode_literals

from django.db import models, migrations

def load_stores_from_fixture(apps, schema_editor):
    from django.core.management import call_command
    call_command("loaddata", "store")

def delete_stores(apps, schema_editor):
    Store = apps.get_model("stores", "Store")
    Store.objects.all().delete()

class Migration(migrations.Migration):

    dependencies = [
        ('stores', '0001_initial'),
    ]

    operations = [
        migrations.RunPython(load_stores_from_fixture,delete_stores),
    ]

Listing 7-36.Load initial data from Django fixture file in Django migration file

添加到空迁移文件中的第一个东西是operations[]列表中的migrations.RunPython(load_stores_from_fixture,,delete_stores)行。RunPython方法运行 Python 代码，如清单 7-32 中所述。

清单 7-36 中的load_stores_from_fixture方法通过模拟manage.py loaddata命令的命令行执行，使用call_command方法加载夹具文件。loaddata命令需要一个附加参数来搜索特定应用中的夹具文件。在这种情况下，参数store告诉 Django 在所有应用的所有fixtures子目录中查找名为store的 fixture 文件。注意RunPython()也使用反向代码参数——如清单 7-32 所示——能够回滚夹具数据的加载。

一旦将清单 7-36 中所示的内容添加到一个空的迁移文件中，您只需要用migrate命令触发迁移，将数据加载到数据库中。

Django 模型信号

正如您在本章中所学到的，Django 模型有一系列方法，您可以覆盖这些方法来提供定制的功能。例如，您可以创建一个定制的save()或__init__方法，这样 Django 就会在保存或初始化 Django 模型实例时分别执行定制的逻辑。

虽然这种能力提供了在 Django 模型实例的生命周期中的某些点执行定制逻辑的各种可能性(例如，如果在实例上调用了delete()方法，则创建一个审计跟踪),但是也有在另一个模型实例的生命周期中发生事件时需要执行定制逻辑的情况。例如，保存Order模型实例时更新Item模型的stock值，或者每次更新Contact模型实例时生成一个Customer模型实例。

这些场景产生了一个有趣的实现问题。一种方法是互连两个模型类之间的逻辑，以实现这种类型的逻辑(例如，每次保存Order对象时，更新相关的Item对象)。不过，最后一种方法可能会变得过于复杂，要求更加苛刻，因为需要更新依赖类来代表其他类执行操作。一旦您面对对您无法控制的类执行动作的需求，这种类型问题只会变得更加复杂(例如，当内置的django.contrib.auth.User模型类的实例被保存时，您如何触发一个定制动作？).

事实证明，这种代表其他类触发动作的场景在软件中非常普遍，因此有一个名称:观察者模式。⁸Django 框架通过 Django 信号支持观察者模式。

最简单来说，Django 模型向项目环境发射信号，就像飞机向环境发射信号一样。类似地，您需要拦截信号的全部工作就是创建适当的接收器来拦截这样的信号(例如，一个接收器来检测所有项目模型的保存信号，一个接收器来检测特定模型的删除信号),并在信号出现时执行您需要运行的任何定制逻辑。

内置 Django 型号信号

默认情况下，所有 Django 模型都为它们最重要的工作流事件发出信号。这是一个非常重要的事实，唯一的原因是它提供了一种非侵入性的方法来链接任何 Django 模型的事件。请注意对任何 Django 模型的强调，这意味着您的项目模型、第三方应用模型甚至 Django 内置模型，这是可能的，因为信号被烘焙到所有 Django 模型使用的核心django.db.models.Model类中。表 7-5 显示了 Django 模型内置的各种信号。

Tip

Django 还为请求、响应、迁移前和迁移后事件以及测试事件提供了内置信号。参见内置信号参考。 ⁹

既然您已经知道所有 Django 项目模型总会发出一系列信号，那么让我们来看看如何得到信号通知，以便在信号出现时执行定制逻辑。

监听 Django 模型信号

监听 Django 模型信号——以及一般的 Django 信号——遵循一个简单的语法，使用来自django.dispatch包的@receiver装饰器，如清单 7-37 所示。

from django.dispatch import receiver

@receiver(<signal_to_listen_for_from_django_core_signals>,sender=<model_class_to_listen_to>)
def method_with_logic_to_run_when_signal_is_emitted(sender, **kwargs):
      # Logic when signal is emitted
      # Access sender & kwargs to get info on model that emitted signal

Listing 7-37.Basic syntax to listen for Django signals

正如您在清单 7-37 中所做的那样，您将想要对信号执行的逻辑包含在一个 Python 方法中，该方法遵循信号回调的输入签名；这反过来允许您访问关于发出信号的模型的信息。对于大多数信号，输入签名sender, **kwargs是合适的，但这可能因信号而异——有关每个信号使用的输入参数的详细信息，请参见信号的脚注参考。

一旦你有了一个在信号发射上运行的方法，这个方法必须用@receiver注释来修饰，它通常使用两个参数:一个要监听的信号——在表 7-5 中描述的那些——这是一个必需的参数和可选的sender参数来指定要监听信号的模型类。如果你想听到所有项目模型发出的相同信号——这种情况很少见——你可以省略sender参数。

表 7-5。

Built-in Django model signals

| 信号 | 信号类别 | 描述 | | --- | --- | --- | | 前初始化后初始化 | django . db . models . signals . pre _ init django . db . models . signals . post _ init | 在模型的 __init__()方法的开头和结尾发出的信号。 | | 预保存后保存 | django . db . models . signals . pre _ save django . db . models . signals . post _ save | 在模型的 __save__()方法的开始和结束时发出的信号。 | | 预删除后删除 | django . db . models . signals . pre _ delete django . db . models . signals . post _ delete | 在模型的 __delete__()方法的开始和结束时发出的信号。 | | m2m _ 已更改 | django . db . models . signals . m2m _ changed | 在模型实例上更改 ManyToManyField 时发出的信号。 | | 班级 _ 已准备 | django . db . models . signals . class _ prepared | 在 Django 的模型系统中定义并注册模型时发送信号。由 Django 内部使用，但很少用于其他情况。 |

现在，您已经对用于监听 Django 信号的语法有了基本的了解，让我们来探索 Django 项目中信号的放置和配置。

推荐的做法是将信号放在应用主文件夹下名为signals.py的文件中(即与models.py、views.py放在一起)。这使信号保持在明显的位置，但更重要的是，它避免了任何潜在的干扰(例如，加载问题，循环引用)，因为信号可能包含与模型和视图相关的逻辑。清单 7-38 展示了名为items的应用的signals.py文件的内容。

from django.dispatch import receiver

from django.db.models.signals import pre_save
from django.dispatch import receiver

import logging

stdlogger = logging.getLogger(__name__)

@receiver(pre_save, sender='items.Item')
def run_before_saving(sender, **kwargs):
    stdlogger.info("Start pre_save Item in signals.py under items app")
    stdlogger.info("sender %s" % (sender))
    stdlogger.info("kwargs %s" % str(kwargs))

Listing 7-38.Listen for Django pre_save signal on Item model in signals.py

首先，注意清单 7-38 中的信号监听方法使用@receiver装饰器来监听Item模型上的pre_save信号。这意味着每当一个Item模型实例将要被保存时，方法run_before_saving就会被触发。在这种情况下，会生成一些日志消息，但是该方法可以根据需要执行任何逻辑。

Tip

清单 7-38 中的 sender 参数使用了一个字符串模型引用，而不是标准的类导入引用。这确保了信号中的模型是延迟加载的，避免了模型和信号之间潜在的导入冲突。

一旦您有了一个包含所有信号监听方法的signals.py文件，您必须告诉 Django 检查这个文件以加载信号逻辑。推荐的做法是在apps.py文件中用一个import语句来实现，这也是应用结构的一部分。清单 7-39 展示了默认apps.py的修改版本，用于检查signals.py文件。

from django.apps import AppConfig

class ItemsConfig(AppConfig):
    name = 'coffeehouse.items'

    def ready(self):

        import coffeehouse.items.signals

Listing 7-39.Django apps.py with custom ready() method

to load signals.py

在清单 7-39 中，您可以看到apps.py文件包含了ready()方法。ready()方法，顾名思义，在应用准备好被访问时执行。在ready()内部，同一个 app 中的signals模块有一个import语句(即清单 7-38 )，这又使得 Django 加载清单 7-38 中的信号监听方法。

除了对apps.py文件进行修改以加载信号之外，还需要确保 Django 加载了apps.py文件本身。对于这一要求，清单 7-40 中显示了两个选项。

Option 1) Declare apps.py class as part of INSTALLED_APPS
# settings.py
INSTALLED_APPS = [
    'coffeehouse.items.apps.ItemsConfig',
     ...
]

Option 2) Declare default_app_config inside the __init__ file of the app

#/coffeehouse/items/__init__.py
default_app_config = 'coffeehouse.items.apps.ItemsConfig'

Listing 7-40.Django configuration options

to load apps.py

清单 7-40 中的第一个选项包括显式声明一个应用的配置类作为INSTALLED_APPS的一部分——在这里是coffeehouse.items.apps.ItemsConfig——而不是独立的包应用语句(例如coffeehouse.items)。这最后一个变化确保了定制的ready()方法作为初始化过程的一部分被调用。

清单 7-40 中的第二个选项包括将default_app_config值添加到应用的__init__文件(即除了apps.py、models.py和views.py之外的文件)中，并声明应用的配置类，在本例中为coffeehouse.items.apps.ItemsConfig。

清单 7-40 中的第一个选项是较新的，自从 Django 1.9 中引入 app 配置后就得到支持，第二个选项同样有效，并在引入 pp 配置之前使用。

在 Django 模型信号中发出自定义信号

除了表 7-5 中所示的 Django 内置信号，还可以创建自定义信号。当您想要执行与您自己的模型的工作流中的重要事件相关联的动作时(例如，当商店关闭时，当订单被创建时)，定制信号是有帮助的，而 Django 内置信号允许您监听重要的 Django 模型工作流信号(例如，在保存或删除模型实例之前和之后)。

创建定制信号的第一步是用django.dispatch.Signal类生成一个信号实例。Signal类只需要providing_args参数，这是信号发射器和接收器都希望Signal拥有的参数列表。下面的代码片段展示了两个定制的Signal实例:

from django.dispatch import Signal

order_complete = Signal(providng_args=["customer","barista"])

store_closed = Signal(providing_args=["employee"])

一旦您有了一个定制的Signal实例，下一步就是添加一个信号发射方法来触发一个Signal实例。对于 Django 模型，标准位置是作为类方法的一部分发出信号，如清单 7-41 所示。

from django.db import models
from coffeehouse.stores.signals import store_closed

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30,unique=True)
    ...
    def closing(self,employee):
        store_closed.send(sender=self.__class__, employee=employee)

Listing 7-41.Django model emitting custom signal

正如您在清单 7-41 中看到的，Store模型定义了一个名为closing()的方法，它接受一个employee输入。在这个closing()方法中，使用通过Signal继承的send()方法向名为store_closed的自定义Signal类发出一个信号，该方法使用自定义Signal类期望的参数。

接下来，当您引用了一个Store模型实例并在任何商店实例(例如downtown_store.closing(employee=request.user)上调用closing()方法时，就会发出一个定制的store_closed信号。谁会收到这个信号？任何人都在监听它，就像内置的 Django 信号一样。以下代码片段说明了自定义store_closed信号的信号监听方法:

@receiver(store_closed)
def run_when_store_is_closed(sender,**kwargs):
    stdlogger.info("Start store_closed Store in signals.py under stores app")
    stdlogger.info("sender %s" % (sender))
    stdlogger.info("kwargs %s" % str(kwargs))

这最后一种监听信号的方法几乎与用于监听内置 Django 信号的方法相同——在清单 7-38 的上一节中介绍过。在这种情况下，@receiver装饰器的唯一参数对应于信号名store_closed，这表明该方法正在监听这个信号。由于定制的store_closed信号是在有限的位置产生的(即，在单一模型方法中)——与所有模型产生的内置信号不同——所以@receiver装饰器放弃添加可选的sender参数。

models.py 之外的 Django 模型

默认情况下，Django 模型放在应用内的models.py文件中。然而，这个文件可能会超出需要存储数十或数百个模型的大型应用的需求。有三种技术可以用来从应用中的models.py文件中释放 Django 模型。

模型文件夹中应用内的 Django 模型

在models.py文件之外存储 Django 模型的第一个技巧是创建一个名为models的文件夹——在同一个应用中——在这个文件夹的独立文件中声明类模型，并通过这个新文件夹的__init__文件导入类。清单 7-42 显示了这种模型部署的应用文件夹布局。

+---+
    |
    +-stores(app)-+
                  +-__init__.py
                  +-models.py
                  +-tests.py
                  +-views.py
                  +-apps.py
                  +-models-+
                           |
                           +-__init__.py
                           +-menus.py
                           +-equipment.py
                           +-personnel.py

Listing 7-42.Django apps with models stored under models directory

注意清单 7-42 中标准models.py文件旁边是一个models文件夹。接下来，在models文件夹中有多个.py文件，它们声明了 Django 模型，因为它们通常在models.py中完成。每个.py文件中可以有任意多的模型，也可以有任意多的.py文件(例如，每个文件一个模型)。

然而，这个新的models文件夹中的__init__文件确实需要额外的关注。虽然__init__文件通常是空的，但在这种情况下，__init__文件必须为每个模型创建一个相对导入——在.py文件内——使它们对应用可见。例如，如果menus.py文件包含Breakfast模型类，那么__init__文件必须声明行from .menus import Breakfast。对于在models文件夹内的.py文件中声明的每个模型，必须在__init__.py中使用这种单行语法——from .<file> import <model_class>。

使用这种布局，您可以将 Django 模型放在单个models.py文件之外，但是以下几点适用于第一种重定位 Django 模型的技术:

该子文件夹必须命名为models。-因为默认情况下会检查models.py文件(作为 Python 路径<app>.models)，所以它需要一个同名的 Python 路径<app>.models来检测模型——由__init__文件完成其余的导入工作。所以请注意，除了models之外的任何其他文件夹名称都不能用于这种配置——这是在models.py之外配置模型的下一项技术，是使用不同文件夹名称的解决方案。
只要__init__文件执行正确的相对导入，将应用声明为INSTALLED_APPS的一部分就足够了。-只要一个应用在settings.py中被声明为INSTALLED_APPS的一部分，Django 就足以检测到在models文件夹中声明的任何模型，如清单 7-42 所述。只需相对导入__init__.py文件中的所有模型。
每个型号的应用名称都是自动确定的。-由于models文件夹嵌套在一个应用中，因此该文件夹中的所有型号都会收到在apps.py文件中为该应用配置的应用名称。尽管您可以使用元类app_label选项显式地将应用分配给模型——如前面元类选项一节中所述——但在这种情况下这是多余的，因为模型会收到相同的应用名称，包括它们的迁移文件的位置。
这些模型就像在models.py中一样可访问。-尽管模型被放在不同的文件中，Python 的访问路径仍然是 t app.models，因此模型就像在models.py中一样是可访问的(例如，要访问menus.py文件中的Breakfast模型类，您仍然可以从应用的其他部分使用from <app>.models import Breakfast)。

Django 模型在自定义文件夹中的应用内

在models.py文件外声明模型的第二种技术是在应用内使用自定义文件夹。这需要使用主models.py文件作为导入机制，也需要对模型使用更长的访问路径。清单 7-43 显示了一个带有模型自定义文件夹的应用文件夹布局。

+---+
    |
    +-stores(app)-+
                  +-__init__.py
                  +-models.py
                  +-tests.py
                  +-views.py
                  +-apps.py
                  +-menus+
                  |      +-__init__.py
                  |      +-breakfast.py
                  |
                  +-equipment+
                             +-__init__.py
                             +-kitchen.py
Listing 7-43.Django apps with models stored under custom directories

正如你可以列出的 7-43 应用现在有多个子文件夹，每个文件夹包含多个.py文件，这些文件声明了 Django 模型，因为它们通常会在models.py中完成。(即清单 7-43 中的breakfast.py和kitchen.py包含模型类)。

因为 Django 只在 Python 路径<app>.models下寻找模型，所以您必须在主models.py文件中为子文件夹中的每个模型声明一个相对导入，以使它们对应用可见。例如，如果Breakfast模型类在menus子文件夹文件和breakfast.py文件中，那么主models.py文件必须声明行from .menus.breakfast import Breakfast。对于在应用的子文件夹中声明的每个模型，必须在models.py中使用这种单行语法——from .<sub_folder>.<file> import <model_class>。

因为models.py文件使用模型本身的相对导入路径，这改变了访问模型的标准 Django Python 路径—from <app>.models...——并且需要一个更长的路径:f rom <app>.models.<sub_folder>.<file>...。除了导入路径的这一变化，模型的其余配置选项在行为上没有变化(即INSTALLED_APPS，模型应用名称)。

Django 在应用之外建模，并将模型分配给其他应用

Django 模型可用的第三种技术是完全在应用之外声明它们，或者包含性地将 Django 模型分配给一个不同于声明它们的应用。那么“将模型分配给应用”是什么意思呢？也就是说，你可以在应用之外或者在给定的应用中声明模型，但是要改变模型所属的应用。

虽然我不推荐这种技术，因为它会导致混乱，但它确实提供了一种不同的解决方案，为了完整起见，我将对其进行描述。

这种技术要求你通过元类app_label选项为模型提供一个明确的应用名称，这样它们就被分配给一个应用。当 Django 检测到一个模型时，它声明 meta app_label选项，这将优先为一个模型指定应用名称。因此，即使在名为common的随机文件夹或名为items的应用中声明了一个模型，如果模型的元app_label值被设置为stores，那么该模型就会被分配给stores应用，而不管其位置如何。

使用app_label选项令人困惑的一面是由于应用名称对 Django 模型的影响。例如，应用名称用于为模型的数据库表名称提供前缀，还用于确定模型迁移文件的位置。因此，如果你用元类app_label='stores'在名为common的文件夹中定义一个模型，这个模型将属于stores应用——连同它的迁移文件和前缀表应用名stores——即使它是在common文件夹中声明的。

正如我刚才解释的那样，最后一种技术虽然灵活，但也可能导致 Django 模型构造的命名和放置不直观。

Django 模型和多个数据库

回到第一章，当您为 Django 项目建立数据库时，您使用了settings.py中的DATABASES变量来定义类型和连接参数，以便在 Django 应用中执行所有与数据库相关的操作。因为这个变量是复数，这意味着你可以在一个 Django 项目中声明多个数据库，如清单 7-44 所示。

DATABASES = {
   'default': {
        ...
    },
   'devops': {
        ...
    },
   'analytics': {
        ...
    }
   'warehouse': {
        ...
    }
}
Listing 7-44.Django multiple DATABASES definitions

in settings.py

清单 7-44 显示了 Django 项目的四个不同的数据库，其中...符号是声明每个数据库连接参数的位置(例如ENGINE、NAME以及表 1-3 中描述的所有其他参数)。

清单 7-44 中最重要的方面是default键，它代表所有 Django 项目数据库相关操作的数据库，除非另有说明。在接下来的章节中，我将描述如何告诉 Django 在不同于default的数据库上执行数据操作。

Tip

如果您希望 Django 默认在不同于default的数据库上进行操作，您可以在settings.py中声明DEFAULT_DB_ALIAS值。(例如，DEFAULT_DB_ALIAS='analytics'告诉 Django 在分配给analytics句柄的数据库上执行所有与数据库相关的操作，除非另有明确说明)。

既然您已经知道了如何在 Django 项目中声明多个数据库以及default数据库的重要性，那么让我们来探索如何在一个 Django 项目中的多个数据库上执行指令。

Django 模型的多个数据库:使用

本章和下一章描述的所有 Django 模型操作都是针对数据库运行的，该数据库定义在DATABASES,的default句柄或DEFAULT_DB_ALIAS数据库句柄中。然而，对于多个数据库，可以有选择地对不同的数据库执行操作，覆盖默认的数据库。

Django 模型支持关键字using来指示对哪个数据库执行操作。using关键字有两种变体:

using选项。- Django 模型方法，如save()和delete()支持using选项来指示在哪个数据库中保存或删除记录。例如，store.save(using='analytics')告诉 Django 将商店记录保存到analytics数据库句柄，覆盖默认的数据库值。
using法。-默认的 Django 模型管理器objects支持using()方法来指示对哪个数据库执行查询。例如，Item.objects.using('warehouse').all()告诉 Django 从warehouse数据库句柄中获取所有的Item记录，覆盖默认的数据库值。

Django 工具的多个数据库:-数据库

除了 Django 模型能够有选择地对不同的数据库执行操作之外，执行数据库相关任务的 Django 工具还能够指定不同于default数据库句柄的数据库。

例如，migrate、dumpdata、loaddata等manage.py命令以及本章中描述的其他命令都支持--database标志来针对不同于default数据库句柄的数据库执行它们的逻辑。例如，mange.py migrate --database devops告诉 Django 在devops数据库上执行迁移过程，覆盖默认的数据库值。

多个数据库路由器:数据库路由器设置

虽然using和--database选项提供了在 Django 项目中使用多个数据库的解决方案，但是它们都需要将多数据库逻辑分散到应用的不同部分(例如，模型和脚本)。Django 数据库路由器提供了集中多数据库逻辑的能力，因此基于数据库操作的模型或类型，逻辑在不同于默认的数据库上执行。

Django 数据库路由器是标准的 Python 类，实现了表 7-6 中所示的四种不同的方法。

表 7-6。

Django database router methods

| 方法 | 描述 | | --- | --- | | db_for_read(型号，* *提示) | 建议用于模型读取操作的数据库。 | | db_for_write(型号，* *提示) | 建议用于模型写操作的数据库。 | | allow_relation(obj1，obj2，* *提示) | 建议是否(允许/阻止/无意见)obj1 和 obj2 之间的关系操作。 | | allow_migrate(db，app_label，model_name=None，* *提示) | 建议用于迁移操作的数据库。 |

**Hints are additional information provided to each router method to further determine which database to use each routing case, in addition to the other input parameters.

掌握了 Django 数据库路由器所用方法的基本知识后，让我们创建一个定制路由器，在一个数据库中存储与核心 Django 应用(例如，用户、管理、会话)相关的 Django 模型，在另一个数据库中存储其他 Django 项目模型。清单 7-45 展示了执行这个逻辑的 Django 数据库路由器。

class DatabaseForDevOps(object):

    def db_for_read(self, model, **hints):
        if model._meta.app_label in ['auth','admin','sessions','contenttypes']:
            return 'devops'
        # Returning None is no opinion, defer to other routers or default database
        return None

    def db_for_write(self, model, **hints):
        if model._meta.app_label in ['auth','admin','sessions','contenttypes']:
            return 'devops'
         # Returning None is no opinion, defer to other routers or default database
        return None

    def allow_relation(self, obj1, obj2, **hints):
        # Allow relations between two models that are both Django core app models
        if obj1._meta.app_label in ['auth','admin','sessions','contenttypes'] and obj2._meta.app_label in ['auth','admin','sessions','contenttypes']:
            return True
        # If neither object is in a Django core app model (defer to other routers or default database)
        elif obj1._meta.app_label not in ['auth','admin','sessions','contenttypes'] or obj2._meta.app_label not in ['auth','admin','sessions','contenttypes']:
            return None
        return None

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        if db == 'devops':
            # Migrate Django core app models if current database is devops
            if app_label in ['auth','admin','sessions','contenttypes']:
                return True
            else:
                # Non Django core app models should not be migrated if database is devops
                return False
        # Other database should not migrate Django core app models
        elif app_label in ['auth','admin','sessions','contenttypes']:
            return False
        # Otherwise no opinion, defer to other routers or default database
        return None

Listing 7-45.Django database router to store core app models in devops database and all other models in default database

清单 7-45—db_for_read()和db_for_write()中的前两个方法告诉 Django 如何进行模型的读写操作。在这种情况下，两个方法都检查模型app_name，如果app_name是auth、admin、sessions或contenttypes——所有这些都是 Django 核心应用——方法返回'devops'值，它代表一个数据库句柄，如清单 7-44 所示。这个逻辑告诉 Django 在devops数据库上为这些类型的模型执行所有的读写操作。如果一个模型不匹配任何引用的app_name值，注意两个方法都返回None，这表明路由器类对如何处理该模型没有意见，并且将控制传递给另一个路由器类或默认数据库，以确定在哪里执行模型的读/写操作。

这里值得一提的是，您可以使用多个 Django 数据库路由器，它们的配置顺序定义了它们的优先级。如果一个 Django 数据库路由器不能确定或没有定义在其上执行操作或模型的特定数据库，它移动到下一个数据库路由器，并且这个过程继续，直到所有的数据库路由器都用完，并且操作或模型默认使用default数据库。这种行为的优点是，数据库路由器不必为项目中的每个模型和操作声明数据库路由路径；为某些模型或操作声明路由规则就足够了，让 Django 使用默认数据库作为后台。

将我们的注意力转回清单 7-45,allow_relation()方法用于确定当一个模型包含相关模型时如何路由模型操作。例如，如果一个模型包含一个ForeignKey字段或ManyToManyField字段，这种关系可以跨越到另一个应用中，从而影响数据库表的位置。在清单 7-45 的情况下，allow_relation()方法表示如果相关模型对象属于auth、admin、sessions或contenttypes应用，则允许关系操作。

最后，清单 7-45 中的allow_migrate()用于定义运行哪些数据库迁移操作。在这种情况下，它表明如果对devops数据库进行迁移操作，它只迁移属于auth、admin、sessions或contenttypes应用的模型，并且它应该忽略所有其他模型迁移(即devops数据库应该只包含与auth、admin、sessions或contenttypes应用相关的模型表)。allow_migrate()中的第二部分表明，对于非devops的任何其他数据库，它应该忽略auth、admin、sessions或contenttypes应用的模型迁移(即default数据库将不包含与auth、admin、sessions或contenttypes应用相关的表)。

一旦有了类似清单 7-45 中的数据库路由器类，就必须将其声明为settings.py中DATABASE_ROUTERS值列表的一部分。假设清单 7-45 中的数据库路由器类位于routers.py文件的文件夹/coffeehouse/common/中，那么DATABASE_ROUTERS = ['coffeehouse.common.routers.DatabaseForDevOps'].

正如我已经提到的，DATABASE_ROUTERS值可以是数据库路由器的列表，所有的模型都要通过它来确定在哪个数据库上执行它们的操作，如果DATABASE_ROUTERS列表用完了，那么就使用默认的数据库。

完成设置数据库路由器配置后，必须在两个项目数据库上运行迁移操作。一旦完成，所有与 Django 核心应用模型相关的读写操作都将在devops数据库上完成，所有其他项目模型都将在default数据库上完成。

Caution

manage.py migrate 命令仅针对默认数据库执行迁移。这意味着，如果您需要对其他数据库执行迁移——例如这个数据库路由器配置示例——您必须使用- database 标志显式运行 migrate，以便为所有非默认数据库创建迁移。

Footnotes 1

https://docs.djangoproject.com/en/1.11/topics/migrations/#serializing-values

https://docs.djangoproject.com/en/1.11/ref/contrib/postgres/indexes/#module-django.contrib.postgres.indexes

https://en.wikipedia.org/wiki/Camel_case

https://en.wikipedia.org/wiki/Abstract_type

https://en.wikipedia.org/wiki/Associative_entity

https://docs.python.org/3/reference/datamodel.html#context-managers

https://docs.djangoproject.com/en/1.11/ref/migration-operations/

https://en.wikipedia.org/wiki/Observer_pattern

https://docs.djangoproject.com/en/1.11/ref/signals/

八、Django 模型查询和管理器

正如您在前一章中所了解到的，Django 模型通过类封装数据，执行数据验证，用于与 Django 项目的关系数据库进行交互，并且有无数的选项来保证和定制数据在 Django 项目中的操作方式。

在这一章中，我们将建立在前面的 Django 模型概念上，并学习 Django 模型查询和管理器。我们将从深入研究 Django 模型 CRUD(创建-读取-更新-删除)操作开始，包括单个、多个和关系查询，涵盖它们的速度和效率含义。接下来，您将了解 Django 模型支持的许多 SQL 查询变体，包括生成 SQL WHERE 语句的字段查找；建模方法以产生 SQL 语句，如 DISTINCT 和 ORDER 以及执行 SQL 聚合操作、数据库函数和子查询的查询表达式。

接下来，您将学习当 Django 的内置 SQL 工具不够用时，如何创建原始(开放式)SQL 查询。最后，您将学习如何在 Django 模型中创建和配置定制模型管理器。

Django 模型中的 CRUD 单一记录

处理单一记录是 Django 模型中最常见的任务之一。接下来，我将把下面的部分组织成传统的 web 应用 CRUD 操作，并描述每种情况下的各种技术，这样您就可以更好地掌握在不同情况下使用什么。

请注意，尽管以下部分集中于实际的 CRUD 操作及其行为，但有时我会不可避免地在示例中引入更高级的查询概念(例如，字段查找)，这将在本章的后面部分详细描述。

使用 save()或 Create()创建一条记录

要在 Django 模型上创建单个记录，您只需要创建一个模型实例，并在其上调用save()方法。清单 8-1 展示了为名为Store的模型创建单个记录的过程。

Tip

参考本书附带的源代码来运行练习，以减少打字和自动访问测试数据。

# Import Django model class
from coffeehouse.stores.models import Store

# Create a model Store instance
store_corporate = Store(name='Corporate',address='624 Broadway',state='CA',email='corporate@coffeehouse.com')
# Assign attribute value to instance with Python dotted notation
store_corporate.city = 'San Diego'
# Invoke the save() method to create the record
store_corporate.save() # If successful, record reference has id
store_corporate.id

Listing 8-1.Create a single record with model save() method

正如您在清单 8-1 中看到的，您可以在一个单独的步骤中声明所有的实例属性，或者您可以使用 Python 的点符号在引用本身上逐个分配属性值。一旦实例准备就绪，调用它的save()方法在数据库中创建记录。当您调用save()方法时，有两个重要的行为需要注意:

默认情况下，所有 Django 模型都被分配了一个名为id的自动递增主键，这个主键是在您启动模型的数据库表时创建的——请参阅上一章的“Django 模型和迁移工作流”一节了解更多详细信息。这意味着数据库给一个记录分配一个id值——除非你明确地给实例提供一个id值——这个值被传递回引用。
如果记录的创建违反了 Django 模型创建的任何数据库或 Django 验证规则，则记录的创建将被拒绝。这意味着如果一个新实例不符合这些验证规则中的任何一个，save()就会生成一个错误。关于规则验证的更多细节，请参见上一章的“Django 模型数据类型”一节。

当您使用save()方法创建记录时，这是最重要的两点。关于与 Django 模型save()方法相关的全套选项和微妙之处，请参见上一章的表格 7-3 和“模型方法”部分

在成功调用清单 8-1 中的save()方法后，您可以看到对象引用被赋予了id属性——由数据库创建——该属性用于将它直接链接到一个数据库记录，该记录稍后可以被更新和/或删除。

create()方法为创造记录提供了一条更短的路线。清单 8-2 展示了使用create()方法在清单 8-1 中创建的等价记录。

# Import Django model class
from coffeehouse.stores.models import Store

# Create a model Store instance which is saved automatically
store_corporate = Store.objects.create(name='Corporate',address='624 Broadway',city='San Diego',state='CA',email='corporate@coffeehouse') # If successful, record reference has id
store_corporate.id

Listing 8-2.Create a single record with create() method

您可以在清单 8-2 中看到，create()方法是通过模型的默认objects模型管理器在 Django 模型类上调用的。create()方法接受代表模型实例字段值的参数。create()的执行返回一个对已创建记录的对象引用，包括一个id值，就像save()方法一样。

在幕后，create()方法实际上使用了相同的save()方法，但是它使用模型管理器来允许在一行中创建一个记录。

用 get()或 get_or_create()读取单个记录

要读取单个数据库记录，您可以使用get()方法——它是模型的默认objects模型管理器的一部分——它接受任何模型字段来限定记录。清单 8-3 展示了get() Django 模型方法的一个基本例子。

# Import Django model class
from coffeehouse.stores.models import Store

# Get the store with the name "Downtown" or equivalent SQL: 'SELECT....WHERE name = "Downtown"
downtown_store = Store.objects.get(name="Downtown")

# Define uptown_email for the query
uptown_email = "uptown@coffeehouse.com"
# Get the store with the email value uptown_email or equivalent SQL: 'SELECT....WHERE email = "uptown@coffeehouse.com"'
uptown_email_store = Store.objects.get(email=uptown_email)

# Once the get() method runs, you can access an object's attributes
# either in logging statements, functions or templates
downtown_store.address
downtown_store.email

# Note you can access the object without attributes.
# If the Django model has a __str__/ method definition, the output is based on this method
# If the Django model has no __str__ method definition, the output is just <object>
print(uptown_email_store)

Listing 8-3.Read model record with get() method

正如您在清单 8-3 中看到的，get()方法使用 Django 模型属性作为其参数来检索特定的记录。第一个例子用name=Downtown获取Store记录，第二个例子用email=uptown@coffeehouse.com获取Store记录。一旦记录被分配给一个变量，您就可以使用 Python 的点符号来访问它的内容或属性。

Tip

除了单个字段-name="Downtown "或 email = " uptown @…"-get()方法还接受多个字段来生成 and 查询(例如，get(email="uptown@…"，name = " Downtown ")来获取电子邮件和姓名都匹配的记录)。此外，Django 还提供了字段查找来创建更好的单记录查询(例如，get(name__contains="Downtown ")来生成子串查询)。请参阅“按 SQL 关键字分类的查询”一章的后面部分。

使用 Django 模型的get()方法就是这么简单。然而，get()方法有一些您应该知道的行为:

使用get(),查询必须匹配且只能匹配一条记录。如果没有匹配的记录，您将得到一个<model>.DoesNotExist错误。如果有多个匹配记录，你将得到一个MultipleObjectsReturned错误。
每次调用都会立即命中数据库。这意味着 Django 不会对相同或多个调用进行缓存。

知道了这些get()限制，让我们来探索如何处理第一个场景，它涉及一个不存在的记录。当试图读取一个不存在的记录时，一个常见的情况是获取它，如果它不存在，就创建它。清单 8-4 展示了如何使用get_or_create()方法来达到这个目的。

# Import Django model class
from coffeehouse.items.models import Menu

# Get or create a menu instance with name="Breakfast"
menu_target, created = Menu.objects.get_or_create(name="Breakfast")

Listing 8-4.Read or create model record with get_or_create() method

正如您在清单 8-4 中看到的,get_or_create()方法——也是模型的默认objects模型管理器的一部分——在 Django 模型类上被调用，使用模型的属性作为它的参数来一步获得或创建记录。get_or_create()方法返回一对结果，模型实例——无论是创建的还是读取的——以及一个指示模型实例是创建的还是读取的布尔值(即，如果创建了就返回True，如果读取了就返回False)。

get_or_create()方法是一种同时使用了get()和create()方法的快捷方式——正如您在上一节中了解到的，后者在幕后使用了save()方法。不同之处在于，当get()没有找到匹配时，get_or_create()方法会自动处理错误情况。清单 8-5 展示了get_or_create()方法是如何在幕后工作的，如果您喜欢显式处理get()错误方法，也可以使用它。

from django.core.exceptions import ObjectDoesNotExist
from coffeehouse.items.models import Menu

try:
     menu_target = Menu.objects.get(name="Dinner")
     # If get() throws an error you need to handle it.
     # You can use either the generic ObjectDoesNotExist or
     # <model>.DoesNotExist which inherits from
     # django.core.exceptions.ObjectDoesNotExist, so you can target multiple
     # DoesNotExist exceptions
except Menu.DoesNotExist: # or the generic "except ObjectDoesNotExist:"      
     menu_target = Menu(name="Dinner")
     menu_target.save()

Listing 8-5.Replicate get_or_create() method with explicit try/except block and save method

正如您在清单 8-5 中看到的，当您知道某个记录可能不存在，并且您无论如何都想创建它时，有必要编写更多的代码(例如，错误处理、获取和保存调用)。因此在这种情况下，get_or_create()方法成为了一种有用的捷径。

现在让我们看看第二个get()限制，它涉及到在一个查询中获得多个记录。按照设计，如果有多个记录匹配一个查询，get()方法会抛出一个MultipleObjectsReturned错误。这种行为是一个实际的特性，因为在某些情况下，您希望确保查询只返回一条记录，否则会得到通知(例如，对于用户或产品的查询，重复项被认为是错误的)。

如果查询有可能返回一个或多个记录，那么您需要放弃使用get()方法，而使用模型管理器的filter()或exclude()方法。filter()或exclude()方法都产生一个名为QuerySet的多记录数据结构，可以通过一个额外的QuerySet方法将其简化为一个记录(例如，Item.objects.filter(name__contains='Salad').first()获得名称包含沙拉子串的第一个Item记录)。

由于 Django 模型的filter()或exclude()方法是为多记录查询设计的，这些方法和QuerySet行为将在后面关于多记录 CRUD 操作的章节中详细描述。类似于first()的其他QuerySet方法也将在后面关于通过 SQL 关键字分类的模型查询的章节中描述。

用 save()、Update()、update_or_create()或 refresh_from_db()更新单个记录

如果您已经有了一个对模型记录的引用，那么更新就像使用 Python 的点符号更新其属性并对其调用save()方法一样简单。清单 8-6 说明了这个过程。

# Import Django model class
from coffeehouse.stores.models import Store

# Get the store with the name "Downtown" or equivalent SQL: 'SELECT....WHERE name = "Downtown"

downtown_store = Store.objects.get(name="Downtown")

# Update the name value
downtown_store.name = "Downtown (Madison)"

# Call save() with the update_fields arg and a list of record fields to update selectively
downtown_store.save(update_fields=['name'])

# Or you can call save() without any argument and all record fields are updated
downtown_store.save()

Listing 8-6.Update model record with the save() method

在清单 8-6 中，您可以看到save()方法以两种方式被调用。您可以使用带有字段列表的update_fields参数来更新某些字段，并在大型模型中获得性能提升。或者另一种选择是使用没有任何参数的save()，在这种情况下，Django 更新所有字段。

如果您还没有对要更新的记录的引用，那么首先获取它(即发出一个 SELECT 查询)然后用save()方法更新它会稍微有些低效。此外，在单独的步骤中执行更新过程会导致争用情况。例如，如果另一个用户在同一时间获取相同的数据，并且也进行了更新，那么你们都会争着保存它，但是谁的更新是最终的，谁的更新会被覆盖呢？因为任何一方都不知道另一方正在处理相同的数据，所以您需要一种方法来指示(技术上称为锁定或隔离)数据，以避免出现竞争情况。

对于这种情况，您可以使用update()方法——模型的默认objects模型管理器的一部分——它在单个操作中执行更新，并保证没有竞争条件。清单 8-7 说明了这个过程。

from coffeehouse.stores.models import Store

Store.objects.filter(id=1).update(name="Downtown (Madison)")

from coffeehouse.items.models import Item
from django.db.models import F

Item.objects.filter(id=3).update(stock=F('stock') +100)

Listing 8-7.Update model record with the update() method

清单 8-7 中的第一个例子使用update()方法用id=1更新Store记录，并将其name设置为Downtown (Madison)。清单 8-7 中的第二个例子使用 Django F表达式和update()方法用id=3更新Item记录，并将其stock值设置为当前股票值加 100。目前，不要担心 Django F表达式——稍后将在更详细的查询中描述它们——只需认识到 Django F表达式允许您在查询中引用模型字段——作为 SQL 表达式——这在这种情况下是在单个操作中执行更新所必需的。

Caution

如果不小心的话，update()方法可以跨多个记录更新一个字段。update()方法前面是 objects.filter()方法，它可以返回多条记录的查询结果。注意，在清单 8-7 中，查询使用 id 字段来定义查询，确保只有一条记录与查询匹配，因为 id 是表的主键。如果 objects.filter()中的查询定义使用不太严格的查找(例如，字符串)，您可能会无意中更新比预期更多的记录。

与上一节描述的便利get_or_create()方法相似，Django 也提供了便利update_or_create()方法。当您想要执行更新并且不确定记录是否存在时，这种方法很有用。清单 8-8 说明了这个过程。

# Import Django model class
from coffeehouse.stores.models import Store

values_to_update = {'email':'downtown@coffeehouse.com'}

# Update for record with name='Downtown' and city='San Diego' is found, otherwise create record
obj_store, created = Store.objects.update_or_create(
    name='Downtown',city='San Diego', defaults=values_to_update)

Listing 8-8.Update or create model record with the update_or_create() method

清单 8-8 中做的第一件事是创建一个包含要更新的字段值的字典。接下来，您向update_or_create传递一个查询参数，用于一个期望的对象(即您希望更新或创建的对象)，以及包含要更新的字段值的字典。

对于清单 8-8 中的情况，如果已经有一个带有name='Downtown'和city='San Diego'的Store记录，则更新values_to_update中记录的值，如果没有匹配的Store，则记录一个带有name='Downtown'、city='San Diego'以及values_to_update中值的新商店记录。update_or_create方法返回一个更新的或创建的对象，以及一个布尔值来指示记录是否是新创建的。

Note

update_or_create 仅适用于单个记录的查询。如果有多个记录与 update_or_create()中的查询匹配，您将得到错误 MultipleObjectsReturned，就像 get()方法一样。

如果您不小心更改了一个模型记录，您可以使用refresh_from_db()方法从数据库中恢复它的数据，如清单 8-9 所示。

from coffeehouse.stores.models import Store

store_corporate = Store.objects.get(id=1)
store_corporate.name = 'Not sure about this name'

# Update from db again
store_corporate.refresh_from_db()  # Model record name now reflects value in database again
store_corporate.name

# Multiple edits
store_corporate.name = 'New store name'
store_corporate.email = 'newemail@coffeehouse.com' store_corporate.address = 'To be confirmed'

# Update from db again, but only address field
# so store name and email remain with local values
store_corporate.refresh_from_db(fields=['address'])

Listing 8-9.Update model record from database with the refresh_from_db() method

正如您在清单 8-9 中看到的，在更改了模型记录上的name字段值之后，您可以调用引用上的refresh_from_db()方法来更新数据库中的模型记录。清单 8-9 中的第二个例子使用了带有fields参数的refresh_from_db()方法，它告诉 Django 只更新在fields列表中声明的模型字段，允许对其他字段的任何(本地)编辑保持不变。

使用 Delete()删除单个记录

如果您已经有一个对记录的引用，删除它就像对它调用delete()方法一样简单。清单 8-10 说明了这个过程。

# Import Django model class
from coffeehouse.stores.models import Store

# Get the store with the name "Downtown" or equivalent SQL: 'SELECT....WHERE name = "Downtown"

downtown_store = Store.objects.get(name="Downtown")
# Call delete() to delete the record in the database
downtown_store.delete()

Listing 8-10.Delete model record with the delete() method

对于您还没有想要删除的记录的引用的情况，首先获取它(例如，发出一个 SELECT 查询)然后用delete()方法删除它可能会稍微有些低效。对于这种情况，您可以使用delete()方法并将其附加到一个查询中，这样一切都在一个操作中完成。清单 8-11 说明了这个过程。

from coffeehouse.items.models import Menu

Menu.objects.filter(id=1).delete()

Listing 8-11.Delete model record with the delete() method

on query

不管您使用的delete()方法是直接引用还是通过objects模型管理器,delete()方法总是返回一个包含删除操作结果的字典。例如，如果 8-11 中的删除操作成功，它将返回(1, {'items.Menu': 1})，表明删除了一条items.Menu类型的记录。如果 8-10 中的删除操作成功，它返回(5, {'stores.Store_amenities': 4, 'stores.Store': 1}),表明总共删除了五条记录，其中四条是stores.Store_amenities类型的，一条是stores.Store类型的——在这种情况下，删除了多条记录，因为stores.Store_amenities是Store模型中的一个模型关系。

Caution

如果不小心的话，delete()方法可以删除多条记录。delete()方法前面是 objects.filter()方法，该方法可以返回包含多条记录的查询结果。注意，在清单 8-11 中，查询使用 id 字段来定义查询，确保只有一条记录与查询匹配，因为 id 是表的主键。如果 objects.filter()中的查询定义使用不太严格的查找(例如，字符串)，您可能会无意中删除比预期更多的记录。

Django 模型中的 CRUD 多个记录

在本节中，您将学习如何在 Django 模型中处理多个记录。虽然这个过程与处理单个记录一样简单，但是处理多个记录可能需要多次数据库调用、缓存技术和批量操作，所有这些都需要考虑在内，以最大限度地减少执行时间。

用 bulk_create()创建多条记录

要基于 Django 模型创建多个记录，可以使用内置的bulk_create()方法。bulk_create()方法的优点是它在一个查询中创建所有的条目，所以如果您有一个想要创建的十几个或一百个条目的列表，这将是非常有效的。清单 8-12 展示了为Store模型创建多个记录的过程。

# Import Django model class
from coffeehouse.stores.models import Store

# Create model Store instances
store_corporate = Store(name='Corporate',address='624 Broadway',city ='San Diego',state='CA',email='corporate@coffeehouse.com')
store_downtown = Store(name='Downtown',address='Horton Plaza',city ='San Diego',state='CA',email='downtown@coffeehouse.com')
store_uptown = Store(name='Uptown',address='240 University Ave',city ='San Diego',state='CA',email='uptown@coffeehouse.com')
store_midtown = Store(name='Midtown',address='784 W Washington St',city ='San Diego',state='CA',email='midtown@coffeehouse.com')

# Create store list
store_list = [store_corporate,store_downtown,store_uptown,store_midtown]

# Call bulk_create to create records in a single call
Store.objects.bulk_create(store_list)

Listing 8-12.Create multiple records of a Django model with the bulk_create() method

在清单 8-12 中，您可以看到bulk_create()方法接受一个模型实例列表，在一个步骤中创建所有记录。尽管bulk_create()方法很有效，但您应该知道它有一定的局限性:

它不支持保存前和保存后模型信号。-为了加快速度，与创建单个记录的save()方法不同，bulk_create()方法不执行预保存和后保存模型信号。如果您不熟悉模型信号的概念，预保存和后保存模型信号允许在保存模型记录之前和之后执行自定义逻辑，这是上一章中讨论的主题。
它不支持跨多个表的模型(即，彼此之间有关系)。-因为记录是批量创建的，所以无法获得第一种类型的已创建记录的主键引用，这些记录随后用于创建相关的子记录。如果一个模型跨越多个表，那么您必须使用save()方法单独创建每个记录，该方法支持创建跨越多个表的记录。

如果您面临bulk_create()方法的这些限制，唯一的替代方法是循环遍历每个记录并使用save()方法创建每个条目，如清单 8-13 所示。

# Same store_list as Listing 8-12

# Loop over each store and invoke save() on each entry # save() method called on each list member to create record
for store in store_list:
    store.save()

Listing 8-13.Create multiple records with the save() method

正如我在介绍bulk_create()方法时提到的，如果对几十或几百条记录执行清单 8-13 中的过程会非常低效，但有时这是批量创建多条记录的唯一选择。但是，如果您手动处理模型事务，与清单 8-13 相关的速度问题可以得到改善。

清单 8-14 展示了如何使用save()方法并将整个记录创建过程分组到一个事务中，以加速批量创建过程。

# Import Django model and transaction class
from coffeehouse.stores.models import Store
from django.db import transaction

# Create store list, with same references from Listing 8-12
first_store_list = [store_corporate,store_downtown]
second_store_list = [store_uptown,store_midtown]

# Trigger atomic transaction so loop is executed in a single transaction
with transaction.atomic():
    # Loop over each store and invoke save() on each entry
    for store in first_store_list:
        # save() method called on each member to create record        
        store.save()

# Method decorated with @transaction.atomic to ensure logic is executed in single transaction
@transaction.atomic
def bulk_store_creator(store_list):
    # Loop over each store and invoke save() on each entry
    for store in store_list:
        # save() method called on each member to create record
        store.save()

# Call bulk_store_creator with Store list
bulk_store_creator(second_store_list)        

Listing 8-14.Create multiple records with save() method in a single transaction

正如您在清单 8-14 中看到的，有两种方法可以在单个数据库事务中创建批量操作，都使用django.db.transaction包。第一个实例使用with transaction.atomic():语句，因此该语句中的任何嵌套代码都在单个事务中运行。第二个实例使用@transaction.atomic方法装饰器，它确保方法操作在单个事务中运行。

Be Careful with Explicit Transactions

Django 的默认数据库事务机制为每个查询创建事务是有原因的:为了安全起见，尽量减少数据丢失的可能性。

如果您决定使用显式事务来提高性能——如清单 8-14 所示——请注意，要么创建所有记录，要么不创建记录。虽然这可能是一种期望的行为，但在某些情况下，它可能会导致意想不到的结果。确保您理解事务对您正在处理的数据的影响。前一章包含了更详细地讨论 Django 模型事务的部分。

用 all()、filter()、exclude()或 in_bulk()读取多条记录

要读取与 Django 模型相关的多个记录，可以使用几种方法，包括all()、filter()、exclude()和in_bulk()。all()方法的目的应该是不言自明的:它检索给定模型的所有记录。filter()方法用于将查询结果限制在给定的模型属性上，例如，filter(state='CA')是一个获取所有带有state='CA'的模型记录的查询。而exclude()方法用于执行排除给定模型属性上的记录的查询，例如exclude(state='AZ')是获取除state='AZ'之外的所有模型记录的查询。

还可以链接filter()和exclude()方法来创建更复杂的多记录查询。例如，filter(state='CA').exclude(city='San Diego')是一个获取所有带有state='CA'的模型记录并排除那些带有city='San Diego'的模型记录的查询。清单 8-15 展示了更多的多记录查询示例。

# Import Django model class
from coffeehouse.stores.models import Store

# Query with all() method or equivalent SQL: 'SELECT * FROM ...'
all_stores = Store.objects.all()

# Query with include() method or equivalent SQL: 'SELECT....WHERE city = "San Diego"'
san_diego_stores = Store.objects.filter(city='San Diego')

# Query with exclude() method or equivalent SQL: 'SELECT....WHERE NOT (city = "San Diego")'
non_san_diego_stores = Store.objects.exclude(city='San Diego')

# Query with include() and exclude() methods or equivalent SQL: 'SELECT....WHERE STATE='CA' AND NOT (city = "San Diego")'
ca_stores_without_san_diego = Store.objects.filter(state='CA').exclude(city='San Diego')

Listing 8-15.Read multiple records with with all(), filter(), and exclude() methods

Append .Query to View the Actual SQL

有时候，查看 Django 模型查询执行的实际 SQL 是有帮助的，甚至是必要的。您可以通过追加。查询转换为查询，如下面的清单所示:

from coffeehouse.stores.models import Store

import logging
stdlogger = logging.getLogger(__name__)

# Get the Store records with city San Diego
san_diego_stores = Store.objects.filter(city='San Diego')
stdlogger.debug("Query %s" % str(san_diego_stores.query))
# You can also use print(san_diego_stores.query)

正如您在前面的代码片段中看到的，您可以将 SQL 查询输出到 Python logger，或者使用“quick & dirty”print 语句。请注意。query 只适用于输出 QuerySets 的查询，所以它不像 get()方法那样适用于查询——稍后将详细介绍 QuerySets。第五章描述了检查模型查询使用的 SQL 的其他替代方法(如 Django 调试工具栏)，第三章展示了如何在 Django 模板中输出 SQL 查询(如调试上下文处理器 sql_queries 变量)。

Tip

除了单个字段-city = " San Diego "或 state="CA "--all()、filter()和 exclude()方法还可以接受多个字段来生成 and 查询(例如，filter(city="San Diego "，state = " CA ")以获取城市和州匹配的记录)。请参阅“按 SQL 关键字分类的查询”一章的后面部分。

除了all()、filter()和exclude()方法，Django 模型还支持in_bulk()方法。in_bulk()方法旨在高效地读取许多记录，就像bulk_create()方法——在上一节中描述过——用于高效地创建许多记录。

与all()、filter()和exclude()方法相比，in_bulk()方法读取许多记录更有效，因为所有后一种方法都产生一个 QuerySet，而前者产生一个标准的 Python 字典。清单 8-16 展示了in_bulk()方法的使用。

# Import Django model class
from coffeehouse.stores.models import Store

# Query with in_bulk() all
Store.objects.in_bulk()
# Outputs: {1: <Store: Corporate (San Diego,CA)>, 2: <Store: Downtown (San Diego,CA)>, 3: <Store: Uptown (San Diego,CA)>, 4: <Store: Midtown (San Diego,CA)>}

# Compare in_bulk query to all() that produces QuerySet
Store.objects.all()
# Outputs: <QuerySet [<Store: Corporate (San Diego,CA)>, <Store: Downtown (San Diego,CA)>, <Store: Uptown (San Diego,CA)>, <Store: Midtown (San Diego,CA)>]>

# Query to get single Store by id
Store.objects.in_bulk([1])
# Outputs: {1: <Store: Corporate (San Diego,CA)>}

# Query to get multiple Stores by id
Store.objects.in_bulk([2,3])
# Outputs: {2: <Store: Downtown (San Diego,CA)>, 3: <Store: Uptown (San Diego,CA)>}

Listing 8-16.Read multiple records with with in_bulk() method

清单 8-16 中的第一个例子使用不带任何参数的in_bulk()方法来生成一个字典，该字典将存储模型的记录(即，就像all()方法一样)。但是，请注意in_bulk()方法的输出是一个标准的 Python 字典，其中每个键对应于记录的id值。

清单 8-16 中剩余的例子说明了in_bulk()方法如何接受一个值列表来指定应该从数据库中读取哪个记录 id。再次注意，虽然行为类似于filter()或exclude()方法，但是输出是标准的 Python 字典而不是QuerySet数据结构。

既然您已经清楚地了解了可以读取多个模型记录的各种方法，以及一些方法如何产生一个QuerySet而另一些方法不产生，这就引出了一个问题，什么是QuerySet，为什么首先要使用它？因此，在我们进入这一更广泛的部分的下一部分——如何对多个记录进行 CRUD 操作——之前，我们将绕一小段路来探索一下QuerySet数据类型。

理解查询集:惰性计算和缓存

QuerySet数据类型的第一个重要特征在技术上被称为惰性评估。这意味着QuerySet不会立即对数据库执行，它只是等待，直到被评估。换句话说，运行像Store.objects.all()这样的代码片段的行为不会马上涉及到任何数据库活动。清单 8-17 展示了如何在不触发数据库活动的情况下，一个接一个地进行链式查询。

# Import Django model class
from coffeehouse.stores.models import Store

# Query with all() method
stores = Store.objects.all()
# Chain filter() method on query
stores = stores.filter(state='CA')
# Chain exclude() method on query
stores = stores.exclude(city='San Diego')

Listing 8-17.Chained model methods to illustrate concept of QuerySet lazy evaluation

注意清单 8-17 中链接all()、filter()和exclude()方法的三个不同的语句。虽然清单 8-17 调用了三次数据库来获取带有state='CA'的Store记录，并排除了带有city='San Diego'的记录，但是没有任何数据库活动！

这就是QuerySet数据结构的工作原理。那么，对数据类型QuerySet的查询什么时候到达数据库呢？有许多触发器使QuerySet评估并调用实际的数据库调用。表 8-1 说明了各种触发器。

表 8-1。

Django QuerySet evaluation triggers that invoke an actual database call

| 评估触发器 | 描述 | 例子 | | --- | --- | --- | | 循环 | 在 QuerySet 上创建循环会触发数据库调用。 | 对于 Store.objects.all()中的 store: | | 使用“step”参数切片 | 用第三个参数(也称为“step”或“stride”参数)分割 QuerySet 会触发数据库调用。注意:用 1 或 2 个参数分割 Queryset 只会创建另一个 QuerySet。 | #每第 5 条记录的列表，用于前 100 条记录 Store.objects.all()[:100:5] #这不会触发数据库命中，(2 个参数)#记录 50 到 100 Store.objects.all()[49:99] #从第 6 条 Store.objects.all()[5:] #这不会触发数据库命中(1 个参数)Store.objects.all()[0] #第一条记录 | | 酸洗* | 酸洗一个查询集会强制在酸洗之前将所有结果加载到内存中。 | import pickle stores = store . objects . all()pickle _ stores = pickle . dumps(stores) | | repr()方法 | 对 QuerySet 调用 repr()会触发数据库调用。注意:这是为了在 Python 交互式解释器中方便起见，所以您可以立即看到查询结果。 | repr(Store.objects.all()) | | len()方法 | 对 QuerySet 调用 len()会触发数据库调用。注意:如果您只需要记录的数量，使用 Django model count()方法会更有效。 | total _ stores = len(store . objects . all())#注意:count()方法可以更有效地获得总计数 efficient _ total _ stores = store . objects . count() | | list()方法 | 对 QuerySet 调用 list()会触发数据库调用。 | store _ list = list(store . objects . all()) | | 布尔测试(bool()、or 和 or if 语句) | 对 QuerySet 进行布尔测试会触发数据库调用。注意:如果您只想检查记录是否存在，使用 Django model exists()方法会更有效。 | #如果 store . objects . filter(city='San Diego ')，则检查是否有 city = ' San Diego '的商店:#在' San Diego' pass 中有一个商店#注意:exists()方法对于布尔值检查更有效 San _ Diego _ stores = store . objects . exists(city = ' San Diego ') |

Pickling is Python’s standard mechanism for object serialization, a process that converts a Python object into a character stream. The character stream contains all the information necessary to reconstruct the object at a later time. Pickling in the context of Django queries is typically used for heavyweight queries in an attempt to save resources (e.g., make a heavyweight query, pickle it, and on subsequent occasions consult the pickled query). You can consider pickling Django queries a rudimentary form of caching.

既然您已经知道了导致QuerySet调用数据库的触发器，那么让我们来看看另一个重要的QuerySet主题:缓存。

每个QuerySet都包含一个缓存以最小化数据库访问。第一次对一个QuerySet进行评估并进行数据库查询——参见表 8-1 中的评估触发器——Django 将结果保存在QuerySet的缓存中以备后用。

当应用经常需要使用相同的数据时，QuerySet的缓存是最有用的，因为它减少了对数据库的访问。然而，利用QuerySet的缓存伴随着一些与QuerySet的评估相关的微妙之处。一个经验法则是首先评估一个您计划多次使用的QuerySet，然后使用它的数据来利用QuerySet缓存。清单 8-18 中给出的例子最好地解释了这一点。

# Import Django model class
from coffeehouse.stores.models import Store

# CACHE USING SEQUENCE
# Query awaiting evaluation
lazy_stores = Store.objects.all()
# Iteration triggers evaluation and hits database
store_emails = [store.email for store in lazy_stores]
# Uses QuerySet cache from lazy_stores, since lazy_stores is evaluated in previous line  
store_names = [store.name for store in lazy_stores]

# NON-CACHE SEQUENCE
# Iteration triggers evaluation and hits database
heavy_store_emails = [store.email for store in Store.objects.all()]
# Iteration triggers evaluation and hits database again, because it uses another QuerySet ref  
heavy_store_names = [store.name for store in Store.objects.all()]

# CACHE USING SEQUENCE
# Query wrapped as list() for immediate evaluation
stores = list(Store.objects.all())
# Uses QuerySet cache from stores
first_store  = stores[0]
# Uses QuerySet cache from stores
second_store = stores[1]
# Uses QuerySet cache from stores, set() is just used to eliminate duplicates
store_states = set([store.state for store in stores])
# Uses QuerySet cache from stores, set() is just used to eliminate duplicates
store_cities = set([store.city for store in stores])

# NON-CACHE SEQUENCE
# Query awaiting evaluation
all_stores = Store.objects.all()
# list() triggers evaluation and hits database
store_one = list(all_stores[0:1])
# list() triggers evaluation and hits database again, because partially evaluating a QuerySet does not populate the cache
store_one_again = list(all_stores[0:1])

# CACHE USING SEQUENCE
# Query awaiting evaluation
coffee_stores = Store.objects.all()
# Iteration triggers evaluation and hits database
[store for store in coffee_stores]
# Uses QuerySet cache from coffee_stores, because it's evaluated fully in previous line
store_1 = coffee_stores[0]
# Uses QuerySet cache from coffee_stores, because it's already evaluated in full
store_1_again = coffee_stores[0]

Listing 8-18.QuerySet caching behavior

正如您在清单 8-18 中看到的，利用QuerySet的缓存的序列会立即触发对QuerySet的评估，然后使用对评估后的QuerySet的引用来访问缓存的数据。不使用QuerySet缓存的序列要么不断地创建相同的QuerySet语句，要么使每个数据赋值的评估过程延迟。

不符合前面行为的缓存QuerySet的唯一边缘情况是清单 8-18 中的倒数第二个例子。如果通过切片触发了对QuerySet的部分求值(如[0]或[1:5])，缓存不会被填充。因此，为了确保使用了一个QuerySet缓存，您必须评估一个QuerySet，然后对结果进行切片，如清单 8-18 中的最后一个示例所示。

读取性能方法:defer()、only()、values()、values_list()、iterator()、exists()和 none()

虽然数据结构通过集成惰性评估和缓存机制向处理多个数据记录迈进了一步，但它们并没有涵盖处理大型数据查询所需的全部性能。

大型数据查询面临的一个常见性能问题是读取不必要的记录字段。尽管在大多数情况下，有选择地从数据库记录中读取哪些字段可能是事后才想到的，但是对于在具有多个字段的 Django 模型上进行的查询来说，这可能会产生重要的影响。

读取模型记录时提高性能的第一种方法是defer()和only()方法，这两种方法都是为了限定在查询中读取哪些字段。defer()和only()方法分别接受要延迟或加载的字段列表，根据您想要实现的目标，它们是互补的。例如，如果您想延迟加载大部分的模型字段，用only()指定加载哪些字段会更简单，如果您想延迟加载模型中的一个或几个字段，您可以在defer()方法中指定字段。清单 8-19 展示了defer()和only()方法的使用。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Item

# Item names on the breakfast menu
breakfast_items = Item.objects.filter(menu__name='Breakfast').only('name')

# All Store records with no email
all_stores = Store.objects.defer('email').all()

# Confirm loaded fields on overall query
breakfast_items.query.get_loaded_field_names()
# Outputs: {<class 'coffeehouse.items.models.Item'>: {'id', 'name'}}
all_stores.query.get_loaded_field_names()
# Outputs: {<class 'coffeehouse.stores.models.Store'>: {'id', 'address', 'state', 'city', 'name'}}

# Confirm deferred fields on individual model records breakfast_items[0].get_deferred_fields()
# Outputs: {'calories', 'stock', 'price', 'menu_id', 'size', 'description'}
all_stores[1].get_deferred_fields()
# Outputs: {'email'}

# Access deferred fields, note each call on a deferred field implies a database hit
breakfast_items[0].price
breakfast_items[0].size
all_stores[1].email

Listing 8-19.Read performance with defer() and only() to selectively read record fields

正如您在清单 8-19 中看到的，defer()和only()方法可以在查询的开始或结束链接到一个模型管理器(即objects)，也可以与其他方法如all()和filter()结合使用。此外，请注意这两种方法如何接受要延迟或加载的字段列表。

为了验证哪些模型字段已经被延迟或加载，清单 8-19 展示了两种选择。第一种技术包括调用查询语句的查询引用上的get_loaded_field_names()来获取已加载字段的列表。第二种技术包括在一个模型实例上调用get_deferred_fields()方法来获得一个延迟字段列表。

那么，如何获得延迟字段呢？简单，你打电话给他们。在清单 8-18 的末尾，请注意尽管breakfast_items表示一个只加载name字段的查询，但还是调用了一个函数来获取price和size字段的值。类似地，清单 8-19 中的all_stores引用表示推迟email字段的查询；然而，您可以通过调用它来获取记录的email字段值。虽然最后一种技术需要额外的数据库命中来获得延迟的字段，但是它也说明了即使它们被延迟，获得记录的整个字段是多么容易。

values()和values_list()方法提供了另一种方法来分隔查询获取的字段。与产生模型实例的QuerySet的defer()和only()方法不同，values()和values_list()方法产生由普通字典、元组或列表组成的QuerySet实例。这具有不创建成熟模型实例的性能优势，尽管这也具有不能访问成熟模型实例的缺点。

values()和values_list()方法接受字段列表作为查询的一部分进行加载，这个过程如清单 8-20 所示。

Tip

您可以使用不带任何字段参数的 values()和 values_list()方法，以普通字典、元组或列表的形式生成完整的模型记录。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Item

# Item names on the breakfast menu
breakfast_items = Item.objects.filter(menu__name='Breakfast').values('name')
print(breakfast_items)
# Outputs: <QuerySet [{'name': 'Whole-Grain Oatmeal'}, {'name': 'Bacon, Egg & Cheese Biscuit'}]>

# All Store records with no email
all_stores = Store.objects.values_list('email','name','city').all()
print(all_stores)
# Outputs: <QuerySet [('corporate@coffeehouse.com', 'Corporate', 'San Diego'), ('downtown@coffeehouse.com', 'Downtown', 'San Diego'), ('uptown@coffeehouse.com', 'Uptown', 'San Diego'), ('midtown@coffeehouse.com', 'Midtown', 'San Diego')]>

all_stores_flat = Store.objects.values_list('email',flat=True).all()
print(all_stores_flat)
# Outputs: <QuerySet ['corporate@coffeehouse.com', 'downtown@coffeehouse.com', 'midtown@coffeehouse.com', 'uptown@coffeehouse.com']>

# It isn't possible to access undeclared model fields with values() and values_list()
breakfast_items[0].price #ERROR
# Outputs AttributeError: 'dict' object has no attribute 'price'

Listing 8-20.Read performance with values() and values_list() to selectively read record fields

清单 8-20 中的第一个变体生成了一个带有name字段的条目QuerySet，正如您所看到的，它生成了一个只有name字段和值的字典列表。接下来，使用values_list()方法查询所有Store模型的email、name和city字段。注意，与values()方法不同，values_list()方法以元组的形式产生了一个更紧凑的结构。在清单 8-20 中，您还可以看到values_list()方法接受可选的flat=True参数来将结果元组展平为一个普通列表。

最后，在清单 8-20 的末尾，您可以看到，当使用values()和values_list()方法时，不可能像使用defer()和only()方法那样，仅仅通过调用它们来获得未声明的字段。这种行为是由于values()和values_list()方法产生的淡化QuerySet，它们不是成熟的模型对象。

iterator()方法是 Django 模型中另一个可用的选项，它在QuerySet的结果上创建一个迭代器。iterator()方法对于打算使用一次的大型查询是理想的，因为这降低了存储数据所需的内存，这是所有 Python 迭代器的固有属性。清单 8-21 展示了一个使用iterator()方法的查询，附录 A 描述了 Python 迭代器背后的核心概念。

from coffeehouse.stores.models import Store

# All Store with iterator()
stores_on_iterator = Store.objects.all().iterator()

print(stores_on_iterator)
# Outputs: <generator object __iter__ at 0x7f2864db8fc0>

# Advance through iterator with __next__()
stores_on_iterator.__next__()
# Outputs: <Store: Corporate (San Diego,CA)>

stores_on_iterator.__next__()
# Outputs: <Store: Downtown (San Diego,CA)>

# Check if Store object with id=5 exists
Store.objects.filter(id=5).exists()
# Outputs: False

# Create empty QuerySet on Store model
Store.objects.none()
# Outputs: <QuerySet []>

Listing 8-21.Read performance with iterator(), exists(), and none()

另一种 Django 模型读取性能技术是exists()方法，如清单 8-21 所示，用于验证查询是否返回数据。虽然exists()方法对数据库执行查询，但是与标准查询相比，exists()使用的查询是一个简化版本，此外exists()方法返回一个布尔值 True 或 False，而不是一个完整的 QuerySet。这使得exists()方法成为对条件进行操作的查询的好选择，在这种情况下，只需要验证模型记录是否存在，而实际的记录数据是不必要的。

最后，Django 模型none()方法——在清单 8-21 的末尾说明——用于生成一个空的QuerySet,特别是一个名为EmptyQuerySet的子类。none()方法对于您故意需要分配一个空模型QuerySet的情况很有帮助，例如与 Django 模型表单或 Django 模板相关的边缘情况，它们以某种方式期望一个QuerySet实例。在这种情况下，有必要创建一个哑元QuerySet，而不是低效地创建返回数据的QuerySet并删除其内容。

正如您在本小节中了解到的，除了QuerySet数据结构，Django 还提供了许多专门设计的方法来有效地读取与 Django 模型相关的大量或少量记录。

Tip

请记住，上一节中的 in_bulk()方法也提供了优于基本的 all()、filter()和 exclude()方法的读取性能。

用 Update()或 select_for_update()更新多条记录

在单记录 CRUD 操作一节中，您探索了如何用update()方法更新单个记录；同样的方法可以处理多个记录的更新。清单 8-22 说明了这一过程。

from coffeehouse.stores.models import Store

Store.objects.all().update(email="contact@coffeehouse.com")

from coffeehouse.items.models import Item
from django.db.models import F

Item.objects.all().update(stock=F('stock') +100)

Listing 8-22.Update multiple records with the update() method

清单 8-22 中的第一个例子使用update()方法更新所有的Store记录，并将它们的 email 值设置为contact@coffeehouse.com。第二个例子使用 Django F表达式和update()方法来更新所有Drink记录，并将它们的stock值设置为当前股票值加 100。Django F表达式允许您在一个查询中引用模型字段，这对于在单个操作中执行更新是必要的。

虽然update()方法保证所有事情都在一个操作中完成以避免竞争情况，但是在某些情况下update()方法可能不足以完成复杂的更新。提供另一种更新多条记录的方法是select_for_update()方法，它锁定给定查询中的行，直到更新被标记为完成。清单 8-23 展示了select_for_update()方法的一个例子。

Select_For_Update() Support is Database Dependent

实际上，Django select_for_update()方法是基于 SQL 的 SELECT…FOR UPDATE 语法，并非所有数据库都支持该语法。Postgres、Oracle 和 MySQL 数据库支持此功能，但 SQLite 不支持。

此外，还有一个特殊的参数 nowait(例如，select_for_update(nowait=True)使查询不阻塞)。默认情况下，如果另一个事务获取了某个选定行的锁，select_for_update()查询将一直阻塞，直到锁被释放。如果使用 nowait，这将允许查询立即运行，如果另一个事务已经获取了冲突锁，则在计算 QuerySet 时会引发 DatabaseError。但是要注意，MySQL 不支持 nowait 参数，如果和 MySQL 一起使用，Django 会抛出 DatabaseError。

# Import Django model class
from coffeehouse.stores.models import Store
from django.db import transaction

# Trigger atomic transaction so loop is executed in a single transaction
with transaction.atomic():
    store_list = Store.objects.select_for_update().filter(state='CA')
    # Loop over each store to update and invoke save() on each entry
    for store in store_list:
        # Add complex update logic here for each store
        # save() method called on each member to update
        store.save()

# Method decorated with @transaction.atomic to ensure logic is executed in single transaction
@transaction.atomic
def bulk_store_updae(store_list):
    store_list = Store.objects.select_for_update().exclude(state='CA')
    # Loop over each store and invoke save() on each entry
    for store in store_list:
        # Add complex update logic here for each store
        # save() method called on each member to update
        store.save()        

# Call bulk_store_update to update store records
bulk_store_update(store_list_to_update)

Listing 8-23.Update multiple records with a Django model with the select_for_update() method

清单 8-23 显示了select_for_update()的两种变体，一种使用显式事务，另一种修饰方法以在事务内限定其范围。两种变体使用相同的逻辑；他们首先用select_for_update()创建一个查询，然后遍历结果来更新每条记录，并使用save()来更新单个记录。通过这种方式，查询所涉及的行保持锁定，直到事务完成。

请注意，在使用select_for_update()时，绝对有必要使用清单 8-23 中描述的任何技术来使用事务。如果在支持的数据库中运行select_for_update()方法，并且没有使用清单 8-23 中所示的事务——保持 Django 的默认自动提交模式——Django 会抛出一个TransactionManagementError错误，因为行不能作为一个组被锁定。在不支持的数据库中使用select_for_update方法没有任何效果(也就是说，您不会看到错误)。

用 Delete()删除多条记录

要删除多条记录，可以使用delete()方法，并将其附加到查询中。清单 8-24 说明了这个过程。

from coffeehouse.stores.models import Store

Store.objects.filter(city='San Diego').delete()

Listing 8-24.Delete model records with the delete() method

清单 8-24 中的例子使用delete()方法删除带有city='San Diego'的Store记录。

跨 Django 模型的 CRUD 关系记录

在前一章中，您学习了 Django 模型关系如何通过特殊的模型数据类型(例如，ForgeignKey、ManyToManyField和OneToOne)帮助您改进数据维护。在 Django 模型关系上进行的 CRUD 操作也有一个特殊的语法。

尽管前面章节中的相同语法适用于对 Django 模型关系数据类型进行的直接操作，但是您也可以对定义关系数据类型的 Django 模型进行相反的操作。

Note

直接 Django 模型操作通过一个 Manager 类来操作，反向操作 Django 模型操作通过一个 RelatedManager 类来完成。

一对多 CRUD 操作

通过ForgeignKey模型数据类型建立一对多的关系。清单 8-25 显示了两个模型之间的一对多关系，包括对相关模型的一系列直接查询操作。

class Menu(models.Model):
    name = models.CharField(max_length=30)

class Item(models.Model):
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)

# Get the Menu of a given Item
Item.objects.get(name='Whole-Grain Oatmeal').menu.id

# Get the Menu id of a given Item
Item.objects.get(name='Whole-Grain Oatmeal').menu.name

# Get Item elements that belong to the Menu with name 'Drinks'
Item.objects.filter(menu__name='Drinks')

Listing 8-25.One to many ForeignKey direct query read operations

在清单 8-25 中，您可以看到Item模型声明了与Menu模型的ForeignKey关系。一旦一个Item模型以这种方式与一个Menu模型相关联，就有可能使用 Python 的点符号访问一个Menu模型，如清单 8-25 所示(例如，menu.id和menu.name获得Item引用上相关Menu实例的id和name)。请注意，在清单 8-25 中，还可以创建一个查询，使用__(两个下划线)(也称为“跟随符号”)来指示相关模型中的一个字段，从而引用相关模型。

清单 8-25 中的操作使用与非关系模型相同的查询语法，因为这些操作是与具有关系数据类型的模型分开创建的。然而，Django 也支持在没有关系数据类型的模型上启动的 CRUD 操作。

清单 8-26 展示了通过Menu模型的实例对其相关的Item模型进行的一系列 CRUD 操作。这些任务被称为反向操作，因为保持关系的模型——ForeignKey——是反向实现的。

from coffeehouse.items.models import Menu, Item

breakfast_menu = Menu.objects.get(name='Breakfast')

# Fetch all Item records for the Menu
breakfast_menu.item_set.all()

# Get the total Item count for the Menu
breakfast_menu.item_set.count()

# Fetch Item records that match a filter for the Menu
breakfast_menu.item_set.filter(name__startswith='Whole')

Listing 8-26.One to many ForeignKey reverse query read operations with _set syntax

清单 8-26 从一个针对Menu记录的标准 Django 查询开始。尽管Menu模型缺少与Item模型的显式关系，但是Item模型声明了与Menu模型的关系，Django 使用<one_model>.<many_model>_set语法创建了一个反向访问模式。

因此，从一个Menu记录中，您可以看到使用menu_record.item_set.all()语法可以获得与一个Menu记录有关系的所有Item记录。类似地，如清单 8-26 中的最后一个示例所示，可以生成一个查询，使用相同的_set语法过滤一组从Menu记录中分离出来的Item记录。

Tip

您可以使用 related_name 和 related_query_name 模型字段选项将 _set 语法更改为更明确的名称，或者完全禁用此行为。请参阅上一章“反转关系选项”小节中的“关系模型数据类型的选项”一节

正如反向的_set语法用于执行从没有显式关系字段的模型到有关系字段的模型的读取操作，也可以使用相同的_set语法来执行其他数据库操作(例如，创建、更新、删除)，如清单 8-27 所示。

from coffeehouse.items.models import Menu, Item

breakfast_menu = Menu.objects.get(name='Breakfast')

# Create an Item directly on the Menu
# NOTE: Django also supports the get_or_create() and update_or_create() operations
breakfast_menu.item_set.create(name='Bacon, Egg & Cheese Biscuit',description='A fresh buttermilk biscuit...',calories=450)

# Create an Item separately and then add it to the Menu
new_menu_item = Item(name='Grilled Cheese',description='Flat bread or whole wheat ...',calories=500)
# Add item to menu using add()
# NOTE: bulk=False is necessary for new_menu_item to be saved by the Item model manager first
# it isn't possible to call new_menu_item.save() directly because it lacks a menu instance
breakfast_menu.item_set.add(new_menu_item,bulk=False)

# Create copy of breakfast items for later
breakfast_items = [bi for bi in breakfast_menu.item_set.all()]

# Clear menu references from Item elements (i.e. reset the Item elements menu field to null)
# NOTE: This requires the ForeignKey definition to have null=True
# (e.g. models.ForeignKey(Menu, null=True)) so the key is allowed to be turned null
# otherwise the error 'RelatedManager' object has no attribute 'clear' is thrown
breakfast_menu.item_set.clear()

# Verify Item count is now 0
breakfast_menu.item_set.count()
0

# Reassign Item set from copy of breakfast items
breakfast_menu.item_set.set(breakfast_items)

# Verify Item count is now back to original count
breakfast_menu.item_set.count()
3

# Clear menu reference from single Item element (i.e. reset an Item element menu field to null)
# NOTE: This requires the ForeignKey definition to have null=True
# (e.g. models.ForeignKey(Menu, null=True)) so the key is allowed to be turned null
# otherwise the error 'RelatedManager' object has no attribute 'remove' is thrown
item_grilled_cheese = Item.objects.get(name='Grilled Cheese')
breakfast_menu.item_set.remove(item_grilled_cheese)

# Delete the Menu element along with its associated Item elements
# NOTE: This requires the ForeignKey definition to have blank=True and on_delete=models.CASCADE (e.g. models.ForeignKey(Menu, blank=True, on_delete=models.CASCADE))
breakfast_menu.delete()

Listing 8-27.One to many ForeignKey reverse query create, update, delete operations with _set syntax

在清单 8-27 中，您可以看到在获得对Menu记录的引用后，您可以使用create()方法直接在_set引用上生成一个Item记录。清单 8-27 还展示了如何首先生成一个Item记录，然后使用同样适用于_set引用的add()方法将它链接到一个Menu记录。

Note

add()、create()、remove()、clear()和 set()关系方法都会立即对所有类型的相关字段应用数据库更改。这意味着不需要在关系的任何一端调用 save()。

接下来，清单 8-27 是clear()关系方法的一个例子。clear()方法用于分离关系，在清单 8-27 的情况下，它将与名为'Breakfast'到NULL的Menu相关联的所有Item记录的Menu引用设置为NULL(即，它不删除任何数据，只是删除关系引用)。值得一提的是，为了调用clear()方法，必须用null=True选项声明一个模型字段，以便将关系引用设置为NULL。

清单 8-27 中的add()关系方法用于关联一个关系的实例列表。在清单 8-27 的情况下，它恢复了由同一清单中的clear()方法产生的逻辑。add()关系方法的一个重要方面是，它在幕后使用模型的标准update()方法来添加关系，这反过来要求在创建关系之前预先保存两个模型记录。您可以通过使用清单 8-27 中使用的bulk=False来绕过这一限制，将保存操作委托给相关的管理器，并在不事先保存相关对象的情况下创建关系。

remove()关系方法的工作方式类似于clear()关系方法，但是它被设计成以一种精细的方式分离关系。在清单 8-27 的情况下，remove()方法将名为'Grilled Cheese'的Item记录的Menu引用设置为NULL(也就是说，它不会删除任何数据，只是删除关系引用)。类似于clear()关系方法，必须用null=True选项声明模型字段，以便将关系引用设置为NULL。

最后，清单 8-27 展示了在一个有关系的模型实例上调用delete()方法是如何删除调用它的实例及其相关的模型实例的。在清单 8-27 的情况下，breakfast_menu.delete()删除名为'Breakfast'的Menu和所有链接到它的Item实例。与clear()和remove()关系方法类似，delete()关系方法需要使用on_delete=models.CASCADE选项声明模型字段，以便自动删除相关模型。

Tip

有关其他 on_delete 选项，请参阅上一章“数据完整性选项”小节中的“关系模型数据类型选项”一节。

多对多 CRUD 操作

与一对多关系类似，多对多关系也支持直接和反向 CRUD 操作。清单 8-28 显示了两个模型之间的多对多关系，包括对相关模型的一系列直接查询操作。

class Amenity(models.Model):
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)

class Store(models.Model):
    name = models.CharField(max_length=30)    
    address = models.CharField(max_length=30,unique=True)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    email = models.EmailField()
    amenities = models.ManyToManyField(Amenity,blank=True)

# Get the Amenity elements of a given Store
Store.objects.get(name='Downtown').amenities.all()

# Fetch store named Midtown
midtown_store = Store.objects.get(name='Midtown')

# Create and add Amenity element to Store
midtown_store.amenities.create(name='Laptop Lock',description='Ask our baristas...')

# Get all Store elements that have amenity id=3
Store.objects.filter(amenities__id=3)

Listing 8-28.Many to many ManyToManyField direct query read operations

在清单 8-28 中，您可以看到Store模型声明了与Amenity模型的ManyToManyField关系。一旦一个Store模型以这种方式与一个Amenity模型相关联，就可以使用 Python 的点符号访问Amenity模型，如清单 8-28 所示(例如，amenities.all()获取Store引用上所有相关的Amenity实例)。此外，清单 8-28 还展示了如何使用create()方法直接在模型amenities引用上创建Amenity实例。还要注意在清单 8-28 中，如何使用__(两个下划线)(也称为“跟随符号”)来创建引用相关模型的查询，以指示相关模型中的字段。

清单 8-28 中的操作使用与非关系模型相同的查询语法，因为这些操作是与具有关系数据类型的模型分开创建的。然而，Django 也支持在没有关系数据类型的模型上启动的 CRUD 操作。

清单 8-29 展示了通过Amenity模型的实例对其相关的Store模型进行的一系列 CRUD 操作。这些任务被称为反向操作，因为保持关系的模型——ManyToManyField——是反向实现的。

from coffeehouse.stores.models import Store, Amenity

wifi_amenity = Amenity.objects.get(name='WiFi')

# Fetch all Store records with Wifi Amenity
wifi_amenity.store_set.all()

# Get the total Store count for the Wifi Amenity
wifi_amenity.store_set.count()

# Fetch Store records that match a filter with the Wifi Amenity
wifi_amenity.store_set.filter(city__startswith='San Diego')

# Create a Store directly with the Wifi Amenity
# NOTE: Django also supports the get_or_create() and update_or_create() operations
wifi_amenity.store_set.create(name='Uptown',address='1240 University Ave...')

# Create a Store separately and then add the Wifi Amenity to it
new_store = Store(name='Midtown',address='844 W Washington St...')
new_store.save()
wifi_amenity.store_set.add(new_store)

# Create copy of breakfast items for later
wifi_stores = [ws for ws in wifi_amenity.store_set.all()]

# Clear all the Wifi amenity records in the junction table for all Store elements
wifi_amenity.store_set.clear()

# Verify Wifi count is now 0
wifi_amenity.store_set.count()
0

# Reassign Wifi set from copy of Store elements
wifi_amenity.store_set.set(wifi_stores)

# Verify Item count is now back to original count
wifi_amenity.store_set.count()
6

# Reassign Store set from copy of wifi stores
wifi_amenity.store_set.set(wifi_stores)

# Clear the Wifi amenity record from the junction table for a certain Store element
store_to_remove_amenity = Store.objects.get(name__startswith='844 W Washington St')
wifi_amenity.store_set.remove(store_to_remove_amenity)

# Delete the Wifi amenity element along with its associated junction table records for Store elements
wifi_amenity.delete()

Listing 8-29.Many to many ManyToManyField reverse query create, read, update, and delete operations with _set syntax

在清单 8-29 中，您可以看到多对多 Django 模型反向查询操作的各种例子。请注意与清单 8-26 和 8-27 中所示的一对多关系 CRUD 操作示例的相似之处。一对多和多对多关系中调用关系方法的显著区别如下:

当应用于多对多模型时，add()和remove()关系方法分别使用模型的标准bulk_create()和delete()方法来添加和移除关系。这反过来意味着模型的标准save()方法没有被调用；因此，如果任一模型的save()方法执行定制逻辑，它将永远不会与add()和remove()关系方法一起运行。如果您想在创建或删除多对多关系时执行自定义逻辑，请使用m2m_changed信号。更多详情，请参见上一章“模型信号”一节。
如果为多对多模型关系声明一个自定义连接表，则add()、create()、remove()和set()关系方法将被禁用。有关如何使用自定义连接表，请参阅上一章“数据库选项”小节中的“关系模型数据类型的选项”一节。

一对一 CRUD 操作

Django 一对一关系上的 CRUD 操作比前面的关系 CRUD 操作简单得多，因为一对一关系本质上要简单得多。在前一章中，您学习了一对一关系如何类似于继承层次结构，其中一个模型声明通用字段，另一个(相关的)模型继承前者的字段并添加更多的专用字段。

这意味着一对一的关系只有直接的查询操作，因为逆向操作没有意义，因为模型遵循层次结构。清单 8-30 显示了两个模型之间的一对多关系，包括对相关模型的一系列查询操作。

from coffeehouse.items.models import Item
# See Listing 8-25 for Item model definition

class Drink(models.Model):
    item = models.OneToOneField(Item,on_delete=models.CASCADE,primary_key=True)
    caffeine = models.IntegerField()

# Get Item instance named Mocha
mocha_item = Item.objects.get(name='Mocha')

# Access the Drink element and its fields through its base Item element
mocha_item.drink.caffeine

# Get Drink objects through Item with caffeine field less than 200
Item.objects.filter(drink__caffeine__lt=200)

# Delete the Item element and its associated Drink record
# NOTE: This deletes the associated Drink record due to the on_delete=models.CASCADE in the OneToOneField definition
mocha_item.delete()

# Query a Drink through an Item property
Drink.objects.get(item__name='Latte')

Listing 8-30.One to one OneToOneField query

operations

正如您在清单 8-30 中看到的，一对一 Django 模型关系的操作比前一个例子简单得多，尽管查询操作仍然使用相同的点符号在关系模型和字段中移动，以及使用__(两个下划线)(也称为“跟随符号”)在相关模型上按字段执行查询。

读取性能关系方法:select_related()和 prefetch_related()

在这些最后的 Django 模型关系 CRUD 操作部分——清单 8-25 到 8-30——您了解了通过关系字段从一个模型到另一个模型访问其他字段是多么容易。例如，对于一个Item和Menu模型之间的一对多关系，您可以使用语法item.menu.name访问一个Menu记录上的 name 字段；类似地，对于一个Store和Amenity模型之间的多对多关系，您可以使用语法store.amenities.all()[0].name访问一个Amenity记录上的name字段。

虽然这种点符号提供了一种轻松访问相关模型中的字段的方法——类似于defer()和load()方法轻松访问延迟数据的方式——但这种技术也会产生额外的数据库命中，这可以通过select_related()和prefetch_related()方法来防止。

selected_related()方法接受应该作为初始查询的一部分读取的相关模型字段参数。尽管这创建了一个更复杂的初始查询，但它避免了对相关模型字段的额外数据库命中。清单 8-31 展示了一个select_related()方法的例子，以及一个放弃使用它的查询。

from coffeehouse.items.models import Item
# See Listing 8-25 for Item and Menu model definitions

# Inefficient access to related model
for item in Item.objects.all():
     item.menu # Each call to menu creates an additional database hit

# Efficient access to related model with selected_related()
for item in Item.objects.select_related('menu').all():
     item.menu # All menu data references have been fetched on initial query

# Raw SQL query with select_related
print(Item.objects.select_related('menu').all().query)
SELECT "items_item"."id", "items_item"."menu_id", "items_item"."name", "items_item"."description", "items_item"."size", "items_item"."calories", "items_item"."price", "items_item"."stock", "items_menu"."id", "items_menu"."name" FROM "items_item" LEFT OUTER JOIN "items_menu" ON ("items_item"."menu_id" = "items_menu"."id")

# Raw SQL query without select_related
print(Item.objects.all().query)
SELECT "items_item"."id", "items_item"."menu_id", "items_item"."name", "items_item"."description", "items_item"."size", "items_item"."calories", "items_item"."price", "items_item"."stock" FROM "items_item"

Listing 8-31.Django model select_related syntax and generated SQL

在清单 8-31 中，您可以看到有两种方法可以访问所有Item模型记录的相关Menu模型。第一个变体使用Item.objects.all()语法来获得所有的Item模型记录，然后直接访问menu字段来获得对相应的Menu记录的访问。这种方法的问题是，获取每个Item记录的Menu记录会产生额外的数据库命中，所以如果您有 100 个Item记录，这意味着额外的 100 个数据库命中！

清单 8-31 中的第二个变化将select_related('menu')方法添加到查询中，确保每个Item记录的相关Menu记录也作为初始查询的一部分被获取。这种技术保证所有关系数据都在一个查询中提取。

在清单 8-31 的下半部分，您可以看到使用和省略select_related()方法时生成的原始 SQL。当使用select_related()时，使用更复杂的LEFT OUTER JOIN查询来确保在一个步骤中读取所有相关数据。

prefetch_related()方法解决了与select_related()方法相同的问题，但是使用了不同的技术。正如您在清单 8-31 中看到的，select_related()方法通过数据库连接的方式在单个查询中获取相关的模型数据；然而，一旦数据在 Python 中，prefetch_related()方法就执行它的连接逻辑。

虽然数据库连接解决了单个查询中的多查询问题，但它是一个重量级操作，通常很少使用。因此，select_related()方法仅限于单值关系(即ForeignKey和OneToOneField模型字段)，因为与连接表相关的多值关系(即ManyToManyField)会在单个查询中产生大量数据。

当查询使用prefetch_related()方法时，Django 首先执行主查询，然后为在prefetch_related()方法中声明的所有相关模型生成QuerySet实例。所有这些都发生在一个步骤中，所以当您试图访问相关的模型引用时，Django 已经有了一个预先填充的相关结果的缓存，它以 Python 数据结构的形式连接这些结果以产生最终的结果。清单 8-32 展示了prefetch_related()方法的一个例子。

from coffeehouse.items.models import Item
from coffeehouse.stores.models import Store
# See Listing 8-25 for Item  model definitions
# See Listing 8-28 for Store  model definitions

# Efficient access to related model with prefetch_related()
for item in Item.objects.prefetch_related('menu').all():
     item.menu # All menu data references have been fetched on initial query

# Efficient access to many to many related model with prefetch_related()
# NOTE Store.objects.select_related('amenities').all() is invalid due to many to many model
for store in Store.objects.prefetch_related('amenities').all():
     store.amenities.all()

# Raw SQL query with prefetch_related
print(Item.objects.prefetch_related('menu').all().query)
SELECT "items_item"."id", "items_item"."menu_id", "items_item"."name", "items_item"."description", "items_item"."size", "items_item"."calories", "items_item"."price", "items_item"."stock" FROM "items_item"

# Raw SQL query with prefetch_related
print(Store.objects.prefetch_related('amenities').all().query)
SELECT "stores_store"."id", "stores_store"."name", "stores_store"."address", "stores_store"."city", "stores_store"."state", "stores_store"."email" FROM "stores_store"

Listing 8-32.Django model prefetch_related syntax and generated SQL

清单 8-32 中的第一个查询相当于清单 8-31 中的查询，它为所有Item模型记录获取相关的Menu模型，除了它使用了prefetch_related()方法。清单 8-32 中的第二个查询是在多对多模型关系上进行的，使用prefetch_related()方法获取所有Store模型记录的相关amenities模型实例。值得一提的是，最后一个查询只可能使用prefetch_related()方法，因为它是多对多模型关系。

最后，在清单 8-32 的下半部分，您可以确认使用prefetch_related()方法的查询生成的原始 SQL 显示为普通 SQL 查询(即，无连接)。在这种情况下，Django/Python 本身负责管理和创建高效读取相关模型数据所需的额外的QuerySet数据结构。

Tip

可以使用 prefetch()对象进一步优化 prefetch_related()方法，以进一步过滤预取操作或包含使用 selected_related。 ¹

通过 SQL 关键字对查询进行建模

在前面的章节中，您学习了如何使用 Django 模型方法查询单个、多个和相关的记录。然而，匹配过程大部分是在精确值的基础上完成的。例如，查询将id=1转换为 SQL WHERE ID=1的Store记录，或者查询将state="CA"转换为 SQL WHERE STATE="CA"的所有Store记录。

实际上，精确的 SQL 匹配模式与大多数需要更细粒度 SQL 查询的真实场景相差甚远。在接下来的小节中，您将了解按 SQL 关键字分类的各种 Django 模型查询选项，通过这种方式，您可以使用更广为人知的 SQL 关键字作为标识符，轻松识别所需的 Django 语法。

WHERE 查询:Django 字段查找

SQL WHERE 关键字是关系数据库查询中最常用的关键字之一，因为它用于通过字段值来限定查询中的记录数量。到目前为止，您主要使用 SQL WHERE 关键字来创建对精确值的查询(例如，WHERE ID=1)；然而，SQL WHERE 关键字还有许多其他变体。

在 Django 模型中，SQL WHERE 关键字的变体通过字段查找得到支持，字段查找是使用__(两个下划线)(也称为“跟随符号”)附加到字段过滤器的关键字。

The PK Lookup Shortcut

Django 查询依靠模型字段名称来分类查询。例如，Django 查询中的 SQL WHERE ID=1 语句写成…(id=1)，Django 查询中的 SQL WHERE NAME="CA "语句写成…(state="CA ")。

此外，Django 模型还可以使用 pk 快捷方式——其中 PK =“primary key”——对模型的主键执行查询。默认情况下，Django 模型的 id 字段是主键，因此 id 字段和 pk 快捷方式查询被认为是等效的(例如 store . objects . get(id = 1)store . objects . get(PK = 1))。

当模型定义了自定义主键模型字段时，具有 pk 查找的查询与具有 id 字段的查询只有不同的含义。

=/等于和！=/不相等查询:exact，iexact

等式或=查询是 Django 模型中使用的默认 WHERE 行为。等式搜索有两种语法变体；一个是简写版本，另一个使用exact字段查找，清单 8-33 展示了这两种方法。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Item

# Get the Store object with id=1
Store.objects.get(id__exact=1)

# Get the Store object with id=1 (Short-handed version)
Store.objects.get(id=1)

# Get the Drink objects with name="Mocha"
Item.objects.filter(name__exact="Mocha")

# Get the Drink objects with name="Mocha" (Short-handed version)
Item.objects.filter(name="Mocha")

Listing 8-33.Django equality = or EQUAL query

正如您在清单 8-33 中看到的，您可以使用exact字段查找来明确限定查询，或者使用简写语法<field>=<value>。因为 exact WHERE 查询是最常见的，Django 意味着默认的exact搜索。

Tip

您可以使用 iexact 字段查找进行不区分大小写的相等查询(例如，匹配“if”、“If”、“iF”或“IF”)。详情参见 LIKE 和 ILIKE 查询部分。

不平等还是！=搜索还有两种语法变体，如清单 8-34 所示。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Item
from django.db.models import Q

# Get the Store records that don't have state 'CA'
Store.objects.exclude(state='CA')

# Get the Store records that don't have state 'CA', using Q
Store.objects.filter(∼Q(state="CA"))

# Get the Item records and exclude items that have more than 100 calories
Item.objects.exclude(calories__gt=100)

# Get the Item records and exclude those with 100 or more calories, using Q
Item.objects.filter(∼Q(calories__gt=100))

Listing 8-34.Django inequality != or NOT EQUAL query with exclude() and Q objects

正如您在清单 8-34 中看到的，一种语法变体使用exclude()方法来排除匹配给定语句的对象。另一种方法是使用 Django Q对象来否定查询。在清单 8-34 中，您可以看到将状态值与CA匹配的Q对象Q(state="CA")，但是因为Q对象前面有∼(波浪符号)，所以它是一个否定模式(即，匹配非CA的状态值)。

exclude()和Q对象语法产生相同的结果。Q对象主要用于更复杂的查询，但是在这种情况下，一个被否定的Q对象就像exclude()一样工作。

和查询

要使用 AND 语句创建 SQL WHERE 查询，您可以向一个查询添加多个语句或使用Q对象，如清单 8-35 所示。

from coffeehouse.stores.models import Store
from django.db.models import Q

# Get the Store records that have state 'CA' AND city 'San Diego'
Store.objects.filter(state='CA', city='San Diego')

# Get the Store records that have state 'CA' AND city not 'San Diego'
Store.objects.filter(Q(state='CA') & ∼Q(city='San Diego'))

Listing 8-35.Django AND query

清单 8-35 中的第一个例子将多个字段值添加到filter()方法中，以产生一个WHERE <field_1> AND <field_2>语句。清单 8-35 中的第二个例子也使用了filter()方法，但是使用了两个Q对象通过&操作符与AND语句(即WHERE <field_1> AND NOT <field2>)产生一个否定。

Tip

例如，如果您正在寻找一个比清单 8-35 中的查询更广泛的 AND 查询，获取状态为‘CA’的商店对象和状态为‘AZ’的商店对象，查看 or 查询或 in 查询。

如果您希望合并两个查询，例如 query1 和 query 2，请参阅本章后面的合并查询部分。

OR 查询:Q()对象

要用 OR 语句创建 SQL WHERE 查询，您可以使用Q对象，如清单 8-36 所示。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Item
from django.db.models import Q

# Get the Store records that have state 'CA' OR state='AZ'
Store.objects.filter(Q(state='CA') | Q(state='AZ'))

# Get the Item records with name "Mocha" or "Latte"
Item.objects.filter(Q(name="Mocha") | Q(name='Latte'))

Listing 8-36.Django OR query

清单 8-36 中的两个例子都在Q对象之间使用|(管道)操作符来产生一个WHERE <field1> OR <field2>语句，类似于&操作符如何用于 AND 条件。

IS 和 IS NOT 查询:isnull

SQL IS 和 IS NOT 语句通常在涉及空值的查询中与 WHERE 一起使用。根据数据库品牌的不同，SQL IS 和 IS NOT 也可以用于布尔查询。要创建带有 IS 或 NOT 语句的 SQL WHERE 查询，您可以使用带有等价测试的 Python None数据类型或isnull字段查找，如清单 8-37 所示。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Drink
from django.db.models import Q

# Get the Store records that have email NULL
Store.objects.filter(email=None)

# Get the Store records that have email NULL
Store.objects.filter(email__isnull=True)

# Get the Store records that have email NOT NULL
Store.objects.filter(email__isnull=False)

Listing 8-37.Django IS and IS NOT queries

清单 8-37 中的第一个例子试图查询 Python 的None值；在这种情况下，None被转换成 SQL 的 NULL(即IS NULL)。清单 8-37 中的第二个和第三个例子使用isnull字段查找，分别创建IS NULL和IS NOT NULL查询。

在查询中:在

SQL IN 语句与 WHERE 子句一起使用，生成与值列表匹配的查询。要用 IN 语句创建 SQL WHERE 查询，可以使用in字段查找，如清单 8-38 所示。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Drink

# Get the Store records that have state 'CA' OR state='AZ'
Store.objects.filter(state__in=['CA','AZ'])

# Get the Item records with id 1,2 or 3
Item.objects.filter(id__in=[1,2,3])

Listing 8-38.Django IN queries

正如您在清单 8-38 中所看到的，Django in字段查找可以用来创建一个查询，查找与来自任何字段(例如，整数、字符串)的列表值相匹配的记录。

LIKE 和 ILIKE 查询:contains、icontains、startswith、istartswith、endswith、iendswith

SQL LIKE 和 ILIKE 查询与 WHERE 子句一起使用来匹配字符串模式，前者区分大小写，后者不区分大小写。Django 提供了三种字段查找来生成类似 SQL 的查询，这取决于您希望匹配的字符串模式。清单 8-39 展示了如何使用 Django 字段查找生成三个不同的类似 SQL 的查询。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Item, Drink

# Get the Store records that contain a 'C' anywhere in state (LIKE '%C%')
Store.objects.filter(state__contains='C')

# Get the Store records that start with 'San' in city (LIKE 'San%')
Store.objects.filter(city__startswith='San')

# Get the Item records that end with 'e' in name (LIKE '%e')
Drink.objects.filter(item__name__endswith='e')

Listing 8-39.Django LIKE queries

正如您在清单 8-39 中看到的，%符号代表一个 SQL 通配符，并根据 Django 字段查找放在 SQL LIKE 模式值的不同位置:要使用LIKE '%PATTERN%'生成一个 SQL 查询，您可以使用contains字段查找；为了生成带有LIKE 'PATTERN%'的 SQL 查询，您使用了startswith字段查找；为了生成带有LIKE '%PATTERN'的 SQL 查询，您可以使用endswith字段查找。

Django 还支持 SQL ILIKE 查询，它的功能类似于 LIKE 查询，但是不区分大小写。清单 8-40 展示了如何使用 Django 字段查找创建 ILIKE 查询。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Item

# Get the Store recoeds that contain 'a' in state anywhere case insensitive (ILIKE '%a%')
Store.objects.filter(state__icontains='a')

# Get the Store records that start with 'san' in city case insensitive (ILIKE 'san%')
Store.objects.filter(city__istartswith='san')

# Get the Item records that end with 'a' in name case insensitive (ILIKE '%A')
Item.objects.filter(name__iendswith='A')

# Get the Store records that have state 'ca' case insensitive (ILIKE 'ca')
Store.objects.filter(state__iexact='ca')

Listing 8-40.Django ILIKE queries

清单 8-40 中的例子就像清单 8-39 中的例子一样，但是唯一的区别是 Django 的字段查找以字母 I 开头，表示不区分大小写的 ILIKE 查询。

值得一提的是清单 8-40 中的最后一个例子是=/EQUAL and 的不区分大小写版本！=/不等于查询。然而，因为iexact在引擎盖下使用了 ILIKE，所以在本节中再次提到它。

REGEXP 查询:regex，iregex

有时 SQL LIKE & ILIKE 语句支持的模式过于基本，在这种情况下，您可以使用 SQL REGEXP 语句将复杂模式定义为正则表达式。正则表达式更强大，因为它们可以定义碎片化的模式，例如:以 sa 开头，后面跟任意字母，后面跟一个数字的模式；或者条件模式，例如以 Los 开始或以 Angeles 结束模式。Django 通过regex字段查找支持 SQL REGEXP 关键字，还通过iregex字段查找支持不区分大小写的正则表达式查询。

尽管描述许多正则表达式语法变体超出了我们的讨论范围，但是一个匹配带有以Los或San开头的city的Store记录的示例正则表达式查询应该是:Store.objects.filter(city__regex=r'^(Los|San) +')。

注定义regex或iregex字段查找模式的推荐实践是使用 Python 原始字符串。Python 原始字符串文字是一个以r开头的字符串，它方便地表达将被转义序列处理修改的字符串(例如，原始字符串r'\n'与标准字符串'\\n'相同)。这种行为对于严重依赖转义字符的正则表达式尤其有用。附录 A 更详细地描述了 Python 原始字符串的使用。

>/大于和小于查询:gt，gte，lt，lte

与数字字段相关联的 SQL WHERE 语句通常使用数学运算符>、> =、> =、< and <= through the 【 , 【 , 【 , and 【 field lookups, respectively. Listing 8-41 说明了这些字段查找在 Django 中的用法。

from coffeehouse.items.models import Item

# Get Item records with stock > 5
Item.objects.filter(stock__gt=5)

# Get Item records with stock > or equal 10
Item.objects.filter(stock__gte=10)

# Get Item records with stock < 100
Item.objects.filter(stock__lt=100)

# Get Item records with stock < or equal 50
Item.objects.filter(stock__lte=50)

Listing 8-41.Django GREATER THAN and LESSER THAN queries

日期和时间查询:范围，日期，年，月，日，周，星期 _ 日，时间，小时，分钟，秒

虽然 SQL WHERE 对日期和时间字段的查询可以用等号、大于号和小于号来完成，但由于它们的特殊性质，编写 SQL 日期和时间查询可能会很耗时。例如，要创建一个 SQL 查询来获取时间戳为 2018 年的所有记录，您需要创建一个类似于'WHERE date BETWEEN '2018-01-01' AND '2018-12-31'的查询。如您所见，如果您添加了处理时区、月份和闰年等内容的需求，这些查询在语法上可能会变得复杂和容易出错。

为了简化带有日期和时间值的 SQL WHERE 查询的创建，Django 提供了各种字段查找，如清单 8-42 所示。

from coffeehouse.online.models import Order
from django.utils.timezone import utc
import datetime

# Define custom dates
start_date = datetime.datetime(2017, 5, 10).replace(tzinfo=utc)
end_date = datetime.datetime(2018, 5, 21).replace(tzinfo=utc)

# Get Order recrods from custom dates, starting May 10 2017 to May 21 2018
Order.objects.filter(created__range=(start_date, end_date))

# Get Order records with exact start date
orders_2018 = Order.objects.filter(created__date=start_date)

# Get Order records with year 2018
Order.objects.filter(created__year=2018)

# Get Order records with month January, values can be 1 through 12 (1=January, 12=December).
Order.objects.filter(created__month=1)

# Get Order records with day 1, where values can be 1 through 31.
Order.objects.filter(created__day=1)

# Get Order records from January 1 2018
Order.objects.filter(created__year=2018,create__month=1,created__day=1)

# Get Order records that fall on week number 24 of the yr, where values can be 1 to 53.
Order.objects.filter(created__week=24)

# Get Order recrods that fall on Monday, where values can be 1 to 7 (1=Sunday, 7=Saturday).
Order.objects.filter(created__week_day=2)

# Get Order records made at 2:30pm using a time object
Order.objects.filter(created__time=datetime.time(14, 30))

# Get Order records made at 10am, where values can be 0 to 23 (0=12am, 23=11pm).
Order.objects.filter(date__hour=10)

# Get Order records made at the top of the hour, where values are 0 to 59.
Order.objects.filter(date__minute=0)

# Get Order records made the 30 second mark of every minute, where values are 0 to 59.
Order.objects.filter(date__second=30)

Listing 8-42.Django date and time queries with field lookups

清单 8-42 中的第一个例子使用了range字段查找，它使用两个 Python datetime.datetime对象来定义查询的日期范围。虽然range是创建日期和时间查询最灵活的方法，但是还有其他提供更简单语法的字段查找替代方法。date字段查找允许您创建一个精确日期的查询。

year、month和day字段查找允许您创建分别匹配给定年、月或日的记录的查询。此外，如果您查看清单 8-42 的中间部分，您会注意到还可以创建一个带有多个字段查找的查询来匹配年、月和日的组合。

最后，在清单 8-42 的下半部分，您可以看到week和week_day字段查找可以分别为匹配一年中给定的一周或一周中的某一天的记录创建一个查询。除了设计用于基于datetime.time对象进行查询的time字段查找，以及设计用于分别为匹配给定小时、分钟或秒的记录创建查询的hour、minute和second字段查找。

Tip

要进行只从记录(而不是完整记录)中提取日期和时间的查询，请查看日期和时间子部分下的 DISTINCT 部分。

Can’T Find an SQL Where Statement? Custom Lookups, Extra(), Subqueries, or Raw Query

尽管 Django 提供了一个广泛的字段查找列表来生成各种 SQL WHERE 语句，但这并不意味着您总能找到必要的字段查找来生成所需的 SQL WHERE 语句。在这种情况下，您有以下选择:

创建自定义查找:就像其他 Django 自定义构造一样，您可以使用自定义 SQL WHERE 语句创建自定义查找。 ²
使用 extra()方法:Django model extra()方法也可以用来创建定制的 SQL WHERE 语句。 ³
使用子查询:子查询允许创建依赖于其他查询结果的 WHERE 语句。本章后面的部分将介绍如何在 Django 模型上创建 SQL 子查询。
原始 SQL 查询:您可以用一字不差的 SQL WHERE 语句创建一个原始(开放式)SQL 查询。本章后面的部分将介绍如何在 Django 模型上执行原始 SQL 查询。

独特的查询

SQL DISTINCT 关键字用于过滤重复记录，并通过distinct()方法在 Django 模型中得到支持。默认情况下，SQL DISTINCT 和 Django distinct()方法应用于整个记录的内容。这意味着除非一个查询限制它的字段数量或者一个查询跨越多个模型，否则distinct()方法将永远不会产生不同的结果。清单 8-43 展示了几个使用distinct()方法的查询，它们更好地展示了这种行为。

from coffeehouse.stores.models import Store

# Get all Store records number
Store.objects.all().count()
4

# Get all distinct Store record number
Store.objects.distinct().count()
4
# Get distinct state Store record values
Store.objects.values('state').distinct().count()
1

# ONLY for PostgreSQL, distinct() can accept model fields to create DISTINCT ON query
Store.objects.distinct('state')

Listing 8-43.Django DISTINCT queries with distinct()

清单 8-43 中的第一个查询获得所有Store记录的总数，而第二个查询获得不同Store记录的总数。请注意，尽管第二个查询使用了distinct()方法，但是两个计数是相同的，因为所有记录中至少有一个字段值(例如id)是不同的。

清单 8-43 中的第三个查询利用values()方法将查询记录限制在仅state字段。一旦完成，将对查询应用distinct()方法，然后应用count()方法，以获得不同的state值的总数。通过在 distinct()方法之前应用选择性查询字段方法(例如，values()或values_list())，distinct()方法执行的逻辑产生逻辑输出。

清单 8-43 中的最后一个例子将一个模型字段传递给distinct()方法，以在查询时产生一个 SQL DISTINCT。只有理解 SQL DISTINCT ON 语句的 PostgreSQL 数据库才支持最后一个distinct()方法语法。

日期和时间查询:日期()和日期时间()

除了distinct()方法，Django 还提供了两种特殊的方法，用于从记录中提取不同的日期和时间值。dates()和datetimes()方法基于匹配不同日期或时间的模型记录值生成一个datetime.date或datetime.datetime对象的列表。

dates()方法接受三个参数，两个是必需的，一个是可选的。第一个参数(必选)是执行不同查询的日期字段，第二个参数(必选)是执行不同查询的日期部分，可以是'year'、'month'或'day'。第三个参数(可选)是查询顺序，默认为'ASC'升序，但也可以是'DESC'降序。

datetimes()方法也接受三个参数，两个是必需的，一个是可选的。第一个参数(必选)是执行不同查询的日期时间字段，第二个参数(必选)是执行不同查询的日期时间部分，可以是'year'、'month'、'day'、'hour'、'minute'或'second'。第三个参数(可选)是查询顺序，默认为'ASC'升序，但也可以是'DESC'降序。

清单 8-44 展示了一系列使用dates()和datetimes()方法的例子。

from coffeehouse.online.models import Order

# Get distinct years (as datetime.date) for Order objects
Order.objects.dates('created','year')
# Outputs: <QuerySet [datetime.date(2017, 1, 1),datetime.date(2018, 1, 1)]>

# Get distinct months (as datetime.date) for Order objects
Order.objects.dates('created','month')
# Outputs: <QuerySet [datetime.date(2017, 3, 1),datetime.date(2017, 6, 1),datetime.date(2018, 2, 1)]>

# Get distinct days (as datetime.datetime) for Order objects
Order.objects.datetimes('created','day')
# Outputs: <QuerySet [datetime.datetime(2017, 6, 17, 0, 0, tzinfo=<UTC>)...]>

# Get distinct minutes (as datetime.datetime) for Order objects
Order.objects.datetimes('created','minute')
# Outputs: <QuerySet [datetime.datetime(2017, 6, 17, 3, 13, tzinfo=<UTC>)...]>

Listing 8-44.Django DISTINCT date and time queries with dates and datetimes() methods

正如您在清单 8-44 中所看到的，dates()方法产生一个由所有模型记录中的给定日期组件生成的datetime.date对象的列表，而datetimes()方法产生一个由所有模型记录中的给定日期时间组件生成的datetime.datetime对象的列表。注意清单 8-44 中的例子将dates()和datetimes()方法应用于所有的模型记录，但是在任何查询(即filter()或exclude())上使用这些方法都是有效的。

Tip

您还可以使用聚合查询来计算不同的值。有关此过程的更多详细信息，请参见聚合查询部分。

订单查询:order_by()和 reverse()

SQL 查询通常使用 ORDER 关键字告诉数据库引擎根据某个或某些字段对查询结果进行排序。这种技术很有帮助，因为它避免了在数据库之外(即在 Python 中)对记录进行排序的额外开销。Django 模型通过order_by()方法支持 SQL ORDER 语句。order_by()方法接受模型字段作为输入来定义查询顺序，这个过程如清单 8-45 所示。

from coffeehouse.stores.models import Store

# Get Store records and order by city (ORDER BY city)
Store.objects.all().order_by('city')

# Get Store recrods, order by name descending, email ascending (ORDER BY name DESC, email ASC)
Store.objects.filter(city='San Diego').order_by('-name','email')

Listing 8-45.Django ORDER queries

清单 8-45 中的第一个例子为所有按照城市排序的Store对象定义了一个查询。默认情况下，order_by设置升序(即“A”记录在前，“Z”记录在后)。清单 8-45 中的第二个例子定义了一个Store查询，但是有多个字段，所以查询首先按第一个字段排序，然后按第二个排序。此外，第二个示例说明了如何使用–(减号)来覆盖默认的升序，-name表示按name对记录进行排序，但以降序排序(即，首先是“Z”记录，最后是“A”记录)。

Tip

您可以在模型上声明 ordering Meta 选项来设置其默认查询排序行为，而不是声明 order_by()方法。参见前一章的查询元选项部分。

除了order_by()方法，Django 模型还支持反转QuerySet结果的reverse()方法。reverse()方法的工作方式就像 Python 的标准reverse()方法一样，颠倒列表的顺序，除了它被设计成在数据被具体化之前对 Django QuerySet数据结构进行操作。

限制查询

当您希望避免在查询中读取整个记录集，而是将结果记录限制在一个较小的记录集中时，可以使用 SQL LIMIT 语句。SQL LIMIT 语句有助于您有目的地逐步读取查询记录(例如，显示在多个页面上的大型查询，也称为分页)-或者您想要对查询进行采样(例如，获取查询中的第一个、最后一个、最新或最早的记录)。

Django 模型提供了各种机制来生成极限查询，这将在下一节中描述。

限制和偏移查询:Python 切片语法

SQL 限制查询通常伴随着 OFFSET 语句，最后一个语句用于从整个记录集中的给定点开始提取记录。Django 模型支持使用标准 Python slice 语法(即用于分割列表的相同语法)创建带有 LIMIT 和 OFFSET 语句的 SQL 查询。清单 8-46 说明了如何生成极限和偏移查询。

from coffeehouse.stores.models import Store
from coffeehouse.items.models import Item

# Get the first five (LIMIT=5) Store records that have state 'CA'
Store.objects.filter(state='CA')[:5]

# Get the second five (OFFSET=5,LIMIT=5) Item records (after the first 5)
Item.objects.all()[5:10]

# Get the first (LIMIT=1) Item object
Item.objects.all()[0]

Listing 8-46.Django LIMIT and OFFSET queries with Python slice syntax

正如您在清单 8-46 中看到的，生成限制和偏移查询的技术是通过 Python 的切片语法直接应用于QuerySet数据结构。如果您从未使用过 Python 的 slice 语法，该技术非常简单:语法QuerySet[start:end]从QuerySet的start到end-1获取项目，语法QuerySet[start:]从start到QuerySet的其余部分获取项目，语法QuerySet[:end]从QuerySet的开头到end-1获取项目。

伪极限 1 阶查询:first()和 last()

在某些情况下，SQL LIMIT 语句用于获取单个记录，即一组记录中的第一条或最后一条记录。Django 模型支持 first()和 last()方法，这些方法生成一个 LIMIT 1 查询，就好像您用 slice 语法[0]创建了一个查询一样——如清单 8-46 中所述。

first()和last()方法通常在order_by()模型方法之前，以保证预期的记录顺序，从而获得所述记录的第一个或最后一个记录。如果在没有使用order_by()模型方法的情况下应用了first()和last()方法，那么查询将根据默认排序机制(通过id字段)来应用，因此first()返回具有第一个id值的记录，而last()返回具有最后一个id值的记录。

例如，查询Store.objects.filter(state='CA').first()获得第一个Store记录，其中state='CA'的id最低(因为订单默认为 id)，这个查询相当于Store.objects.filter(state='CA')[0]。查询Item.objects.all().order_by('name').last()获取字母表中最后一个带有name的条目记录(因为顺序是由name指定的)，这个查询相当于Item.objects.all().order_by('name').reverse()[0]。

伪限制 1 日期和时间查询:最晚()和最早()

对于与日期或时间相关联的 SQL 限制查询，Django 提供了latest()和earliest()方法来获得基于日期字段的最近或第一次创建的模型记录。与first()和last()相比，latest()和earliest()方法都接受执行查询的日期字段，并提供更短的语法来处理与日期或时间相关的有限查询。这是因为latest()和earliest()方法自动对作为参数提供的字段执行order_by()操作。

例如，Order.objects.latest('created')根据created字段获得最近的Order记录，而Order.objects.earliest('created')根据created字段获得最早的Order记录。

Tip

在模型中使用 get_latest_by 元选项设置一个默认字段，在该字段上执行 latest()和 earliest()方法。有关更多详细信息，请参见上一章的元选项。

合并查询

SQL 查询经常需要合并以产生不同的结果集，比如合并多个 SQL 查询的记录或者获取多个 SQL 查询之间的公共记录。Django 支持各种方式来合并 SQL 查询，既可以作为QuerySet数据结构，也可以通过 UNION、INTERSECT 和 EXCEPT 等 SQL 查询语句。

QuerySet 合并:Pipe 和 itertools.chain

正如您在本章中所了解到的，Django 模型通常使用QuerySet数据结构来表示 SQL 查询。这种QuerySet数据结构通常需要合并，以呈现更大的结果集，并避免执行新的数据库查询。清单 8-47 展示了两种可用于合并QuerySet数据结构的语法变体。

from coffeehouse.items.models import Item, Drink
from itertools import chain

menu_sandwich_items = Item.objects.filter(menu__name='Sandwiches')
menu_salads_items = Item.objects.filter(menu__name='Salads')
drinks = Drink.objects.all()

# A pipe applied to two QuerySets generates a larger QuerySet
lunch_items = menu_sandwich_items | menu_salads_items

# | can't be used to merge QuerySet's with different models # ERROR menu_sandwich_items | drinks

# itertools.chain generates a Python list and can merge different QuerySet model types
lunch_items_with_drinks = list(chain(menu_sandwich_items, drinks))

Listing 8-47.Combine two Django queries with | (pipe) and itertools.chain

清单 8-47 中的第一个选项使用|(管道)操作符来组合两个QuerySet数据结构。这种技术产生了另一种QuerySet数据结构，但是有一个警告，即只能在使用相同模型的QuerySet上工作(例如Item)。

清单 8-47 中的第二个选项使用 Python itertools包通过chain()方法合并两个QuerySet数据结构。这种技术产生一个标准的 Python 列表——带有各自的模型对象——并且是更灵活的选择，因为它可以组合QuerySet数据结构，即使它们使用不同的模型(例如Item和Drink)。

联合查询:UNION()

SQL UNION 语句用于在数据库中直接合并两个或多个查询。不像前面的合并查询技术——如清单 8-47 所示——发生在 Django/Python 中，联合查询完全由数据库引擎完成。Django 通过union()方法支持 SQL UNION 语句，如清单 8-48 所示。

from coffeehouse.items.models import Item

menu_breakfast_items = Item.objects.filter(menu__name='Breakfast')
menu_sandwich_items = Item.objects.filter(menu__name='Sandwiches')
menu_salads_items = Item.objects.filter(menu__name='Salads')

# All items merged with union()
all_items = menu_breakfast_items.union(menu_sandwich_items,menu_salads_items)
print(all_items.query)
SELECT "items_item"."id", "items_item"."menu_id" ... WHERE "items_menu"."name" = Breakfast UNION SELECT "items_item"."id", "items_item"."menu_id" ... WHERE "items_menu"."name" = Sandwiches UNION SELECT "items_item"."id", "items_item"."menu_id"... WHERE "items_menu"."name" = Salads

Listing 8-48.Merge Django queries with union()

清单 8-48 首先声明了三个产生QuerySet数据结构的标准 SQL 查询。接下来，注意union()方法是如何链接到一个查询的，其余的查询是作为参数传递的。最后，清单 8-48 展示了union()方法的结果如何产生一个包含多个 SQL UNION 语句的查询，这些语句合并了各个查询。

除了union()方法接受不同的QuerySet实例作为参数之外，union()方法还接受设置为False的可选关键字all参数。默认情况下，union()方法忽略跨QuerySet实例的重复值；但是，您可以将all参数设置为True来告诉 Django 合并重复的记录(例如menu_breakfast_items.union(menu_sandwich_items,menu_salads_items, all=True))。

相交查询:相交()

SQL INTERSECT 语句用于获取在多个查询中相交(即存在)的记录。Django 通过intersection()方法支持 SQL INTERSECT 语句，如清单 8-49 所示。

from coffeehouse.items.models import Item

all_items = Item.objects.all()
menu_breakfast_items = Item.objects.filter(menu__name='Breakfast')

# Intersected (common) records merged with intersect()
intersection_items = all_items.intersection(menu_breakfast_items)
print(intersection_items.query)
SELECT "items_item"."id", "items_item"."menu_id", "items_item"."name"... INTERSECT SELECT "items_item"."id", "items_item"."menu_id", "items_item"."name"... WHERE "items_menu"."name" = Breakfast

Listing 8-49.Intersect (Common) Django query records with intersection()

清单 8-49 首先声明了两个产生QuerySet数据结构的标准 SQL 查询。接下来，注意intersection()方法是如何链接到其中一个查询的，剩下的查询是如何作为参数传递的。最后，清单 8-49 展示了intersection()方法的结果如何产生一个带有 SQL 交集语句的查询，从而产生跨查询的公共记录。

intersection()方法只接受QuerySet实例作为参数。此外，在一个intersection()查询中声明两个以上的QuerySet实例时要小心，因为只有出现在所有QuerySet实例中的记录才构成最终查询结果的一部分。

例外查询:差异()

SQL EXCEPT 语句用于获取在查询中出现但在其他查询中缺失的记录。Django 通过difference()方法支持 SQL EXCEPT 语句，如清单 8-50 所示。

from coffeehouse.items.models import Item

all_items = Item.objects.all()
menu_breakfast_items = Item.objects.filter(menu__name='Breakfast')
menu_sandwich_items = Item.objects.filter(menu__name='Sandwiches')
menu_salads_items = Item.objects.filter(menu__name='Salads')

# Extract records in all_items, except those in:
#     menu_breakfast_items, menu_sandwich_items & menu_salads_items
ex_items = all_items.difference(menu_breakfast_items, menu_sandwich_items, menu_salads_items)
print(ex_items.query)
SELECT "items_item"."id", "items_item"."menu_id", "items_item"."name"...EXCEPT SELECT "items_item"."id", "items_item"."menu_id", "items_item"."name"... EXCEPT SELECT "items_item"."id", "items_item"."menu_id", "items_item"."name", ... EXCEPT SELECT "items_item"."id", "items_item"."menu_id", "items_item"."name" ... WHERE "items_menu"."name" = Salads

Listing 8-50.Except Django query records with difference()

清单 8-50 首先声明了产生QuerySet数据结构的四个标准 SQL 查询。接下来，注意如何在all_items查询上调用difference()方法，以及如何将剩余的查询作为要从all_items查询中排除的参数进行传递。最后，清单 8-50 展示了difference()方法的结果如何产生一个包含多个 SQL EXCEPT 语句的查询，这些语句从父查询中排除查询记录。

聚合查询

SQL 查询有时需要从 Django 模型中包含的核心字段生成值(例如，记录集的计数、平均值、最大值或最小值等数学计算)。将这种类型的聚合信息存储为单独的 Django 模型字段是多余的——因为它可以从核心数据中导出——并且在数据库环境之外计算这些数据也是浪费的(例如，读取所有记录并在 Python 中生成聚合结果)。

SQL 通过聚合函数为数据库提供了必要的语句来解决这个问题。聚合函数是 SQL 查询的一部分，由数据库引擎执行，并在与aggregate()方法结合使用时作为独立的结果返回，或者在与annotate()方法结合使用时作为附加字段与结果 SQL 响应一起返回。Django 通过一系列方法支持聚合查询，包括count()、aggregate()和annotate()，以及聚合类。

计数查询:count()方法和 COUNT()类

SQL COUNT 聚合函数用于这样的情况:您只需要获取符合特定条件的记录数，而不需要读取构成查询的所有记录。使用 SQL COUNT 的查询也更有效，因为是数据库引擎进行计算，而不是获取所有数据并在 Python 中进行计算。

Django models 通过count()方法和 aggregate Count类支持 SQL 计数聚合函数。两种变化都在清单 8-51 中进行了说明。

from coffeehouse.stores.models import Store

from django.db.models import Count

# Get the number of stores (COUNT(*))
stores_count = Store.objects.all().count()
print(stores_count)
4

# Get the number of stores that have city 'San Diego' (COUNT(*))
stores_san_diego_count = Store.objects.filter(city='San Diego').count()

# Get the number of emails, NULL values are not counted (COUNT(email))
emails_count = Store.objects.aggregate(Count('email'))
print(emails_count)
{'email__count': 4}

# Get the number of emails, NULL values are not counted (COUNT(email) AS "coffeehouse_store_emails_count")
emails_count_custom = Store.objects.aggregate(coffeehouse_store_emails_count=Count('email'))
print(emails_count_custom)
{'coffeehouse_store_emails_count': 4}

# Get number of distinct Amenities in all Stores, NULL values not counted (COUNT(DISTINCT name))
different_amenities_count = Store.objects.aggregate(Count('amenities',distinct=True))
print(different_amenities_count)
{'amenities__count': 5}

# Get number of Amenities per Store with annotate
stores_with_amenities_count = Store.objects.annotate(Count('amenities'))
# Get amenities count in individual Store
stores_With_amenities_count[0].amenities__count

# Get number of Amenities per Store with annotate and custom name
stores_amenities_count_custom = Store.objects.annotate(amenities_per_store=Count('amenities'))
stores_amenities_count_custom[0].amenities_per_store

Listing 8-51.Django COUNT queries with aggregate(), annotate(), and Count()

清单 8-51 中的前两个例子将count()方法作为 Django 查询的最后一部分，以获得总计数。

清单 8-51 中的第三个例子使用aggregate()函数和聚合Count类来获得Store记录中emails的总数。请注意使用aggregate()方法的查询是如何生成字典的，其中的键是 counted 字段——在本例中是email——后缀是__count,表示聚合类，字典值是结果计数。清单 8-51 中的第四个例子与第三个非常相似，除了它在聚合Count类前添加了一个自定义字符串来模拟 SQL AS 关键字，因此得到的字典值使用自定义字符串coffeehouse_store_emails_count作为关键结果。

Note

如果在查询中没有将字符串分配给聚合类(例如 Count)，则结果查询输出默认为: __ <aggregate_class>。</aggregate_class>

清单 8-51 中的第五个例子说明了 aggregate Count类如何接受可选的distinct=True参数来忽略计数中的重复值。在这种情况下，对所有与Store记录相关联的amenities进行计数，但是该计数仅反映不同的amenities值。

虽然aggregate()方法产生聚合结果，但是它仅限于自己产生聚合结果，也就是说，它需要额外的查询来获取计算聚合结果的核心数据。annotate()方法解决了这个问题，如清单 8-51 所示。

清单 8-51 中的最后两个例子使用annotate()方法向查询记录添加一个额外的字段来保存一个聚合结果。清单 8-51 中倒数第二个例子通过聚合Count()类将amenities__count字段添加到所有Store记录中。清单 8-51 中的最后一个例子为聚合Count()类分配了一个自定义字符串，以创建自定义amenities_per_store字段来保存所有Store记录的amenities计数。

Max、Min、Sum、AVG、方差和 StdDev 查询:MAX()、MIN()、SUM()、Avg()、VARIANCE()和 STDDEV()类

除了 SQL 计数聚合函数之外，SQL 查询还支持其他聚合函数，用于最好在数据库中完成的数学运算。这些 SQL 聚合函数包括从一组记录中获取最大值的 MAX、从一组记录中获取最小值的 MIN、从一组记录中获取值的 SUM、从一组记录中获取平均值的 AVG、从一组记录中获取值的统计方差的 VARIANCE 以及从一组记录中获取统计偏差的 STDDEV。

Django 模型通过使用聚合类支持所有以前的 SQL 聚合函数——就像清单 8-51 中描述的Count()聚合一样。因此，为了利用这些额外的 SQL 聚合函数，您可以将 Django 模型的aggregate()或annotate()方法与相关的聚合类结合使用，清单 8-52 展示了这个过程。

from coffeehouse.items.models import Item
from django.db.models import Avg, Max, Min
from django.db.models import Sum
from django.db.models import Variance, StdDev

# Get the average, maximum and minimum number of stock for all Item records
avg_max_min_stock = Item.objects.aggregate(Avg('stock'), Max('stock'), Min('stock'))

print(avg_max_min_stock)
{'stock__avg': 29.0, 'stock__max': 36, 'stock__min': 27}

# Get the total stock for all Items
item_all_stock = Item.objects.aggregate(all_stock=Sum('stock'))
print(item_all_stock)
{'all_stock': 261}

# Get the variance and standard deviation for all Item records
# NOTE: Variance & StdDev return the population variance & standard deviation, respectively.
#       But it's also possible to return sample variance & standard deviation,
#       using the sample=True argument
item_statistics = Item.objects.aggregate(Variance('stock'), std_dev_stock= StdDev('stock'))
{'std_dev_stock': 5.3748, 'stock__variance': 28.8888}

Listing 8-52.Django MAX, MIN,SUM, AVG, VARIANCE and STDDEV queries with Max(), Min(), Sum(), Avg(), Variance() and StdDev() classes

正如您在清单 8-52 中的第一个例子中所看到的，作为aggregate()方法的一部分，可以为一个查询定义多个聚合类，在这种情况下，查询获得所有Item记录的平均值、最小值和最大值stock。

清单 8-52 中的第二个例子通过使用 aggregate Sum类获得所有条目记录中所有stock值的总和。请注意，在第二个示例中，如何在 aggregate 类前面加上一个自定义字符串作为 SQL AS 关键字，以便查询输出与 aggregate 类名不同的结果值。最后，清单 8-52 中的最后一个例子计算所有项目记录中所有stock值的方差和标准差。

Tip

如果要执行更复杂的聚合查询，如多字段数学运算(如乘法)，请参阅 F 表达式小节。

如果要执行更复杂的聚合查询，请参阅使用原始(开放式)SQL 的模型查询一节。

表达式和函数查询

SQL 查询通常引用由调用环境提供的值，而不考虑它们的许多语句。例如，当您创建一个查询来获取所有具有某些state值的Store记录时，Django/Python 为state提供一个值引用，同样，如果您创建一个查询来获取属于某个Menu模型的所有Item记录，Django/Python 为Store提供一个值引用。

但是，对于某些 SQL 查询，有必要使用指向实际数据库中数据的引用。这是必要的，因为某些 SQL 查询的结果取决于数据库中存在的数据，或者因为在数据库(即 Python)的上下文之外操作数据是一项额外的工作，可以很容易地在 SQL 中解决。

您已经在前面关于聚合查询的章节中了解了这种技术，其中 SQL 查询可以告诉数据库引擎计算诸如计数和平均值之类的东西，而不需要提取数据并在数据库之外执行操作(例如，用 Python)。聚合查询依赖于一个特殊的表达式子集，称为聚合表达式，但是在接下来的章节中，您将了解 Django 如何支持许多其他类型的 SQL 表达式。

另一种 SQL 技术是 SQL 函数，它以 SQL 表达式的相同精神设计，有利于将工作委托给数据库引擎。SQL 函数旨在允许数据库改变查询的结果(例如，连接两个字段或将一个字段转换为大写/小写),并减轻在呼叫方环境(即，Django/Python)中对这种任务的需要。在下一节中，您还将了解 Django 模型支持的不同 SQL 函数。

SQL 表达式查询:F 表达式

Django F 表达式是 Django 模型中最常见的 SQL 表达式。在本章开始时，您已经了解了 F 表达式的用途，了解了如何在一个步骤中更新一条记录，并让数据库引擎执行逻辑，而不需要从数据库中提取记录。

通过 F 表达式，可以在查询中引用模型字段，并让数据库对模型字段值执行操作，而无需从数据库中提取数据。反过来，这不仅提供了更简洁的查询语法——单个更新查询，而不是两个(一个读取，一个更新)——它还避免了“竞争条件”。 ⁴

清单 8-53 展示了在更新查询中使用 F 表达式的各种方式。

from coffeehouse.items.models import Item
from django.db.models import F

# Get single item
egg_biscuit = Item.objects.get(id=2)
# Check stock
egg_biscuit.stock
2
# Add 10 to stock value with F() expression
egg_biscuit.stock = F('stock') + 10
# Trigger save() to apply F() expression
egg_biscuit.save()
# Check stock again
egg_biscuit.stock
<CombinedExpression: F(stock) + Value(10)>
# Ups, need to re-read/refresh from DB
egg_biscuit.refresh_from_db()
# Check stock again
egg_biscuit.stock
12

# Decrease stock value by 1 for Item records on the Breakfast menu
breakfast_items = Item.objects.filter(menu__name='Breakfast')
breakfast_items.update(stock=F('stock') – 1)

# Increase all Item records stock by 20
Item.objects.all().update(stock=F('stock') + 20)

Listing 8-53.Django F() expression

update queries

清单 8-53 中的第一个例子读取单个模型记录，并将一个F()表达式应用于stock字段。一旦应用了F()表达式，就需要对数据库的记录调用save()方法来触发更新。接下来，请注意，为了让模型记录引用反映出F()表达式的结果，您必须从数据库中重新读取记录——在本例中使用的是refresh_from_db()方法——因为数据库是唯一知道更新操作结果的一方。

接下来在清单 8-53 中，您可以看到如何对一个F()表达式执行减法运算，以及通过update()方法将一个F()表达式应用到一个QuerySet中的所有记录。

除了更新记录而不需要从数据库中提取数据之外，F()表达式还可以用于数据库读取操作。F()表达式对于读取查询和聚合查询很有帮助，这些查询的结果最好由数据库引擎决定，如清单 8-54 所示。

from django.db.models import  F, ExpressionWrapper, FloatField
from coffeehouse.items.models import Drink, Item

calories_dbl_caffeine_drinks = Drink.objects.filter(item__calories__gt=F('caffeine')*2)

items_with_assets = Item.objects.annotate(
                                 assets=ExpressionWrapper(F('stock')*F('price'),
                                 output_field=FloatField()))

Listing 8-54.Django F() expressions in read queries and aggregate queries

请注意清单 8-54 中的第一个查询示例缺少任何固定值，而是由数据库引擎检查的引用组成，以返回符合条件的记录。在这种情况下，查询获得所有calories大于其caffeine内容两倍的Drink记录，其中其数据库引擎——通过F()表达式——负责确定哪些Drink记录符合该规则。

清单 8-54 中的第二个例子从两个F()表达式中创建一个聚合查询。在这种情况下，通过F()表达式将记录的stock和price字段的值相乘，用annotate()方法计算出一个名为assets的新字段。与上一节中的聚合查询示例不同，此聚合有两个重要的差异和参数:

ExpressionWrapper。-因为清单 8-54 中的聚集查询由多个模型字段组成，所以有必要通过将聚集查询包装在ExpressionWrapper语句中来划定其范围。
output_field.-当一个聚合查询由多个模型字段组成，并且数据类型不同时，需要用一个模型数据类型指定output_field。在清单 8-54 中，因为stock是一个IntegerField模型字段，而price是一个FloatField模型字段，所以output_field告诉 Django 将聚合的assets字段生成为FloatField，从而避免数据类型不明确。

SQL 函数查询:Func 表达式和 Django 数据库函数

Func 表达式是 Django 模型支持的另一个表达式子集，它与其他 SQL 表达式的目的相同:使用数据库来执行操作，而不是获取数据，然后在数据库外执行操作(即在 Python 中)。

Django 中使用 Func 表达式来触发数据库函数的执行。与用于对模型字段执行基本操作的 F 表达式不同，Func 表达式用于执行数据库支持的更复杂的函数，并对模型字段运行这些函数。

清单 8-55 展示了一个调用 SQL 函数的 Func 表达式的例子，以及几个模拟 SQL 函数的 Django 数据库函数。

from django.db.models import  F, Func, Value
from django.db.models.functions import Upper, Concat
from coffeehouse.stores.models import Store

# SQL Upper function call via Func expression and F expression
stores_w_upper_names = Store.objects.annotate(name_upper=Func(F('name'), function='Upper'))
stores_w_upper_names[0].name_upper
'CORPORATE'
stores_w_upper_names[0].name
'Corporate'

# Equivalent SQL Upper function call directly with Django SQL Upper function
stores_w_upper_names_function = Store.objects.annotate(name_upper=Upper('name'))
stores_w_upper_names_function[0].name_upper
'CORPORATE'

# SQL Concat function called directly with Django SQL Concat function
stores_w_full_address = Store.objects.annotate(full_address=
                               Concat('address',Value(' - '),'city',Value(' , '),'state'))
stores_w_full_address[0].full_address
'624 Broadway - San Diego, CA'
stores_w_full_address[0].city
'San Diego'

Listing 8-55.Django Func() expressions

for SQL functions and Django SQL functions

清单 8-55 中的第一个例子利用Func()表达式通过annotate()生成额外的name_upper字段。额外的name_upper字段的目的是以大写格式获取所有Store记录的名称，这个过程非常适合 SQL UPPER 函数。在清单 8-55 的情况下，Func()表达式声明了两个参数:一个F表达式指定要应用函数的模型字段，另一个function参数指定要使用的 SQL 函数。一旦创建了查询，您可以在清单 8-55 中看到，每条记录都可以访问带有大写版本的name字段的附加name_upper字段，以及其他模型字段。

虽然Func()表达式是使用 SQL 表达式生成 Django 模型查询的最灵活的选项，但是对于默认场景，Func()表达式可能会很冗长。Django 提供了一种更快的替代方法，通过django.db.models.functions包中的 SQL 函数生成 SQL 表达式。

清单 8-55 中的第二个查询等价于第一个查询，但是注意这个变化使用 Django 数据库Upper()函数作为annotate()方法的参数，类似于 Django 集合类如何在annotate()语句中声明。

清单 8-55 中的第三个例子通过annotate()生成附加的full_address字段，并利用 Django 数据库Concat()函数。Concat()函数的目的是连接多个模型字段的值。在清单 8-55 的情况下，Concat()函数将Store型号的地址、城市和州的值连接起来。为了在串联的字段值之间留出空格，Concat()函数使用 Django Value()表达式输出逐字分隔符和空格。一旦创建了查询，您可以在清单 8-55 中看到，每条记录都可以访问附加的full_address字段以及address, city和state字段的串联值，还可以访问其他模型字段。

Django 在django.db.models.functions包 ⁵ 中包含了十几个数据库函数，用于字符串、日期和其他可以在查询中作为 SQL 函数使用的数据类型。

SQL 子查询:子查询表达式

SQL 子查询是嵌套在其他标准 CRUD 查询或包含其他子查询中的查询。大多数 SQL 子查询在两种情况下使用。第一种情况发生在您需要创建包含跨多个表的相关字段的 SQL 查询时，但是基础表之间没有显式的关系。

第一个 SQL 子查询场景常见于涉及多个 Django 模型且缺少关系数据类型(即OneToOneField、ForeignKey和ManyToManyField)的查询。清单 8-56 展示了通过使用Subquery表达式解决的 SQL 子查询场景。

from django.db.models import OuterRef, Subquery

class Order(models.Model):
    created = models.DateTimeField(auto_now_add=True)

class OrderItem(models.Model):
    item = models.IntegerField()
    amount = models.IntegerField()
    order = models.ForeignKey(Order)

# Get Items in order number 1
order_items = OrderItem.objects.filter(order__id=1)
# Get item
order_items[0].item
1
# Get item name ?

# OrderItem item field is IntegerField, lacks Item relationship
# Create sub-query to get Item records with id
item_subquery = Item.objects.filter(id=(OuterRef('id')))

# Annotate previous query with sub-query
order_items_w_name = order_items.annotate(item_name=Subquery(item_subquery.values('name')[:1]))
# Output SQL to verify
print(order_items_w_name.query)
SELECT `online_orderitem`.`id`, `online_orderitem`.`item`,
    `online_orderitem`.`amount`, `online_orderitem`.`order_id`,
     (SELECT U0.`name` FROM `items_item` U0 WHERE U0.`id` = (online_orderitem.`id`) LIMIT 1)
     AS `item_name` FROM `online_orderitem` WHERE `online_orderitem`.`order_id` = 1
# Access item and item_name
order_items_w_name[0].item
1
order_items_w_name[0].item_name
'Whole-Grain Oatmeal'

Listing 8-56.Django Subquery expression with SQL subquery to get related model data

清单 8-56 中的第一行显示了Order和OrderItem型号，包括一个获取所有属于Order编号 1 的OrderItem记录的查询。接下来，您可以看到虽然OrderItem模型有一个item字段，但是它的值是一个整数。这就产生了一个问题，因为不可能获得与一个item字段整数值相关联的name和其他属性，或者换句话说，OrderItem记录缺少与项目模型的关系。这个问题可以通过子查询来解决。

接下来在清单 8-56 中，声明了Item.objects.filter(id=(OuterRef('id')))子查询以通过id获取所有的Item记录，这是主OrderItem期望映射到item值的值。特殊的OuterRef语法像一个F表达式一样工作，直到父查询被解析；毕竟，要通过id获得的Item记录依赖于父查询(例如，对于OrderItem记录中的那些项目，子查询应该只通过id获得Item记录)。

一旦在清单 8-56 中定义了子查询，它就会通过annotate()方法和Subquery()表达式链接到初始的OrderItem查询。接下来，您可以看到查询生成的 SQL 包含一个引用Item模型的子查询。最后，清单 8-56 展示了通过子查询生成的OrderItem查询上附加的item_name字段的输出。

涉及子查询的第二种情况是，一个 SQL 查询必须生成一个 WHERE 语句，该语句的值依赖于另一个 SQL 查询的结果。这个场景在清单 8-57 中进行了说明。

# See Listing 8-56 for referenced model definitions
from coffeehouse.online.models import Order
from coffeehouse.items.models import Item
from django.db.models import OuterRef, Subquery

# Get Item records in lastest Order to replenish stock
most_recent_items_on_order = Order.objects.latest('created').orderitem_set.all()

# Get a list of Item records based on recent order using a sub-query
items_to_replenish = Item.objects.filter(id__in=Subquery(
                                    most_recent_items_on_order.values('item')))

print(items_to_replenish.query)
SELECT `items_item`.`id`, `items_item`.`menu_id`, `items_item`.`name`, `items_item`.`description`, `items_item`.`size`, `items_item`.`calories`,
`items_item`.`price`, `items_item`.`stock` FROM `items_item` WHERE `items_item`.`id`
  IN (SELECT U0.`item` FROM `online_orderitem` U0 WHERE U0.`order_id` = 1)

Listing 8-57.Django Subquery expression with SQL subquery in WHERE statement

清单 8-57 的第一步是从最新的Order记录中获取所有的OrderItem记录，目的是检测要补充哪个Item库存。然而，因为OrderItem记录使用一个普通的整数 id 来引用Item记录，所以有必要创建一个子查询来获取基于OrderItem整数引用的所有Item记录。

接下来在清单 8-57 中，查询 id 包含在子查询中的项目记录。在这种情况下，Subquery表达式用于指向most_recent_items_on_order查询，该查询仅从最近的Order记录中获取item值(即整数值)。

最后，清单 8-57 展示了生成的查询如何使用利用子查询的 WHERE 语句。

Join Queries

SQL JOIN 关键字用于从多个数据库表中产生查询。Django 通过 select_related()方法支持相关模型的连接查询，这在前面的跨 Django 模型的 CRUD 关系记录中有所描述。

如果您想在没有 Django 模型关系的表之间创建一个连接查询，您可以使用一个原始 SQL 查询，这将在下一节中介绍。

使用原始(开放式)SQL 对查询进行建模

尽管 Django 模型查询非常广泛，但是在某些情况下，前面几节中介绍的选项都不足以执行某些 CRUD 操作。在这种情况下，您必须依赖原始(开放式)SQL 查询，这是对连接到 Django 项目的数据库执行操作的最灵活的方法。

Django 提供了两种执行原始 SQL 查询的方法。第一种方法是使用模型管理器的raw()方法，将得到的 SQL 查询数据放入 Django 模型中，这样做的额外好处是原始 SQL 查询的行为尽可能接近本地 Django 模型查询。第二种方法是使用 Python 数据库连接——由 Django 管理——获取 SQL 查询数据，并使用较低级别的 Python DB API 函数(例如，cursor)对其进行处理。 ⁶

使用模型管理器的 raw()方法的 SQL 查询

模型管理器的raw()方法应该是您执行原始 SQL 查询的第一选择，因为结果被结构化为一个RawQuerySet类实例，这与您到目前为止使用的 Django 模型查询产生的QuerySet类实例非常相似。

因此，RawQuerySet类实例——就像QuerySet类实例一样——提供了一种使用 Django 模型的字段访问记录的简单方法，能够延迟模型字段的加载，以及索引和切片。清单 8-58 展示了用模型管理器的raw()方法执行的一系列原始 SQL 查询。

from coffeehouse.items.models import Drink, Item

# Get all drink
all_drinks = Drink.objects.raw("SELECT * FROM items_drink")

# Confirm type
type(all_drinks)
# Outputs: <class 'django.db.models.query.RawQuerySet'>

# Get first drink with index 0
first_drink = all_drinks[0]
# Get Drink name (via item OneToOne relationship)
first_drink.item.name

# Use parameters to limit a raw SQL query
caffeine_limit = 100

# Create raw() query with params argument to pass dynamic arguments
drinks_low_caffeine = Drink.objects.raw("SELECT * FROM items_drink where caffeine < %s",params=[caffeine_limit]);

Listing 8-58.Django model manager raw() method

清单 8-58 中的第一个代码片段使用Drink模型管理器的raw()方法发出SELECT * FROM items_drink查询。值得一提的是，这个原始查询产生与原生 Django 查询Drink.objects.all()相同的结果，但是与产生QuerySet数据结构的原生查询不同，请注意raw()方法查询是如何产生RawQuerySet数据结构的。

因为RawQuerySet数据结构是QuerySet的子类，清单 8-58 展示了如何使用与QuerySet数据结构相同的机制。例如，对记录的访问也是通过索引来完成的(例如，使用[0]来获取第一个元素)，也可以使用点符号来访问相关的模型。

最后，清单 8-58 中的最后一个例子说明了如何使用params参数创建带有动态参数的原始 SQL 查询。在所有需要创建依赖于动态值(例如，由用户或另一个子程序提供)的raw() SQL 查询的情况下，您应该总是创建带有占位符-% s --的原始 SQL 查询字符串，然后通过params参数进行替换。在清单 8-58 的情况下，请注意caffeine_limit变量是如何在params中声明的，以便稍后被替换到原始 SQL 查询中。params参数确保动态值在应用到数据库之前从查询中逸出，避免了潜在的 SQL 注入安全攻击。 ⁷

清单 8-58 中的raw() SQL 例子很简单，因为查询结果直接映射到预期的模型。换句话说，SELECT * FROM items_drink查询产生了 Django 创建Item记录所需的结果，而无需额外的帮助。虽然有时候，raw() SQL 查询需要额外的配置才能创建底层的模型记录。

例如，如果您对一个遗留表或多个表执行原始 SQL 查询，打算使用某个模型的 raw()方法，那么您必须确保 Django 能够将原始 SQL 查询的结果解释给模型，方法是在原始 SQL 中使用 SQL 作为语句，或者依赖于raw() translations 参数。清单 8-59 展示了这两种技术。

# Map results from legacy table into Item model
all_legacy_items = Item.objects.raw("SELECT product_name AS name, product_description AS description from coffeehouse_products")

# Access legacy results as if they are standard Item model records
all_legacy_items[0].name

# Use explicit mapping argument instead of 'as' statements in SQL query
legacy_mapping = {'product_name':'name','product_description':'description'}

# Create raw() query with translations argument to map table results
all_legacy_items_with_mapping = Item.objects.raw("SELECT * from coffeehouse_products", translations=legacy_mapping)

# Deferred model field loading, get item one with limited fields
item_one = Item.objects.raw("SELECT id,name from items_item where id=1")
# Acess model fields not referenced in the raw query, just like QuerySet defer()
item_one[0].calories
item_one[0].price

# Raw SQL query with aggregate function added as extra model field
items_with_inventory = Item.objects.raw("SELECT *, sum(price*stock) as assets from items_item");
# Access extra field directly as part of the model
items_with_inventory[0].assets

Listing 8-59.Django model manager raw() method with mapping, deferred fields, and aggregate queries

清单 8-59 中的第一个例子用多个 SQL AS 语句声明了一个raw()方法，在这种情况下，每个 AS 子句对应一个项目模型字段。以这种方式，当 Django 检查原始查询的结果时，它知道如何将结果映射到Item实例，而不考虑底层数据库表列名。

清单 8-59 中的第二个例子声明了一个带有translations参数的raw()方法，其值是一个 Python 字典，该字典将数据库表列名映射到 Django 模型字段。在这种情况下，当 Django 在原始查询结果中遇到未知的数据库表列名时，它使用translations字典来确定如何将结果映射到条目实例。

清单 8-59 中的第三个例子说明了即使使用raw()方法发出部分原始 SQL 查询，Django 也能够获取缺失的字段，就好像它是本地QuerySet数据结构一样。最后，清单 8-59 中的第四个例子说明了raw()方法如何能够处理声明为聚集查询的额外字段，以及它们如何变得可访问，就好像它们是用本地模型aggregate()方法添加的一样。

使用 Python 的 DB API 进行 SQL 查询

尽管 Django model raw()方法提供了一个创建原始 SQL 查询的很好的替代方法，并且能够利用原生 Django 模型特性，但是在某些情况下，使用模型的raw()方法进行原始 SQL 查询是行不通的。要么是因为原始 SQL 查询的结果不能映射到 Django 模型，要么是因为您只想在不受任何 Django 模型影响的情况下访问原始数据。

在这种情况下，您需要使用第二个 Django 选项来执行原始 SQL 查询，包括直接连接到数据库并显式提取查询结果。尽管第二种 Django 方法在技术上是与数据库交互最灵活的，但它也需要使用来自 Python 的 DB API 的低级调用。

使用这种技术执行原始 SQL 查询时，Django 中唯一可以利用的是 Django 项目中定义的数据库连接(即settings.py中的DATABASES变量)。一旦建立了数据库连接，您将需要依赖 Python DB API 方法，如cursor()、fetchone()和fetchall()，以及执行结果的手动提取，以便能够成功运行原始 SQL 查询。

清单 8-60 展示了在 Django 环境中使用 Python DB API 的 SQL 查询。

from django.db import connection

# Delete record
target_id = 1
with connection.cursor() as cursor:
    cursor.execute("DELETE from items_item where id = %s", [target_id])

# Select one record
salad_item = None
with connection.cursor() as cursor:
    cursor.execute("SELECT * from items_item where name='Red Fruit Salad'")
    salad_item = cursor.fetchone()

# DB API fetchone produces a tuple, where elements are accessible by index
salad_item[0] # id
salad_item[1] # name
salad_item[2] # description

# Select multiple records
all_drinks = None
with connection.cursor() as cursor:
    cursor.execute("SELECT * from items_drink")
    all_drinks = cursor.fetchall()

# DB API fetchall produces a list of tuples
all_drinks[0][0] # first drink id

Listing 8-60.Django raw SQL queries with connection() and low-level DB API methods

清单 8-60 中的第一条语句导入了django.db.connection，它代表了在settings.py的DATABASES变量中定义的default数据库连接。一旦有了对 Django 数据库的connection引用，就可以开始使用 Python DB API，这通常是从使用cursor()方法开始的。 ⁸

清单 8-60 中的第一个原始 SQL 查询在connection上打开一个cursor，并执行cursor.execute()方法来执行删除操作。因为删除查询不返回结果，所以在调用了cursor.execute()方法之后，操作被认为是结束了

Tip

如果在数据库中声明多个数据库引用，可以使 django.db.connections 引用在特定数据库上创建一个游标，而不是默认的游标:

从 django.db 导入连接

游标=连接['分析']。cursor() # Cursor 连接到“分析”数据库

清单 8-60 中的第二个原始 SQL 查询首先声明了salad_item占位符变量来存储原始 SQL 查询的结果。一旦完成，另一个cursor在connection上打开，使用相同的cursor.execute()方法执行选择操作。因为 select 查询返回一个结果，所以对cursor.fetchone()方法进行了一次额外的调用，以提取查询结果并将它们分配给占位符变量。注意，使用fetchone()方法是因为预计原始 SQL 查询将返回单个记录结果。

接下来，观察索引如何访问salad_item中原始 SQL 查询的结果。因为 Python DB API cursor.fetchone()方法不使用字段名或其他引用，所以您必须知道记录字段返回的顺序，对于包含许多字段的原始 SQL 来说，这个过程可能特别麻烦。

清单 8-60 中的第三个原始 SQL 查询首先声明了all_drinks占位符变量来存储原始 SQL 查询的结果。一旦完成，另一个cursor在connection上打开，使用相同的cursor.execute()方法执行另一个选择操作。因为 select 查询返回一个结果，所以对cursor.fetchall()方法进行了一次额外的调用，以提取查询结果并将它们分配给占位符变量。注意，使用fetchall()方法是因为预计原始 SQL 查询将返回多个记录结果。

接下来，观察多个索引如何访问all_drinks中原始 SQL 查询的结果。因为 Python DB API cursor.fetchall()方法不使用字段名或其他引用，所以第一个索引表示结果中的一条记录，第二个索引表示给定记录中的一个字段值。

模型经理

正如您在本章和上一章的例子中所了解到的，Django 模型的objects参考或默认模型管理器提供了大量执行数据库操作的功能。

在大多数情况下，Django 模型不需要对它们的默认模型管理器或objects引用进行任何修改。但是，在某些情况下，需要定制 Django 模型的默认模型管理器，或者创建多个模型管理器。

定制和多模型管理器

创建自定义 Django 模型管理器的一个主要原因是添加自定义管理器方法，以便更容易地在模型上执行循环查询。

例如，运行像Item.objects.filter(menu__name='Sandwiches')或Item.objects.filter(menu__name='Salads')这样的查询很简单，但是如果您开始一遍又一遍地编写这些相同的查询，这个过程就会变得令人厌倦并且容易出错。对于原始 SQL 查询来说尤其如此，它需要花费更多的时间来编写，并且具有更高的复杂性。

自定义管理器方法允许您编写一次查询作为模型的一部分，然后调用自定义管理器方法(就像其他模型管理器方法一样(例如，all()、filter()、exclude()))来触发查询。清单 8-61 展示了一个带有定制方法的定制模型管理器类，包括一个使用它的模型，以及各种模型管理器调用。

from django.db import models

# Create custom model manager
class ItemMenuManager(models.Manager):
    def salad_items(self):
        return self.filter(menu__name='Salads')

    def sandwich_items(self):
        return self.filter(menu__name='Sandwiches')    

# Option 1) Override default model manager
class Item(models.Model):
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30)
    ...
    objects = ItemMenuManager()

# Queries on default custom model manager
Item.objects.all()
Item.objects.salad_items()
Item.objects.sandwich_items()

# Option 2) Create new model manager field and leave default model manager as is
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30)
    ...
    objects = models.Manager()
    menumgr = ItemMenuManager()

# Queries on default and custom model managers
Item.objects.all()
Item.menumgr.salad_items()
Item.menumgr.sandwich_items()
# ERROR Item.objects.salad_items() # 'Manager' object has no attribute 'salad_items'
# ERROR Item.objects.sandwich_items() # 'Manager' object has no attribute 'sandwich_items'
Item.menumgr.all()

Listing 8-61.Django custom model manager with custom manager methods

清单 8-61 中的第一个类是作为定制模型管理器的ItemMenuManager。注意这个类是如何从models.Manager类继承它的行为的，这就是它的模型管理器行为。接下来，ItemMenuManager类声明了两个返回QuerySet结果的方法。注意类方法如何引用self——表示模型类实例——并调用标准模型方法来触发数据库查询。

值得一提的是，定制模型管理器不一定需要使用原生模型查询或返回QuerySet数据结构，定制模型管理器同样可以包含任何逻辑(例如 Python DB API 调用)或返回任何数据结构(例如 Python 元组)。

一旦您有了一个定制的模型管理器，有两个选项可以将它分配给一个模型类。第一个选项，如清单 8-61 所示，包括覆盖一个模型的默认模型管理器objects，并显式地为它指定一个定制模型管理器。一旦完成，您就可以使用相同的objects引用来调用定制模型管理器方法。此外，请注意清单 8-61 中的内容，即使覆盖了默认的模型管理器objects，模型仍然可以访问内置的模型管理器方法(例如all()，因为定制模型从父models.Manager类继承了它的行为。

接下来，清单 8-61 展示了集成定制模型管理器的第二种选择。该选项包括添加一个新的模型字段来引用一个自定义管理器，并保持默认管理器objects不变。在这种情况下，定制模型管理器方法通过新的字段引用(例如，Item.menumgr.salad_items())变得可访问，并且objects引用继续以其默认行为工作。

Tip

当在一个模型中声明多个模型管理器时，可以使用 default_manager_name 元选项设置缺省模型管理器。有关模型元选项的更多详细信息，请参见上一章。

Warning

如果在多管理器模型中没有定义默认的模型管理器，Django 会选择模型中声明的第一个管理器。这可能会在模型操作中产生意外行为，这些操作不能显式地选择模型管理器(例如，dumpdata ),这与可以使用点符号选择模型管理器的查询不同。

自定义模型管理器和带有方法的 QuerySet 类

模型管理器与返回QuerySet数据结构的方法紧密相连。正如您所看到的，几乎所有链接到默认模型管理器objects(例如all()、filter())的方法都会生成QuerySet数据结构。当您创建定制模型管理器时，可以覆盖这些QuerySet方法的默认行为，以及创建您自己的定制QuerySet类和方法。

模型管理器中最重要的QuerySet方法之一是get_queryset()方法，用于定义模型的初始QuerySet或模型管理器的all()方法返回的内容。在定制模型管理器中，get_queryset()方法尤其重要，因为它允许您根据模型管理器的目的过滤最初的QuerySet。

清单 8-62 展示了为get_queryset()方法定义定制逻辑的多个定制模型管理器。

class SanDiegoStoreManager(models.Manager):
    def get_queryset(self):
        return super(SanDiegoStoreManager, self).get_queryset().filter(city='San Diego')

class LosAngelesStoreManager(models.Manager):
    def get_queryset(self):
        return super(LosAngelesStoreManager, self).get_queryset().filter(city='Los Angeles')    

class Store(models.Model):
    name = models.CharField(max_length=30)    
    ...
    objects = models.Manager()
    sandiego = SanDiegoStoreManager()
    losangeles = LosAngelesStoreManager()

# Call default manager all() query, backed by get_queryset() method
Store.objects.all()
# Call sandiego manager all(), backed by get_queryset() method
Store.sandiego.all()
# Call losangeles manager all(), backed by get_queryset() method
Store.losangeles.all()

Listing 8-62.Django custom model managers with custom get_queryset() method

清单 8-62 中的前两个类代表定制模型管理器；然而，请注意，与清单 8-61 中的定制模型管理器不同，SanDiegoStoreManager和LosAngelesStoreManager类都定义了get_queryset()方法。在这两种情况下，get_queryset()方法都返回一个通过调用父模型管理器get_queryset()方法(即all())生成的QuerySet——通过super()方法——并根据定制模型管理器的目的(例如，按城市获取商店)对父模型应用一个额外的filter()。

一旦定义了定制管理器，清单 8-62 将定制模型管理器声明为Store模型类中的独立字段。最后，在清单 8-62 中，您可以看到使用all()方法对每个模型管理器的调用，这些调用根据后台get_queryset()方法的逻辑返回适当的过滤结果。

多个定制模型管理器的替代方法是创建一个定制管理器，并依赖一个定制的QuerySet类和方法来执行相同的逻辑，这种技术在清单 8-63 中进行了说明。

class StoreQuerySet(models.QuerySet):
    def sandiego(self):
        return self.filter(city='San Diego')

    def losangeles(self):
        return self.filter(city='Los Angeles')

class StoreManager(models.Manager):
    def get_queryset(self):
        return StoreQuerySet(self.model, using=self._db)

    def sandiego(self):
        return self.get_queryset().sandiego()

    def losangeles(self):
        return self.get_queryset().losangeles()

class Store(models.Model):
    name = models.CharField(max_length=30)    
    ...
    objects = models.Manager()
    shops = StoreManager()

Store.shops.all()
Store.shops.sandiego()
Store.shops.losangeles()

Listing 8-63.Django custom model manager with custom QuerySet class and methods

清单 8-63 中的StoreQuerySet类是一个自定义的QuerySet类，它定义了sandiego()和losangeles()方法，这两个方法都将额外的过滤器应用于其基类QuerySet。一旦有了一个QuerySet类，就有必要将它与一个定制的模型管理器关联起来。在清单 8-63 中，您可以看到StoreManager类表示一个定制的模型管理器，它定义了它的get_queryset()方法来通过定制的StoreQuerySet类设置它的初始数据。

接下来，注意定制模型管理器StoreManager类是如何定义额外的sandiego()和 losangeles()方法的，这两个方法被连接起来以调用定制StoreQuerySet类中同名的方法。

最后，定制模型管理器StoreManager被设置为Store模型类中的shops字段，在这里您可以观察到调用是如何通过shops引用触发定制StoreQuerySet类支持的查询方法的。

尽管清单 8-63 中的技术有助于减少模型管理器的数量，但是如果你仔细查看清单 8-63 ，仍然有相当多的冗余为定制模型管理器和定制QuerySet类声明相似的命名方法。

为了在使用定制模型管理器和定制QuerySet类时减少多余的方法，后一种类型的类提供了as_manager()方法来自动将QuerySet类转换成定制模型管理器，这种技术在清单 8-64 中有所说明。

class StoreQuerySet(models.QuerySet):
    def sandiego(self):
        return self.filter(city='San Diego')

    def losangeles(self):
        return self.filter(city='Los Angeles')

class Store(models.Model):
    name = models.CharField(max_length=30)    
    ...
    objects = models.Manager()
    shops =  StoreQuerySet.as_manager()

Store.shops.all()
Store.shops.sandiego()
Store.shops.losangeles()

Listing 8-64.Django custom model manager with custom QuerySet converted to manager

清单 8-64 中的例子定义了与清单 8-63 中相同的自定义QuerySet类；但是，请注意缺少一个定制的模型管理器类。相反，清单 8-64 中的Store模型定义直接引用了定制的StoreQuerySet类，并在其上调用as_manager()来将QuerySet类转换成模型管理器。最后，注意通过shops引用进行的调用与清单 8-63 中的调用是相同的。以这种方式，如果您使用定制的QuerySet类，清单 8-64 中的技术为您节省了创建显式定制模型管理器的额外工作。

九、Django 模型表单和类视图

在前两章中，您学习了如何使用 Django 模型在关系数据库和 Django 项目之间移动数据。尽管这是 Django 模型的主要目的，但是 Django 模型实现的另一组重要功能并不直接绑定到数据库。

在这一章中，你将学习如何创建与 Django 模型不同的 Django 表单，这个过程进一步扩展了 Django 的 DRY(不要重复自己)原则。您将了解 Django 模型如何生成 Django 表单，包括它的字段、验证，以及将它的数据保存到数据库，所有这些都不需要编写第六章中描述的许多表单搭建逻辑。

接下来，您将了解 Django 基于类的模型视图。虽然你可以继续使用第二章中介绍的 Django 视图技术——就像第六章中的表单技术一样——但是在牢牢掌握 Django 模型之后，你可以进一步将 Django DRY 原则应用到视图中。您将学习如何创建基于类的视图来执行模型 CRUD 操作，从而减少将模型 CRUD 操作合并到视图中所需的逻辑数量。

Django 模型表单结构和工作流程

Django 模型代表了将数据移入和移出数据库的标准方式。但是正如您在前两章中所了解到的，将数据移入和移出数据库的阶段需要您以编程方式操作模型记录(例如，views.py文件中的内部视图方法),以在模型上执行所需的 CRUD 操作。

虽然这对于任何 web 框架来说都是非常有效的工作流，但是您可以通过将 Django 模型链接到更自然的输入/输出机制(表单)来改进将数据移入和移出数据库的过程。

一旦您在实际项目中以编程方式创建了足够多的 Django 模型记录，您将会看到一种模式的出现:大多数 Django 模型操作背后的逻辑是由用户交互决定的。最终用户创建Order模型记录，最终用户读取Store模型记录，管理员更新Menu模型记录，或者管理员删除Item模型记录。这些最终用户和管理员用什么来交流这些模型操作呢？确切地说，是用户界面(UI)中的表单。

现在让我们看看将表单链接到模型的另一面。在第六章中，您学习了 Django 表单，但是您是否意识到在表单数据被处理后，您最有可能对其进行什么操作呢？您最有可能将它保存到数据库中，这涉及到 Django 模型。

因此，本着 Django 的 DRY 原则的精神，模型表单提供了一种使用 Django 模型作为基础来生成 Django 表单以在 Django 模型上执行 CRUD 操作的方法。换句话说，不是创建一个独立的 Django 表单，然后创建必要的“粘合”代码来创建 Django 模型实例，反之亦然，而是创建一个独立的 Django 模型，然后创建必要的表单来对模型记录进行 CRUD 操作，Django 模型表单允许您不重复自己。

创建 Django 模型表单

回到第六章，您创建了一个 Django 表单来获取姓名、电子邮件和评论。接下来，我们将把这个表单重新设计成一个模型表单，以便能够快速地将数据保存到数据库中。

创建模型表单的第一步是创建一个模型作为数据的基础。清单 9-1 展示了一个 Django 模型类，紧接在从模型创建的 Django 模型表单之后。

Tip

参考本书附带的源代码来运行练习，以减少打字和自动访问测试数据。

from django import forms

class Contact(models.Model):
      name = models.CharField(max_length=50,blank=True)
      email = models.EmailField()  
      comment = models.CharField(max_length=1000)

class ContactForm(forms.ModelForm):
      class Meta:      
            model = Contact
            fields = '__all__'

Listing 9-1.Django model class and model form

清单 9-1 的第一个重要方面是 Django 模型遵循标准的模型语法，有三个字段使用模型字段来限制模型存储的数据类型。清单 9-1 中的模型保持简单，以便更好地说明模型形式，但是可以添加你在前两章中学到的任何其他模型功能(例如，验证器、清理方法、元选项)。

清单 9-1 中的下一个是代表表单的ContactForm类，它从django.forms.ModelForm类继承了它的行为，最后一个类使它成为一个模型表单。注意ContactForm类没有任何表单域，就像你在第六章的表 6-2 中学到的那样；相反，它声明了一个类似于模型中使用的Meta类部分。

ContactForm的Meta类部分指定了两个选项:model和fields。model选项指示使用哪个模型来生成表单，在本例中，Contact模型也在清单 9-1 中。fields选项指示使用哪些模型字段来生成表单，在这种情况下，'__all__'告诉 Django 使用模型中的所有模型fields。

清单 9-1 中ContactForm的强大之处在于它使用两条语句创建一个表单，该表单反映了与Contact模型相同的字段类型。这不仅避免了重复(例如，在显式表单域中键入)，表单域还继承了模型的验证行为(例如，models.EmailField()被翻译成forms.EmailField)。但是在我描述完模型表单的基础知识之后，我将很快描述更多关于这个模型到表单继承行为的细节和选项。

一旦有了一个模型表单类，您可能想知道它的处理与标准的 Django 表单有什么不同？实际上很少；你在第六章学到的处理、验证和布局表单的概念对模型表单同样有效，如清单 9-2 所示。

# views.py method to process model form
def contact(request):
    if request.method == 'POST':
        # POST, generate bound form with data from the request
        form = ContactForm(request.POST)
        # check if it's valid:
        if form.is_valid():
            # Insert into DB
            form.save()

            # redirect to a new URL:
            return HttpResponseRedirect('/about/contact/thankyou')
    else:
        # GET, generate unbound (blank) form
        form = ContactForm()
    return render(request,'about/contact.html',{'form':form})

# See chapter 6 for form layout template syntax in about/contact.html

Listing 9-2.Django model form processing

在清单 9-2 中，你可以看到视图方法序列遵循与标准 Django 表单相同的模式。当用户在 view 方法上发出 GET 请求时，会创建一个未绑定表单实例，并发送给用户，并通过about/contact.html模板呈现。接下来，当用户通过 POST 请求提交表单时，使用request.POST参数创建一个绑定表单，然后使用is_valid()方法对其进行验证。如果表单值无效，则有错误的绑定表单被返回给用户，以便他可以纠正错误，如果表单值有效，在清单 9-2 的特定情况下，用户被重定向到/about/contact/thankyou页面。

然而，在清单 9-2 中，模型表单有一个重要的处理差异。在表单的值被确定为有效之后，在模型表单实例上调用save()。这个save()方法被绑定到表单的支持模型save()方法，这意味着表单数据被结构化为模型记录并保存到数据库中。

如您所知，与创建和处理独立的表单和独立的模型相比，创建和处理模型表单的过程节省了大量时间。

Django 模型表单选项和字段映射

现在您已经了解了模型表单的基本操作，让我们来看看它的各种选项。大多数模型表单选项都在元类语句中声明，如清单 9-1 所示。但是，也可以声明常规的表单字段，或者覆盖默认的模型字段行为，或者包含新的表单字段。

模型表单必需选项:模型和字段或排除

模型表单从forms.ModelForm类继承它们的行为——而不是标准的forms.Form类——因此 Django 总是期望表单基于一个模型，这就是元model选项的目的。因此model选项值总是模型表单的一个要求。

Django 并不期望模型的结构与表单完美匹配，Django 还期望您明确告诉它支持模型的哪些字段应该或不应该成为模型表单的一部分。这可以通过fields选项——指示哪些模型字段成为模型表单的一部分——或exclude选项——指示哪些模型字段不应该成为模型表单的一部分来实现。总是需要fields或exclude选项，即使模型表单将包含支持模型的所有字段。注意清单 9-1 中的模型表单示例是如何声明选项fields='__all__'来创建一个模型表单，该表单捕获与它的支持模型相同的一组字段。

当您使用除了fields='__all__'(例如，模型字段的缩短列表)或exclude选项(例如，要在表单中省略的模型字段的列表)之外的东西来声明模型表单时，请注意您是有意地并且潜在地违反了模型的规则。例如，默认情况下，所有的模型字段都是必需的，因此如果您创建一个省略了某些字段的模型表单——使用fields或exclude——表单本身可以正常显示，但是模型表单永远不会成功完成其标准工作流，除非您手动添加这些省略的字段。在这种情况下，最终用户将看到“无效表单错误”，因为表单的模型部分由于所需的模型字段值而被破坏。关于模型表单验证和初始化的下一节将描述如何向模型表单中手动添加省略的字段值。

正如您所看到的，您可以创建一个比它的支持模型有更多或更少字段的模型表单。此外，还可以向模型表单添加新的字段——它不是支持模型的一部分——以及定制由模型字段生成的默认表单字段。

为了描述最后两种情况的解决方案，下一节将描述由每个模型字段生成的不同表单字段——这样您就可以确定是否需要自定义默认行为——随后的一节将描述如何自定义和向模型表单添加新字段。

模型表单默认字段映射

模型表单遵循一定的规则将表 7-1 中描述的模型字段数据类型转换为表 6-2 中描述的表单字段数据类型。在大多数情况下，模型字段数据类型被转换成镜像等价的表单字段数据类型。例如，如果模型字段使用models.CharField数据类型，则模型表单会将该字段转换为forms.CharField数据类型。

表 9-1 说明了模型数据类型和表单数据类型之间使用的模型表单映射。请注意，模型和表单之间具有镜像数据类型映射的数据类型包含在表 9-1 的第一行中。

表 9-1。

Model form data type mapping between models and forms

| 模型字段 | 表单字段 | | --- | --- | | 模特。布尔菲尔德 | 表格。布尔菲尔德 | | 模特。日期字段 | 表格。日期字段 | | 模特。日期 | 表格。日期 | | 模特。德西马菲尔德 | 表格。德西马菲尔德 | | 模特。邮箱 | 表格。邮箱 | | 模特。文件字段 | 表格。文件字段 | | 模特。文件路径字段 | 表格。文件路径字段 | | 模特。浮田 | 表格。浮田 | | 模特。像场 | 表格。像场 | | 模特。整数 | 表格。整数 | | 模特。IP 地址字段 | 表格。IP 地址字段 | | 模特。GenericIPAddressField | 表格。GenericIPAddressField | | 模特。NullBooleanField | 表格。NullBooleanField | | 模特。斯拉格菲尔德 | 表格。斯拉格菲尔德 | | 模特。时间字段 | 表格。时间字段 | | 模特。URLField | 表格。URLField | | 模型。自动字段模型。BigAutoField | 不在表单中显示，因为自动建模字段是由数据库生成的。 | | 模特们。毕希菲尔德 | 表格。IntegerField，最小值设置为-9223372036854775808，最大值设置为 9223372036854775807) | | 模特。类型 | 表格。CharField，如果 null=True，max_length 设置为模型字段的 max_length，empty_value 设置为 None | | 模特。CommaSeparatedIntegerField | 表格。类型 | | 模特。外键 | 表格。模型选择字段 | | 模特。多对多字段 | 表格。模型多重选择字段 | | 模特。正积分域 | 表格。整数字段，min_value 设置为 0 | | 模特。PositiveSmallIntegerField | 表格。整数字段，min_value 设置为 0 | | 模特。SmallIntegerField | 表格。整数 | | 模特。文本字段 | 表格。CharField，with widget=forms。文本区域 |

正如你在表 9-1 中看到的，超过 50%的 Django 模型数据类型直接映射到等价的表单数据类型。大多数剩余的模型数据类型映射到稍微调整的表单数据类型，以更好地适应支持模型类型(例如，models.PositiveIntegerField映射到forms.IntegerField，但是表单min_value值为 0)。

只有表 9-1 中的四种模型数据类型没有直接映射到表 6-2 中第六章描述的表单数据类型。models.AutoField和models.BigAutoField模型数据类型从不在模型表单中表示，原因很简单，它们的值是由数据库自动分配的，所以它们在表单中没有输入位置。models.ForeignKey和models.ManyToManyField模型数据类型代表模型关系，这意味着它们的数据来自不同的模型。反过来，models.ForeignKey和models.ManyToManyField模型数据类型不映射到字符串或数字的常规表单字段，而是映射到表示其他模型数据的表单字段，这就是特殊表单数据类型:forms.ModelChoiceField和forms.ModelMultipleChoiceField的用途。这最后两个表单字段将在后面的带有关系的模型表单小节中描述。

Tip

要查阅表单域数据类型产生的 HTML(如查阅表 6-2 ，其中包含表单域和表单小部件之间的映射，最后一个小部件产生实际的表单 HTML 标记。

模型表单新的和定制的字段:小部件、标签、帮助文本、错误消息、字段类和本地化字段

现在您已经知道了如何将所有模型字段转换为模型表单中的表单字段，让我们来解决如何在模型表单中添加和自定义表单字段的问题。

向模型表单添加新的表单域就像声明一个表单域一样简单，就好像它是一个常规表单一样。还可以自定义模型字段数据类型使用的默认表单字段数据类型(即表 9-1 中的映射)，方法是声明一个与模型字段同名的新表单字段，使其优先于默认的模型-表单字段映射。

清单 9-3 展示了清单 9-1 中的 Django 模型类和模型表单，更新后包括了一个新的表单字段和一个覆盖默认模型表单字段映射的表单字段。

from django import forms

def faq_suggestions(value):
      # Validate value and raise forms.ValidationError for invalid values
      pass     

class Contact(models.Model):
      name = models.CharField(max_length=50,blank=True)
      email = models.EmailField()  
      comment = models.CharField()

class ContactForm(forms.ModelForm):
      age = forms.IntegerField()

      comment = forms.CharField(widget=forms.Textarea,validators=[faq_suggestions])

      class Meta:      
            model = Contact
            fields = '__all__'

Listing 9-3.Django model form with new and custom field

清单 9-3 首先添加了新的age表单字段来捕获表单中的整数值。尽管底层的Contact模型从来不知道age字段或值，但通过这种修改，模型表单将要求该字段作为表单工作流的一部分提供。

清单 9-3 中的下一个是comment表单字段，它覆盖了同名的底层模型字段。在这种情况下，覆盖comment表单字段的目的是添加一个自定义的widget，以及添加一个自定义的validators方法，以便在表单被认为有效之前验证comment值——注意widget和validators选项都是第六章中描述的标准表单选项。

清单 9-3 中的表单域覆盖机制有优点也有缺点。这样做的好处是您可以完全控制表单域来定义任何选项。缺点是传递给表单域的模型域选项(如max_length)丢失，需要作为新表单域语句的一部分重新声明。

为了保留模型字段的底层行为并仍然能够定制某些表单字段选项，除了model、fields和exclude选项之外，模型表单还支持额外的元类选项。清单 9-4 展示了一个模型表单的附加元选项来覆盖默认的模型表单字段映射，同时保持底层的模型字段行为。

from django import forms

class Contact(models.Model):
      name = models.CharField(max_length=50,blank=True)
      email = models.EmailField()  
      comment = models.CharField()

class ContactForm(forms.ModelForm):
      class Meta:      
            model = Contact
            fields = '__all__'
            widgets = {

               'name': models.CharField(max_length=25),

               'comment': form.Textarea(attrs={'cols': 100, 'rows': 40})

            }

            labels = {

               'name': 'Full name',

               'comment': 'Issue'

            }

            help_texts = {

               'comment': 'Provide a detailed account of the issue to receive a quick answer'

            }

            error_messages = {

               'name': {

               'max_length': "Name can only be 25 characters in length"

                }

            }

            field_classes = {

               'email': EmailCoffeehouseFormField

            },

            localized_fields = '__all__'

Listing 9-4.Django model form with meta options to override default form field behavior

清单 9-4 中的元模型表单选项最重要的方面是它们是表单域选项的复数名称，在第六章中有描述。清单 9-4 中突出显示的模型表单元选项是复数的，因为它们可以将多个表单字段的选项声明为一个字典，其中每个键代表表单字段名称，其值代表选项值。

例如，清单 9-4 中的widgets和labels元选项为name和comment模型表单字段定义了定制部件和标签。help_texts元选项为comment模型表单字段定义了help_text选项，而error_messages元选项为name模型表单字段上的max_length键错误声明了一个定制表单错误消息。

接下来，清单 9-4 中的field_classes元选项用于为email模型表单字段声明一个定制表单字段。最后，清单 9-4 中的localized_field元选项被设置为__all__以告诉 Django 本地化(即转换成不同的语言)所有模型表单字段。如果省略了localized_field选项，那么模型表单字段不会被本地化。值得一提的是，您可以通过将模型表单字段的列表传递给localized_field选项来选择性地本地化某些模型表单字段，就像使用fields和exclude选项一样。

有关系的 Django 模型表单

正如您在前两章中所了解到的，Django 模型之间可以有关系，这反过来使得模型具有引用另一个模型中的记录的数据类型(例如，ForeignKey，ManyToManyField)。

当在模型表单的上下文中使用包含这种数据类型的模型时，Django 依赖于两个特殊的表单字段。默认情况下，ForeignKey模型字段转换为ModelChoiceField表单字段，ManyToManyField模型字段转换为ModelMultipleChoiceField表单字段。

ModelChoiceField和ModelMultipleChoiceField表单字段的好处是它们基于 Django 模型查询生成表单字段。因此，ModelChoiceField和ModelMultipleChoiceField表单域生成一个包含模型记录的友好的 HTML <select>/<option>输入域，而不是用模型数据手工填充表单域。

模型选择字段和模型多重选择字段表单字段选项:queryset、empty_label、to_field_name 和 label_from_instance

Tip

ModelChoiceField和ModelMultipleChoiceField是标准表单字段，可用于任何需要模型数据的 Django 表单。默认情况下，它们被用在有关系的模型表单上，但是它们并不局限于模型表单(即，从forms.ModelForm继承的表单)。

Note

ModelChoiceField和ModelMultipleChoiceField是标准表单字段(即 Django forms包的一部分)，也接受标准表单选项:必填、小部件、标签、初始、help_text 和 limit _ choices _ to——如第六章所述。

由于ModelChoiceField和ModelMultipleChoiceField表单字段使用模型记录来获取数据，因此它们明确需要模型查询。对于从forms.ModelForm继承其行为的模型表单，它们的基础模型包含一个ForeignKey或ManyToManyField模型字段，这个模型查询是自动设置的。例如，如果一个Item模型包含一个ForeignKey到一个Menu模型，一个Item模型表单在一个表单中显示所有的Menu记录，允许用户选择一个单独的Menu记录。类似地，如果一个Store模型包含一个ManyToManField到一个Amenity模型，一个Store模型表单在一个表单中呈现所有的Amenity记录，允许用户选择多个Amenity记录。

虽然这种行为在大多数情况下是可以接受的，但当您需要过滤默认行为以使用模型表单字段上的所有模型记录时，或者当这些表单字段用于常规表单(即继承了forms.Form)时，可能有必要提供对ModelChoiceField或ModelMultipleChoiceField表单字段的显式查询。

清单 9-5 展示了使用queryset选项在ModelChoiceField和ModelMultipleChoiceField表单字段上设置模型查询的两种技术。

from django import forms
from coffeehouse.stores.models import Amenity

class Menu(models.Model):
    name = models.CharField(max_length=30)
    def __str__(self):
        return "%s" % (self.name)

class Item(models.Model):
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)

class ItemForm(forms.ModelForm):
    menu = forms.ModelChoiceField(queryset=Menu.objects.filter(id=1))

    class Meta:       
        model = Item
        fields = '__all__'

class StoreForm(forms.Form):
    name = forms.CharField()    
    address = forms.CharField()
    amenities = forms.ModelMultipleChoiceField(queryset=None)

    def __init__(self, *args, **kwargs):
        super(StoreForm, self).__init__(*args, **kwargs)
        self.fields['amenities'].queryset = Amenity.objects.filter(name__contains='W')

Listing 9-5.Django model form and standard form with custom query for ModelChoiceField and ModelMultipleChoiceField form fields

清单 9-5 中的第一项技术通过用ItemForm模型表单上的自定义ModelChoiceField()覆盖menu字段来定义内联queryset值。在这种情况下，不是ItemForm模型表单有一个包含所有Item记录的menu字段，而是将menu字段限制为只有包含id=1的Item记录。

清单 9-5 中的第二项技术在标准表单上定义了一个空的queryset值，该表单在amenities字段上使用了一个forms.ModelMultipleChoiceField()表单字段。但是在表单的__init__方法中，amenities字段被设置为一个查询，该查询将其记录限制为包含字母W的Amenity记录。

值得一提的是，清单 9-5 中展示的两种queryset技术在模型表单和常规表单中同样有效，同样有效的还有ModelChoiceField()和ModelMultipleChoiceField()表单字段。

默认情况下，不定义initial值的ModelChoiceField()表单字段生成时会将空的 HTML <option>---------</option>选项作为默认字段值。可以通过empty_label选项自定义该空选项的值(例如empty_label='Please select a value'，输出<option>Please select a value</option>)。也可以用empty_label=None禁用这个空选项。

默认情况下，ModelChoiceField()和ModelMultipleChoiceField()表单字段都从模型记录的主键值(即id)和模型__str__方法表示)生成它们的 HTML <select>/<option>输入字段值。例如，给定清单 9-5 中的Menu模型定义，该模型的 HTML <select>/<option>输入字段将如下所示:

<select name="menu" required id="id_menu">
     <option value="" selected>---------</option>
     <option value="1">Breakfast</option>
     <option value="2">Salads</option>
     <option value="3">Sandwiches</option>
     <option value="4">Drinks</option>
</select>

注意每个<option> value对应一个记录的主键id值，而<option>文本对应一个由模型的__str__方法返回的记录的name字段。

可以使用to_field_name选项定制ModelChoiceField()和ModelMultipleChoiceField()表单字段中使用的<option> value。例如，在最后一个代码片段的上下文中设置to_field_name='name'，将 HTML <select>/<option>输入字段更改为格式<option value="Breakfast">Breakfast</option>。

Caution

使用 to_field_name 值会破坏基础模型表单保存到数据库的能力，因为模型的关系值被设置为与模型关系所期望的主键不同的值。

除了定制<option> value之外，通过覆盖ModelChoiceField()和ModelMultipleChoiceField()表单域中的label_form_instance方法，还可以将表单域中的<option>文本定制为除模型的__str__方法之外的东西。清单 9-6 展示了一个为此目的设计的定制表单域。

from django import forms
from django.forms import ModelChoiceField

class MenuModelChoiceField(ModelChoiceField):
    def label_from_instance(self, obj):
        return "Menu #%s) %s" % (obj.id,obj.name)

class ItemForm(forms.ModelForm):
    menu = MenuModelChoiceField(queryset=Menu.objects.all())
    class Meta:      
        model = Item
        fields = '__all__'

# HTML menu form field output
<select name="menu" id="id_menu" required>
  <option value="" selected>---------</option>
  <option value="1">Menu #1) Breakfast</option>
  <option value="2">Menu #2) Salads</option>
  <option value="3">Menu #3) Sandwiches</option>
  <option value="4">Menu #4) Drinks</option>
</select>

Listing 9-6.Django custom form field to customize <option> text for ModelChoiceField and ModelMultipleChoiceField form fields

清单 9-6 中的第一步创建了从ModelChoiceField表单域继承其行为的MenuModelChoiceField定制表单域，并定义了label_from_instance方法的实现。在这种情况下，label_from_instance方法告诉 Django 生成以Menu #静态字符串为前缀的<option>文本值，后跟模型的id和name。注意同样的技术可以用来定制一个ModelMultipleChoiceField，只要确保改变定制表单域的继承类。

接下来，通过menu字段将清单 9-6 中的MenuModelChoiceField定制表单字段添加到同一清单中的ItemForm模型表单中。因为MenuModelChoiceField是一个定制的ModelChoiceField表单字段，所以有必要指定一个显式的queryset值来填充表单字段，在本例中，它对应于所有的Menu模型记录。

最后，清单 9-6 展示了menu字段的 HTML <option>文本输出遵循自定义MenuModelChoiceField自定义表单字段中定义的模式。

Django 模型表单处理

现在您已经对各种模型表单选项有了坚实的理解，是时候更深入地了解模型表单处理了，这在清单 9-2 中有简要介绍。

在处理模型表单时要考虑的最重要的因素是您正在处理两个实体:表单和模型。在清单 9-2 中展示的模型表单处理示例中，这个事实并不太明显，主要是因为表单完全符合支持模型。但是，当您修改任何模型表单部件时，使用表示表单和模型的单个引用可能需要更多的考虑。

模型表单初始化:初始和实例

模型表单可以使用两个初始化参数:initial和instance。initial参数的工作方式就像标准的initial表单参数——在第六章中描述——为未绑定表单提供初始值。instance参数用于用一个模型实例初始化一个模型窗体，该模型实例也用于初始化一个未绑定窗体的值。

在所有的模型表单中，正如您在前面章节中所学的，表单定义优先于任何底层的模型定义。这意味着initial参数中的所有模型表单值优先于通过instance参数定义的值。清单 9-7 显示了使用initial和instance参数的模型表单初始化序列。

from coffeehouse.items.models import Item

preloaded_item = Item.objects.get(id=1)

# Model form from Listing 9-6, initialize with instance
form = ItemForm(instance=preloaded_item)

# Unbound form set up with instance values
form.as_p()
  <p>
   <label for="id_menu">Menu:</label>
        <select name="menu" required id="id_menu">
            <option value="">---------</option>     
            <option value="1" selected>Menu #1) Breakfast</option>

            <option value="2">Menu #2) Salads</option>
            <option value="3">Menu #3) Sandwiches</option>
            <option value="4">Menu #4) Drinks</option>
         </select>
  </p>
  <p>
    <label for="id_name">Name:</label>
          <input type="text" name="name"
               value="Whole-Grain Oatmeal" required maxlength="30" id="id_name" />
    </p>
    # Remaining fields committed for brevity

# Model form from Listing 9-6, initialize with instance and override with initial
form2 = ItemForm(initial={'menu':3},instance=preloaded_item)

# Unbound form set up with instance values
form2.as_p()

# Unbound form set up with instance values, but overridden with initial
form2.as_p()
  <p>
   <label for="id_menu">Menu:</label>
        <select name="menu" required id="id_menu">
            <option value="">---------</option>     
            <option value="1">Menu #1) Breakfast</option>
            <option value="2">Menu #2) Salads</option>
            <option value="3" selected>Menu #3) Sandwiches</option>

            <option value="4">Menu #4) Drinks</option>
         </select>
  </p>
   # Remaining fields committed for brevity

Listing 9-7.Django model form initialization with initial and instance

清单 9-7 中的第一步是获取一个Item模型记录来填充ItemForm模型表单；在这种情况下，进行查询以获得带有id=1的Item模型记录。接下来，Item模型记录被用来用实例值初始化模型表单。在清单 9-7 中，表单是用标准的as_p()表单方法输出的，您可以确认表单字段是预先选择的，以反映底层的模型记录。

清单 9-7 中的下一个是同一个ItemForm模型表单的初始化序列，但是它也结合使用了initial参数和instance参数。在这种情况下，因为initial参数提供了'menu':3值，所以未绑定表单的menu字段被设置为值3，而不是模型记录的实例menu值1。从而确认initial参数值优先于instance参数值。

注意，只使用initial参数——而不使用instance参数——来初始化一个模型表单，就像它是一个常规表单一样，这同样有效。在模型表单的初始化阶段，表单的模型部分不知道任何值，直到模型表单进入验证阶段，底层模型才知道任何表单值。

模型表单验证

与模型表单初始化类似，模型表单验证可能看起来是交织在一起的，因为您处理的是一个既引用表单又引用模型的变量。但是只要你知道表单验证的基本步骤——在第六章中描述——和模型验证——在第七章中描述——模型表单验证就很简单。

回到清单 9-2 ，您学习了如何通过在视图方法(例如ContactForm(request.POST))中传递request.POST值来将模型表单转换为绑定表单(即包含用户数据的表单)。一旦有了绑定表单，标准的 Django 表单验证工作流就会继续应用于模型表单:对表单引用调用is_valid()方法，根据表单验证规则验证用户提交的数据。如果有任何表单规则不符合，一个errors字典将被添加到表单引用中，并给出原因，它将作为一个重新呈现的有错误的表单返回给用户。如果is_valid()方法成功，模型表单的处理逻辑就可以进入下一步。

一旦模型表单通过了is_valid()方法测试，您实际上可以使用相同的标准表单cleaned_data()方法来访问包含有效表单数据内容的字典(例如，form.cleaned_data()包含{'name': '...','email': '...','comment': '...', })。但是由于您使用的是模型表单，您更可能采取的步骤是使用表单数据来进一步与模型进行交互。

为了促进这一过程，Django 向表单引用添加了instance字段，其中包含了作为模型表单底层模型实例的表单数据。当您在尝试模型操作之前需要或必须操作模型数据时,instance字段尤其重要。这是模型表单验证过程中最关键的方面:即使在表单is_valid()方法通过并且数据被用于在instance字段中构造模型实例之后，这个模型实例数据仍然必须经过模型验证，否则就有被支持的模型验证规则拒绝的风险。

对于简单的模型表单场景，其中模型和表单直接相互映射——如清单 9-2 中所示——操纵instance字段是不必要的(例如，在表单is_valid()方法传递之后，您可以调用form引用上的save()方法来将模型实例保存在instance中)。但是对于模型和表单在字段数量上不同的模型表单，您需要在表单is_valid()方法传递之后和调用模型表单的save()方法之前执行额外的逻辑。

清单 9-8 展示了模型表单的两个验证过程，其中表单省略了底层模型中的字段。

from django import forms
from django.conf import settings

class Contact(models.Model):
      user = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, default=None)

      name = models.CharField(max_length=50,blank=True)
      email = models.EmailField()  
      comment = models.CharField()

class ContactForm(forms.ModelForm):
      class Meta:      
            model = Contact
            exclude = ['user']

# Option 1) Form model processing with missing value assigned with instance
         if form.is_valid():
            # Check if user is available
            if request.user.is_authenticated():

                # Add missing user to model form
                form.instance.user = request.user

            # Insert into DB
            form.save()

# Option 2) Form model processing with missing value assigned after model form sequence
            if form.is_valid():
            # Save instance but don't commit until model instance is complete
            # form.save() returns a materialized model instance that has yet to be saved
            pending_contact = form.save(commit=False)

             # Check if user is available
            if request.user.is_authenticated():

                # Add missing user to model form
                pending_contact.user = request.user

            # Insert into DB
            pending_contact.save()

Listing 9-8.Django model form with reduced form that requires model update before saving

清单 9-8 中的Contact模型类似于前面清单中使用的模型类，但是有额外的user字段来注册 Django 用户作为模型记录的一部分。接下来，在清单 9-8 中是ContactForm模型表单——基于最后一个Contact模型——它使用exclude选项从表单中省略user模型字段。

因为您有意从模型表单中省略了user字段，最终用户将无法提供它——即使在不太可能的情况下，他也知道他的内部用户。因此，作为验证过程的一部分，有必要更新模型以包含内部用户，这在视图方法的request引用中总是可用的。

在清单 9-8 中的第一个验证序列中，您可以看到在模型表单通过is_valid()方法后，会进行一个快速检查来确认用户是否通过了身份验证；如果是，则访问模型的instance引用来更新user模型字段。一旦完成，模型表单的支持实例包含一个被省略的user字段的值，并且在调用save()方法时，模型记录与它的所有模型字段的值一起被保存。

清单 9-8 中的第二个验证序列使用commit=False来具体化模型表单的模型实例，而不将其保存到数据库中。一旦完成了这些，模型表单的工作也就完成了，这样就剩下一个需要更新并保存到数据库中的基本模型记录实例。您可以在清单 9-8 中看到，进行了相同的检查来确认用户是否通过了身份验证，如果是，则更新未保存的模型记录user引用，并最终调用模型的save()方法将记录提交给数据库。

Django 模型表单集

正如标准的 Django 表单可以作为一个集合组合在一起成为一个表单集一样，Django 模型表单也可以组合成一个模型表单集。类似地，正如 Django 模型表单类似于标准 Django 表单一样，模型表单集也与标准表单集有很多相似之处。

接下来，我将基于第六章最后一部分介绍的关于标准表单集的知识来描述模型表单集的特性。因此，如果您不熟悉表单集术语(例如，工厂和管理表单)，请回过头来阅读最后一节，因为下面的内容假设您已经了解这些基本的表单集概念。

模型表单集工厂

modelformset_factory()方法是使用模型表单集的核心。modelformset_factory()方法最多可以接受 19 个参数，其中 9 个与标准表单集相同，其余的特定于模型表单集。下面的代码片段展示了modelormset_factory()方法中每个参数的所有名称和默认值，粗体文本代表模型表单集特定选项。

modelformset_factory(model, queryset=model.objects.all(),
                    form=ModelForm,fields=None, exclude=None,
                  formset=BaseModelFormSet, extra=1, can_order=False, can_delete=False,
                  max_num=None, min_num=None, validate_max=False, validate_min=False,
                  widgets=None, localized_fields=None,labels=None,
                  help_texts=None, error_messages=None,
                  field_classes=None,formfield_callback=None)

正如您可以在这个代码片段中确认的那样，modelformset_factory()方法唯一需要的参数(即没有默认值)是model。每个参数的含义如下:

model。-定义要在其上创建表单集的模型类。

queryset。-定义 queryset 以创建表单集。默认情况下，所有的模型记录都被用来创建表单集(即model.objects.all() queryset，如果使用的话)。

fields。-定义模型表单字段作为模型的一部分，以创建模型表单集–就像fields元模型表单选项一样。

exclude。-定义要作为模型的一部分省略的模型表单字段，以创建模型表单集-就像exclude元模型表单选项一样。

widgets。-为模型表单定义覆盖小部件以创建模型表单集——就像widgets元模型表单选项一样。

localize_fields。-定义要本地化的模型表单字段(即支持多种语言)以创建表单集–就像localize_fields元模型表单选项一样。

labels。-为模型表单定义覆盖标签以创建模型表单集–就像labels元模型表单选项一样。

help_text。-为模型表单定义覆盖帮助文本以创建模型表单集-就像help_texts元模型表单选项一样。

error_messages。-为模型表单定义覆盖错误消息，以创建模型表单集–就像help_texts元模型表单选项一样。

field_classes。-为模型表单定义覆盖字段类以创建模型表单集——就像field_classes元模型表单选项一样。

formsetfield_callback。-定义在从模型字段创建表单字段之前要执行的方法。通常用于在表单集的上下文中自定义模型表单字段，如前面的模型表单部分所述。

Tip

参见第六章了解额外模型表单集 _ 工厂选项的详细信息，该选项已在标准表单集章节中描述。

鉴于模型表单集逻辑是前面描述的模型表单技术和第六章中描述的表单集技术的结合，我不会再重复同样的技术。你可以查看这本书的源代码，在online应用下的第九章的源代码中找到一个工作模型表单集的例子。

带有模型的基于类的视图

回到第二章，您学习了基于类的视图如何允许您创建符合面向对象编程(OOP)原则(例如封装、多态和继承)的视图，从而提高可重用性并缩短实现时间。现在你已经知道 Django 模型是如何工作的，我们可以处理基于类的视图，这些视图与表 2-10 的最后一部分描述的模型相集成。

不同于标准的 Django 视图(在第二章的前几节中讨论过)允许开放式逻辑处理请求并生成响应，基于类的模型视图以更模块化的方式封装了针对 Django 模型执行的逻辑。

例如，在标准视图方法中创建、读取、更新和删除模型实例的逻辑模式通常遵循非常一致的工作流:从 url 或表单中获取输入数据，对模型执行 CRUD 操作，然后将响应发送给模板。

本着 Django 的 DRY 原则，基于类的模型视图提供了一种减少标准视图方法中使用的样板代码的方法，并使用类字段和方法来定义用于 Django 模型 CRUD 操作的工作流。

使用基于类的视图 CreateView 创建模型记录

到目前为止，您已经了解到，在实际项目中创建 Django 模型实例伴随着一系列的构造，包括模型表单、GET/POST 请求处理、模板的使用等等。

Django CreateView基于类的视图是专门为减少创建模型记录所需的样板代码而设计的。清单 9-9 展示了使用CreateView类的基于类的视图。

# views.py
from django.views.generic.edit import CreateView
from .models import Item, ItemForm
from django.core.urlresolvers import reverse_lazy

class ItemCreation(CreateView):
    model = Item
    form_class = ItemForm
    success_url = reverse_lazy('items:index')

# models.py
from django import forms
from django.db import models

class Menu(models.Model):
    name = models.CharField(max_length=30)

class Item(models.Model):
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)

class ItemForm(forms.ModelForm):
    class Meta:
        model = Item
        fields = '__all__'
        widgets = {
            'description': forms.Textarea(),
        }

# urls.py
from django.conf.urls import url
from coffeehouse.items import views as items_views

urlpatterns = [
    url(r'^new/$', items_views.ItemCreation.as_view(), name='new'),
]

# templates/items/item_form.html
    <form method="post">
        {% csrf_token %}
        {{ form.as_p }}
        <button type="submit" class="btn btn-primary">Create</button>
    </form>

Listing 9-9.Django class-based view with CreateView to create model records

清单 9-9 的第一部分展示了基于ItemCreation类的视图，它从CreateView类继承了它的行为。注意这个视图缺少一个request引用、处理逻辑或者return语句，所有这些在第二章描述的标准视图方法中都很常见。那么ItemCreation基于阶级的观点实际上在做什么呢？

因为您预先知道您想要创建一个模型记录，所以由基于ItemCreation类的视图使用的CreateView类支持所有必要的样板文件逻辑，并且需要最少的代码集来实现它的模型记录创建逻辑。

清单 9-9 中的ItemCreation基于类的视图使用model字段告诉 Django 创建Item模型记录。此外，form_class字段指定了ItemForm表单——也在清单 9-9 中声明——用于创建模型记录。此外，当模型记录创建成功时，success_url字段用于将控制权返回给item:index url。

Why Reverse_Lazy in Class-Based Views, Instead of Reverse?

由于基于类的视图中模型、视图和 url 的同时导入顺序，使用标准的 reverse()方法来解析 URL 名称可能会导致错误:django . core . exceptions . improperly configured:包含的 URLconf '–-'中似乎没有任何模式。如果您在文件中看到有效的模式，那么问题可能是由循环导入引起的。

reverse_lazy 方法确保只有在所有模型、视图和 url 都被正确导入之后才尝试任何反向 URL 名称解析；因此，这是基于类的视图环境中的常见选择。

您可能仍然会疑惑，如果清单 9-9 中的ItemCreation基于类的视图正在创建模型记录，那么它的save()和is_valid()方法在哪里？默认情况下没有。因为您只想创建一个模型记录，所以父类CreateView负责这个支持逻辑。

清单 9-9 中的下一部分包含了带有钩子的urly.py文件，用于在应用中设置基于类的视图。在这种情况下，ItemCreation基于类的视图被设置为在/new url 上运行，并通过使用基于类的视图as_view()方法被声明为url()方法的一部分——注意，这种 url 设置技术对所有基于类的视图都是相同的，并在第二章末尾对无模型的基于类的视图进行了描述。

那么当用户访问/new url 时会发生什么呢？控制被发送到ItemCreation基于类的视图。因为这个视图的目的是创建一个Item模型记录，所以基于类的视图在遵循约定<app_name>/<model_name>_form.html的项目的TEMPLATES目录路径下寻找一个呈现表单的模板。

在清单 9-9 的最后一部分，您可以看到模板templates/items/item_form.html，其中templates表示一个TEMPLATES目录路径值，items表示应用名称，item表示为基于类的视图定义的模型名称。此外，请注意item_form.html模板的内容使用了标准的表单布局，您可以像任何 Django 表单一样对其进行调整。

那么清单 9-9 中的 POST 表单处理程序和错误处理在哪里呢？默认情况下，也没有。一旦用户得到清单 9-9 底部所示的未绑定表单，表单处理和验证就由ItemCreation基于类的视图在幕后处理。如果表单包含错误，模板将被重新呈现——像任何其他表单一样——使用清单 9-9 中的相同模板。如果表单数据有效，表单处理被认为是成功的，基于类的视图创建一个Item模型记录——类似于模型表单——将控制重定向到基于类的视图success_url字段中定义的item:index url。

正如您在这个例子中看到的，从CreateView类继承其行为的基于类的视图减少了创建模型记录所需的样板代码。

创建视图字段和方法

虽然乍一看，从CreateView类继承其行为的基于类的视图可能显得不灵活，但是可以像任何 Django 构造一样覆盖其默认行为。

事实证明，CreateView类从许多其他基于 Django 类的视图中继承了它的行为，这就是赋予了CreateView类及其实现子类(如清单 9-9 中基于类的视图)幕后的力量。CreateView类从以下基于类的视图类继承其行为:

django.views.generic.detail.SingleObjectTemplateResponseMixin
django.views.generic.base.TemplateResponseMixin
django.views.generic.edit.BaseCreateView
django.views.generic.edit.ModelFormMixin
django.views.generic.edit.FormMixin
django.views.generic.detail.SingleObjectMixin
django.views.generic.edit.ProcessFormView
django.views.generic.base.View

那么，为什么这些课程如此重要呢？因为它们为所有基于类的视图提供了默认行为。清单 9-9 中的ItemCreation基于类的视图中声明的稀疏字段对于CreateView基于类的视图来说只有三个字段。可以声明十几个以上的字段和方法——属于这个过去的类列表——来提供行为，比如使用另一个模板而不是<app_name>/<model_name>_form.html；指定响应的内容类型(例如，text/csv)；模型表单有效或无效时运行的自定义方法；以及声明自定义方法来手动执行 GET 和 POST 工作流逻辑。

Note

基于类的视图从它的父类继承了许多字段和方法。以下选项是最常见的选项；要获得详尽的列表，请查阅每个CreateView父类。

基本的 CreateView 选项:模型、form_class 和 success_url 字段

正如您已经在清单 9-9 中看到的，基于CreateView类的视图实现的基本逻辑是使用一个表单创建一个模型记录，这反过来需要一组基本的参数。首先，model字段是整个操作的基础，因为基于CreateView类的视图必须预先知道要创建哪种类型的模型记录。其次，form_ class也是一个基本参数，因为必须向用户提供一个表单来捕获数据以创建模型记录。

最后，因为成功地创建一个模型记录需要通知用户这个动作并离开表单页面，所以success_url字段也是一个基于CreateView类的视图的基本部分，用来指示在创建一个模型记录后将用户重定向到哪里。

定制模板名称、MIME 类型和上下文:模板名称和内容类型字段以及 get_context_data()方法

有时依赖于CreateView基于类的视图模板命名约定<app_name>/<model_name>_form.html是不可行的，要么是因为您有一个预先存在的模板可以重用，要么是因为您不喜欢默认约定。您可以将template_name字段声明为基于CreateView类的视图的一部分来覆盖这个约定。类似地，也可以覆盖基于类的视图响应所使用的默认 MIME 类型——如果模板包含除了text/html(例如text/csv)之外的东西——使用content_type字段作为CreateView基于类的视图的一部分。

此外，您可以通过定义get_context_data()方法的实现来改变传递给基于类的视图模板的上下文数据。当你需要传递额外的数据到一个模板——除了form引用——或者改变实际的form引用到另一个名字时，最后一个过程是很常见的。

清单 9-10 展示了一个基于CreateView类的视图，它利用了template_name和content_type字段，以及get_context_data()方法。

# views.py
from django.views.generic.edit import CreateView
from .models import Item, ItemForm, Menu

class ItemCreation(CreateView):
    template_name = "items/item_form.html"

    context_type = "text/html"

    model = Item
    form_class = ItemForm
    success_url = reverse_lazy('items:index')
    def get_context_data(self,**kwargs):

        kwargs['special_context_variable'] = 'My special context variable!!!'

        context = super(ItemCreation, self).get_context_data(**kwargs)

        return context        

Listing 9-10.Django class-based view with CreateView with template_name, content_type

, and get_context_data()

您可以在清单 9-10 中看到，template_name和content_type字段被声明为基于类的视图的一部分。在这种特殊情况下，为简单起见，两个字段值都被赋予默认值，使它们变得多余；但是您可以根据自己的需要进行相应的调整。

清单 9-10 中的get_context_data()方法首先添加自定义special_context_variable键，使其可用于基于类的视图模板(即items/item_form.html)。接下来，调用父类的get_context_data()方法(即CreateView)来运行其上下文设置逻辑，包括设置模板中也使用的form引用。最后，get_context_data()方法返回带有所有模板上下文值的context引用，以便在模板内部使用。

正如您在清单 9-10 中看到的，通过简单地在一个基于CreateView类的视图中添加字段和覆盖方法，您可以很容易地开始改变它的默认行为。

自定义表单初始化和验证:Initial field、get_initial()、get_form()、form_valid()和 form_invalid()方法

基于CreateView类的视图上的initial字段就像标准表单的initial参数一样为未绑定表单指定默认值。例如，在基于CreateView类的视图上声明字段initial = {'size':'L'}会将其表单的size字段设置为L。

表单初始化有时可能需要比单行语句更复杂的需求，其中基于类的视图还提供了方法。get_initial()方法的功能类似于标准表单中使用的__init__方法——因为您可以引入开放式逻辑来设置默认值——但它的唯一目的是设置initial值并返回一个值字典——不像__init__方法，您可以引入除默认表单值之外的其他操作(例如，更改小部件、添加验证)。

清单 9-11 展示了在基于CreateView的视图上使用initial参数和get_initial()方法。

# views.py
from django.views.generic.edit import CreateView
from .models import Item, ItemForm, Menu

class ItemCreation(CreateView):
    initial = {'size':'L'}

    model = Item
    form_class = ItemForm
    success_url = reverse_lazy('items:index')
    def get_initial(self):

        initial_base = super(ItemCreation, self).get_initial()

        initial_base['menu'] = Menu.objects.get(id=1)

        return initial_base

Listing 9-11.Django class-based view with CreateView with initial and get_initial()

清单 9-11 中的第一步是设置initial字段，将基于类的视图的表单size字段设置为L。接下来，声明get_initial()方法，为基于类的视图表单添加另一个默认值。

在get_initial()方法内部，第一步是调用父类的get_initial()方法(即CreateView)来运行它的初始设置逻辑；这确保了类别的initial字段值(即{'size':'L'})被考虑为initial值的一部分。接下来，更新initial_base引用，将表单的menu字段设置为带有id=1的Menu记录。最后，清单 9-11 中的get_initial()方法返回一个字典，其中包含由基于类的视图设置的initial字段值和在其主体中设置的自定义表单值。

基于CreateView类的视图的get_form()方法旨在利用表单的完整初始化过程，而不仅仅是像initial字段和get_initial()方法那样设置其默认值。这使得get_form()方法适合于执行更广泛的表单初始化任务，比如设置表单小部件和验证初始化，就像在标准表单的__init__方法中所做的那样。包含地，可以使用get_form()方法来指定默认的表单值，并且完全放弃使用initial和get_initial()。清单 9-12 展示了在基于CreateView类的视图中get_form()方法的使用。

# views.py
from django.views.generic.edit import CreateView
from .models import Item, ItemForm, Menu

class ItemCreation(CreateView):
    initial = {'size':'L'}

    model = Item
    form_class = ItemForm
    success_url = reverse_lazy('items:index')
    def get_form(self):

        form = super(ItemCreation, self).get_form()

        initial_base = self.get_initial()

        initial_base['menu'] = Menu.objects.get(id=1)

        form.initial = initial_base

        form.fields['name'].widget = forms.widgets.Textarea()

        return form

Listing 9-12.Django class-based view with CreateView with get_form()

清单 9-12 中的get_form()方法的第一步是调用父类的get_form()方法(即CreateView)来获取基础表单。接下来，调用基于类的视图的get_initial()方法来获取其initial表单值，并使用模型查询为表单的menu字段设置默认值。在这种情况下，表单初始化表单字典的值与清单 9-11 中的值相同。

接下来，使用标准的initial表单引用将表单初始化字典分配给基础表单。最后，在返回 form 类的实例之前，在表单的name字段上设置一个自定义小部件，覆盖表单name字段的默认小部件。

除了初始化任务，还可以定制基于类的视图的表单验证过程。form_valid()和form_invalid()方法分别用于访问基于类的视图表单被认为成功或错误的点。清单 9-13 展示了一个在基于CreateView类的视图中使用form_valid()和form_invalid()方法的例子。

# views.py
from django.views.generic.edit import CreateView
from django.http import HttpResponseRedirect
from django.contrib import messages
from .models import Item, ItemForm, Menu

class ItemCreation(CreateView):
    initial = {'size':'L'}
    model = Item
    form_class = ItemForm
    success_url = reverse_lazy('items:index')
    def form_valid(self,form):

        super(ItemCreation,self).form_valid(form)

        # Add action to valid form phase

        messages.success(self.request, 'Item created successfully!')

        return HttpResponseRedirect(self.get_success_url())

    def form_invalid(self,form):

        # Add action to invalid form phase

        return self.render_to_response(self.get_context_data(form=form))

Listing 9-13.Django class-based view with CreateView with form_valid() and form_invalid()

正如您在清单 9-13 中看到的，form_valid()方法通过它的form输入参数获得对表单实例的访问，这反过来允许您在表单通过验证阶段时在表单上执行操作。在这种情况下，没有对表单本身采取任何操作来简化事情，但是添加了一个额外的逻辑来说明定制过程。

清单 9-13 中form_valid()的第一步是调用父类的form_valid()方法(即CreateView)来运行其表单验证设置逻辑，这确保了基类的表单验证首先运行，以验证任何违反表单规则的情况(例如，向表单添加错误)。如果对父类的form_valid()方法的调用检测到了违反规则的情况，那么该类的form_valid()方法(即列出 9-13 的方法)就会短路并退回到form_invalid()方法。如果父方法form_valid()通过，清单 9-13 中的逻辑继续添加一个 Django 消息框架成功消息以呈现给用户。

Tip

还可以通过 mixin 将 Django 消息框架成功消息添加到基于类的视图表单验证过程中。本章的最后一节描述了基于类的视图的混合。

最后，因为您正在处理一个有效的表单工作流，清单 9-13 中的form_valid()方法必须显式地将用户重定向到一个位置来完成它的工作。在这种情况下，标准 Django HttpResponseRedirect方法与基于类的视图的get_success_url()方法一起使用，最后一个方法获取基于类的视图success_url字段值。

清单 9-13 中的form_invalid()方法并不特别处理无效表单。它只是通过基于类的视图方法完成最少量的工作，即将控制返回到同一个模板位置，并添加包含有错误的表单的上下文以呈现给用户。

正如您所看到的，基于CreateView类的视图中的form_valid()和form_invalid()方法的好处是它们允许您定制表单验证工作流，而不需要修改CreateView工作流的其他部分(例如，将表单数据保存到数据库)。

自定义视图方法工作流:get()和 post()方法

除了前面对基于类的视图的定制选项之外，还可以使用get()或post()方法对基于类的视图完成的工作流进行绝对控制。get()方法用于接入与基于类的视图相关联的 HTTP GET 工作流，而post()方法用于接入与基于类的视图相关联的 HTTP POST 工作流。

虽然使用get()或post()方法可以为基于类的视图提供最大的灵活性，但是它们也需要显式声明基于类的视图的初始化、验证和重定向序列。这意味着使用get()或post()方法的基于类的视图可以更类似于标准的开放式 Django 视图——在第二章中描述——而不是之前在清单 9-9 中呈现的简洁的基于类的视图。

尽管如此，有时基于类的视图的吸引力如此之大，使用get()或post()方法是有保证的。清单 9-14 展示了一个在基于CreateView的视图中使用get()和post()方法的例子。

# views.py
from django.views.generic.edit import CreateView
from django.shortcuts import render
from django.contrib import messages

class ItemCreation(CreateView):
    initial = {'size':'L'}
    model = Item
    form_class = ItemForm
    success_url = reverse_lazy('items:index')
    template_name = "items/item_form.html"
    def get(self,request, *args, **kwargs):

        form = super(ItemCreation, self).get_form()

        # Set initial values and custom widget

        initial_base = self.get_initial()

        initial_base['menu'] = Menu.objects.get(id=1)

        form.initial = initial_base

        form.fields['name'].widget = forms.widgets.Textarea()

        # return response using standard render() method

        return render(request,self.template_name,

                      {'form':form,

                       'special_context_variable':'My special context variable!!!'})

    def post(self,request,*args, **kwargs):

        form = self.get_form()

        # Verify form is valid

        if form.is_valid():

            # Call parent form_valid to create model record object

            super(ItemCreation,self).form_valid(form)

            # Add custom success message

            messages.success(request, 'Item created successfully!')    
            # Redirect to success page    
            return HttpResponseRedirect(self.get_success_url())

        # Form is invalid

        # Set object to None, since class-based view expects model record object

        self.object = None

        # Return class-based view form_invalid to generate form with errors

        return self.form_invalid(form)

Listing 9-14.Django class-based view with CreateView with get() and post()

您可以在清单 9-14 中看到，get()和post()方法都可以访问一个request输入——一个HttpRequest实例——就像标准视图方法一样。这个request引用允许基于类的视图访问请求数据，例如 HTTP 元数据(例如，用户的 IP 地址)，这是在第二章中详细描述的主题。

清单 9-14 中get()方法的第一步是使用父类的get_form()方法(即CreateView)创建一个未绑定表单。因为get()方法让您可以完全控制工作流，所以使用标准表单语法(例如form = ItemForm())创建未绑定表单同样有效，但是因为它是基于类的视图，所以该示例利用了基于类的视图构造。一旦创建了未绑定表单，就会在表单上设置一系列初始值和一个自定义小部件，就像在前面基于类的视图示例中所做的那样。

一旦未绑定表单准备好了，注意到get()方法的return语句使用了常规视图方法中使用的标准render()方法。在这种情况下，render()方法将控制重定向到基于类的视图模板，并用未绑定的form和一个额外的special_context_variable变量设置模板上下文，以便在模板中使用。

接下来，清单 9-14 中的post()方法负责处理包含用户数据的表单。post()方法的第一步是使用基于类的视图get_form()类获得一个绑定表单实例。类似于get()方法，使用标准表单语法(如form = ItemForm(request.POST))创建绑定表单同样有效。

对于绑定的表单实例，将进行检查以验证用户提供的表单数据是否有效，就像对标准表单(例如，form.is_valid())所做的那样。如果表单数据有效，则调用父类的is_valid()方法(即CreateView)，确保在表单有效时执行基于类的视图的核心逻辑(例如将表单数据保存到数据库)。这里可以再次使用任何标准的模型构造，但是调用父类的is_valid()方法更容易执行这个例程逻辑来创建一个模型对象记录。一旦例程验证逻辑完成，就会添加一条成功消息呈现给最终用户，并重定向到基于类的视图的成功 url。如果表单数据无效，基于类的视图的对象字段被设置为None——因为基于类的视图期望在后期处理中处理一个对象记录实例——并且使用负责底层细节的基于类的form_invalid()方法返回控制，而不是使用render()方法创建标准的视图方法响应。

正如您现在从清单 9-14 中的例子所理解的，基于CreateView类的视图可以像标准视图方法一样灵活。这只是了解和理解基于类的视图所支持的不同字段和方法的问题。当然，如果你觉得基于CreateView类的视图的定制逻辑变得过于笨拙，你可以随时回到第二章中介绍的标准视图方法。

使用基于类的视图 ListView 和 DetailView 读取模型记录

与创建模型记录的过程类似，读取模型记录的过程也遵循一个对所有模型几乎相同的过程:创建一个查询来获取模型记录，然后使用一个模板来显示模型记录。Django ListView和DetailView基于类的视图是专门为减少分别显示 Django 模型记录列表和单个 Django 模型记录所需的样板代码而设计的。

ListView基于类的视图可以快速建立一个模型记录列表的查询，并在模板中显示它们。清单 9-15 展示了一个基于类的视图，它使用了ListView基于类的视图。

# views.py
from django.views.generic.list import ListView
from .models import Item

class ItemList(ListView):
    model = Item

# urls.py
from django.conf.urls import url
from coffeehouse.items import views as items_views

urlpatterns = [
    url(r'^$',items_views.ItemList.as_view(),name="index"),
]

# templates/items/item_list.html
  {% regroup object_list by menu as item_menu_list %}
  {% for menu_section in item_menu_list %}
   <li>{{ menu_section.grouper }}
    <ul>
        {% for item in menu_section.list %}
        <li>{{item.name|title}}</li>    
        {% endfor %}
    </ul>
    </li>
{% endfor %}

Listing 9-15.Django class-based view with ListView to read list of records

清单 9-15 中的第一个定义是ItemList类，它继承了基于ListView类的视图类的行为。设置为Item的ItemList类中的model字段告诉 Django 生成所有Item模型记录的列表(例如Item.objects.all())。

接下来，使用as_view()方法将ListView基于类的视图连接到一个根 url 正则表达式–r'^$',最后一个方法可用于所有基于类的视图，并且在上一节中也用于设置一个CreateView基于类的视图。

最后，清单 9-15 的最后一部分展示了在object_list引用上生成循环的模板item_list.html，最后一个是默认的上下文变量，由包含模型记录列表的ListView基于类的视图使用。

概括一下，ListView基于类的视图最重要的默认行为如下:

记录列表由model选项中定义的模型的所有记录组成。

呈现记录列表的模板使用项目的TEMPLATES目录路径下的约定<app_name>/<model_name>_list.html。

传递给模板(即包含记录的模板)的上下文变量被命名为object_list。

正如您在这个例子中看到的，一个基于ListView类的视图减少了向一个字段显示模型记录列表所需的样板代码。

DetailView基于类的视图是另一个记录读取构造，旨在快速建立单个记录查询并在模板中呈现结果。清单 9-16 展示了使用DetailView类的基于类的视图。

# views.py
from django.views.generic. import DetailView
from .models import Item

class ItemDetail(DetailView):
    model = Item

# urls.py
from django.conf.urls import url
from coffeehouse.items import views as items_views

urlpatterns = [
    url(r'^(?P<pk>\d+)/$',items_views.ItemDetail.as_view(),name="detail"),
]

# templates/items/item_detail.html
<h4> {{item.name|title}}</h4>
<p>{{item.description}}</p>
<p>${{item.price}}</p>
<p>For {{item.get_size_display}} size: Only {{item.calories}} calories
{% if item.drink %}
and {{item.drink.caffeine}} mg of caffeine.</p>
{% endif %}
</p>

Listing 9-16.Django class-based view with DetailView to read model record

清单 9-16 中的第一个定义是ItemDetail类，它继承了基于DetailView类的视图类的行为。ItemDetail类中的model字段指向Item，它告诉 Django 获取一个Item模型记录。与清单 9-15 中读取所有模型记录的ListView基于类的视图类不同，DetailView基于类的视图类必须总是将其模型查询限制在单个记录中，这就是基于类的视图 url 定义发挥作用的地方。

清单 9-16 中的DetailView基于类的视图被挂接到一个根 url 正则表达式——r'^$'——使用as_view()方法——就像其他基于类的视图一样——但是请注意 url 定义包含了(?P<pk>\d+) url 参数，该参数被传递给基于类的视图以将模型查询限定为一条记录。

例如，如果在 url /items/1/上发出一个请求，1被分配给pk参数，该参数被传递给基于类的视图，以构建模型查询Item.objects.get(pk=1)，该模型查询通过pk=1获得Item模型记录——注意pk字段代表主键，通常相当于id字段。

以这种方式，当在DetailView基于类的视图上作出的 url 请求改变时(例如/items/2/、/items/3/)，对模型 a 记录作出的后备查询也改变，并且记录返回以显示在模板中。

最后，清单 9-16 的最后一部分展示了模板item_detail.html，它输出代表模型记录的item引用的各个字段。在这种情况下，使用item引用是因为DetailView基于类的视图为模型记录使用的默认上下文变量是模型本身的名称。

概括一下，DetailView基于类的视图最重要的默认行为如下:

模型记录是基于model选项和 url pk参数确定的，该参数根据模型的主键将查询限定为单个记录。

呈现记录的模板使用项目的TEMPLATES目录路径下的约定<app_name>/<model_name>_detail.html。

传递给模板(即包含记录的模板)的上下文变量以基于类的视图的model命名(例如，如果model=Item，则上下文变量命名为item)。

正如您在这个例子中看到的，从DetailView类继承其行为的基于类的视图减少了呈现单个模型记录所需的样板代码。

ListView 字段和方法

类似于前面介绍的CreateView基于类的视图，可以覆盖ListView基于类的视图的许多默认行为。

事实证明，ListView基于类的视图继承了许多其他 Django 基于类的视图的行为，如下所示:

django.views.generic.list.MultipleObjectTemplateResponseMixin
django.views.generic.base.TemplateResponseMixin
django.views.generic.list.BaseListView
django.views.generic.list.MultipleObjectMixin
django.views.generic.base.View

Note

基于类的视图从它的父类继承了许多字段和方法。以下选项是最常见的选项；要获得详尽的列表，请查阅每个ListView父类。

基本 ListView 选项:模型字段

正如您在清单 9-15 中看到的，基于ListView类的视图实现的基本逻辑是从一个模型中创建一个记录列表。因此,model字段选项对于指示在哪个模型上创建记录列表至关重要。

接下来的部分描述了如何定制一个基于ListView类的视图，包括如何为一个记录列表定界和生成多个页面，以及如何覆盖其他默认行为。

自定义模板上下文引用名称:上下文对象名称

在清单 9-15 中，您可以看到ListView基于类的视图的模板使用了不太友好的上下文变量object_list。这是默认行为，但是为了帮助模板编辑器，可以使用不同的上下文变量来包含记录列表。

context_object_name字段用于定义一个定制的上下文变量名，以操作模板内的记录列表(如context_object_name = 'item_list')。

Tip

基于ListView类的视图也从许多与前面描述的CreateView类相同的类中继承它的行为。因此，你也可以使用template_name字段来指定一个自定义模板名；用于指定 MIME 类型的content_type字段；和get_context_data()方法来改变模板使用的上下文。

自定义记录列表:查询集和排序字段以及分页行为

默认情况下，一个基于ListView类的视图为属于一个模型的所有记录生成一个列表。虽然这种行为是合理的，但也有必要创建一个基于ListView类的视图来返回更有限的标准，在这种情况下，有必要对支持模型查询进行定界。queryset字段用于定义一个定制查询来生成一个记录列表。

自定义记录列表的另一个有用选项是指定生成记录列表的字段顺序。类似于模型查询中使用的标准order_by()方法，基于ListView类的视图可以指定ordering字段来定义记录列表的排序顺序。

清单 9-17 展示了在基于ListView类的视图中queryset和ordering字段的使用。

# views.py
from django.views.generic.list import ListView
from .models import Item

class ItemList(ListView):
    model = Item
    queryset = Item.objects.filter(menu__id=1)

    ordering = ['name']

Listing 9-17.Django class-based view with ListView to reduce record list with queryset

正如您在清单 9-17 中看到的那样，queryset字段被分配了一个标准模型查询来生成带有menu id=1的Item记录。通过这种方式，由ListView基于类的视图传递给模板的结果记录列表只包含符合这些标准的Item记录。此外，清单 9-17 还利用了ordering = ['name']字段，在这种情况下，它确保生成记录列表的查询按照Item模型的name字段排序。

虽然queryset选项有助于限定基于ListView类的视图所显示的记录列表的大小，但有时有必要处理一个大的记录列表，并且仍然能够限定模板中显示的结果数量。对于这种情况，您可以使用分页将大型记录列表拆分到多个页面上。

由于根据定义分页依赖于多个页面的使用，这迫使您不仅要调整基于类的视图定义，还要调整基于类的视图使用的 url 结构和模板以支持多个页面。清单 9-18 展示了一个基于ListView类的视图的分页示例，它基于清单 9-15 中的示例。

# views.py
from django.views.generic.list import ListView
from .models import Item

class ItemList(ListView):
    model = Item
    paginate_by = 5

# urls.py
from django.conf.urls import url
from coffeehouse.items import views as items_views

urlpatterns = [
    url(r'^$',items_views.ItemList.as_view(),name="index"),
    url(r'^page/(?P<page>\d+)/$',items_views.ItemList.as_view(),name="page"),

]

# templates/items/item_list.html
  {% regroup object_list by menu as item_menu_list %}
{% for menu_section in item_menu_list %}
   <li>{{ menu_section.grouper }}
    <ul>
        {% for item in menu_section.list %}
        <li>{{item.name|title}}</li>    
        {% endfor %}
    </ul>
    </li>
{% endfor %}

{% if is_paginated %}

    {{page_obj}}

{% endif %}

Listing 9-18.Django class-based view with ListView to read list of records with pagination

清单 9-18 中的相关分页逻辑以粗体显示。首先，paginate_by = 5被添加到基于类的视图定义中，它告诉 Django 将记录列表限制为每页 5 条记录。由于ListView基于类的视图将需要页码来显示查询的前 5 条记录之外的记录——因为页面被限制为 5 个——获取页码的自然位置是通过 url(例如，/page/1/创建查询的前 5 条记录的列表，/page/2/创建记录 6 到 10 的列表，等等)。).

接下来在清单 9-18 中，您可以看到一个新的 url 定义，其中的(?P<page>\d+)参数连接到了ListView基于类的视图。这个 url 定义允许一个匹配正则表达式模式(例如，/page/1/,/page/2/)的请求将 url page参数值传递给基于类的视图。当基于ListView类的视图检测到存在paginate_by选项的 url page参数值时，它调整对记录列表的查询，以基于页面将适当的记录集返回给模板(例如，/page/1/生成整个查询的 1 到 5 的记录列表，/page/2/生成整个查询的 6 到 10 的记录列表，等等)。).

最后，清单 9-18 中的最后一部分代表了使用分页的ListView基于类的视图的支持模板。{% is_paginated %}标签和{{page_obj}}上下文引用用于让用户知道他们在整个记录列表的哪一页。

Tip

一个ListView基于类的视图也可以使用get()基于类的视图方法来获得对视图工作流的完全控制。参见上一节关于CreateView基于类的视图，它描述了如何使用它及其含义。

详细视图字段和方法

像其他基于类的视图一样，DetailView基于类的视图也可以用定制字段和方法来创建，以覆盖它们的默认行为。

事实证明，DetailView类从许多其他基于 Django 类的视图中继承了它的行为，这些视图在下面的列表中描述:

django.views.generic.detail.SingleObjectTemplateResponseMixin
django.views.generic.base.TemplateResponseMixin
django.views.generic.detail.BaseDetailView
django.views.generic.detail.SingleObjectMixin
django.views.generic.base.View

Note

基于类的视图从它的父类继承了许多字段和方法。以下选项是最常见的选项；要获得详尽的列表，请查阅每个DetailView父类。

基本详细信息视图选项:带 pk 参数的模型字段和 url

正如您在清单 9-16 中看到的，基于DetailView类的视图实现的基本逻辑是获取一个模型记录并在模板中显示它。因此,model字段是这种基于类的视图的重要部分之一，必须始终提供。

为了获得一个特定的模型记录，一个基于类的视图还必须定义一个 url 参数来帮助它选择一个模型记录。默认情况下，这个 url 参数必须被命名为pk，它的值用于使用pk字段对model值执行查询，这个字段通常相当于模型的id字段。

Tip

一个基于类的视图也从前面描述的许多基于类的视图类中继承了它的行为。因此，您也可以使用template_name字段来指定一个自定义模板名称；用于指定 MIME 类型的content_type字段；改变模板使用的上下文的get_context_data()方法；以及context_object_name字段来声明不同的上下文变量以访问模板中的记录。

自定义 url 和查询参数:pk_url_kwarg，slug_field 和 slug_url_kwarg

默认情况下，DetailView基于类的视图期望一个名为pk的 url 参数来决定通过主键查询哪个模型记录。然而，如果你已经有了一个预先存在的 url 或者只是不喜欢这个不明确的 url 参数名，你可以用pk_url_kwarg字段指定一个自定义的 url 参数。

例如，在基于DetailView类的视图上设置pk_url_kwarg='item_id'，允许将 url 定义为url(r'^(?P<item_id>\d+)/$',items_views.ItemDetail.as_view())而不是默认的url(r'^(?P<pk>\d+)/$',items_views.ItemDetail.as_view())。

尽管使用pk字段执行基于DetailView类的视图的记录查询是一种常见的做法——考虑到pk字段通常是一个带有数据库索引的整数字段，以提高查找性能——有时可能有必要使用另一个模型字段执行基于DetailView类的记录查询(例如，创建更多用户/SEO 友好的 URL，如/item/capuccino/，而不是/item/1/)。

清单 9-19 展示了一个基于DetailView类的视图，它使用slug_field选项来允许对模型字段而不是pk进行模型记录查询。

# views.py
# views.py
from django.views.generic import DetailView
from .models import Item

class ItemDetail(DetailView):
    model = Item
    slug_field = 'name__iexact'

# urls.py
from django.conf.urls import url
from coffeehouse.items import views as items_views

urlpatterns = [
    url(r'^(?P<slug>\w+)/$',items_views.ItemDetail.as_view(),name="detail"),
]

# Template identical to listing to template in Listing 9-16

Listing 9-19.Django class-based view with DetailView and slug_field option

清单 9-19 中的第一个重要方面是，url 定义有一个名为slug的 url 参数，由于使用了w+正则表达式，它可以匹配任何单词模式。这意味着像/items/espresso/和/items/latte/这样的 url 匹配这个 url，不像以前的DetailView基于类的 URL 定义使用pk参数来匹配数值和d+正则表达式。

当一个DetailView基于类的视图接收到一个名为slug的 url 参数时，它会通知基于类的视图，模型记录查询应该在一个模型字段而不是pk上进行。因为这个slug值可能是不明确的(例如，它可以表示几个模型字段值中的一个，如名称、成本或描述)，所以有必要限定slug值表示哪个模型字段，这就是slug_field字段的目的。

在清单 9-19 的情况下，slug_field字段被设置为name__iexact，这告诉DetailView基于类的视图使用Item模型name字段上的slug值执行不区分大小写的模型查询。不区分大小写的查询由__iexact查找提供，在数据库记录值大小写混合的情况下很重要(例如，url /items/capuccino/将匹配Item名称记录capuccino、Capuccino,或CAPUCCINO)。如果没有大小写发明，Item名称记录将需要精确地capuccino来匹配 url)。

尽管清单 9-19 中的示例中没有提供，基于DetailView类的视图的另一个可用选项是slug_url_kwarg选项，它与前面描述的pk_url_kwarg选项类似。

默认情况下，使用 slug 查询(即非pk查询)的基于DetailView类的视图期望一个名为slug的 url 参数来确定对哪个模型字段进行查询以获得记录。但是，如果您已经有一个预先存在的 url 或者只是不喜欢这个不明确的 url 参数名称，您可以使用slug_url_ kwarg字段指定一个自定义的 url 参数。

例如，在基于DetailView类的视图上设置slug_url_kwarg='item_name'，允许将 url 定义为url(r'^(?P<item_name>\w+)/$',items_views.ItemDetail.as_view())而不是默认的url(r'^(?P<slug>\w+)/$',items_views.ItemDetail.as_view())。

Tip

一个DetailView基于类的视图也可以使用get()基于类的视图方法来获得对视图工作流的完全控制。参见上一节关于CreateView基于类的视图，描述了如何使用它及其含义。

用基于类的视图更新模型记录

当您更新 Django 模型记录时，典型的过程包括从数据库中获取想要更新的模型记录，在表单中显示模型数据以便用户可以进行更改，最后将更改保存回数据库。基于 Django UpdateView类的视图是专门为减少更新 Django 模型记录所需的样板代码而设计的。

由于其功能性，UpdateView基于类的视图的操作类似于通过表单创建模型记录的CreateView和显示模型记录的DetailView的组合。清单 9-20 展示了一个UpdateView基于类的视图的例子。

# views.py
from django.views.generic import UpdateView
from .models import Item

class ItemUpdate(UpdateView):
    model = Item
    form_class = ItemForm
    success_url = reverse_lazy('items:index')

# urls.py
from django.conf.urls import url
from coffeehouse.items import views as items_views

urlpatterns = [
     url(r'^edit/(?P<pk>\d+)/$', items_views.ItemUpdate.as_view(), name='edit'),
]

# templates/items/item_form.html
<form method="post">
        {% csrf_token %}
        {{ form.as_p }}
        <button type="submit" class="btn btn-primary">
          {% if object == None%}Create{% else %}Update{% endif %}
        </button>
</form>

Listing 9-20.Django class-based view with UpdateView to edit a record

清单 9-20 中的第一个定义是从基于UpdateView类的视图类继承其行为的ItemUpdate类。ItemUpate类中的model字段为Item设置一个值，它告诉 Django 更新Item模型记录。此外，因为您正在处理一个更新操作，Item模型记录必须以一种形式呈现——这是from_class选项的目的——以及定义一个成功的 url 来在更新成功时重定向用户，这是success_url选项的目的。

清单 9-20 中的下一个是链接到UpdateView基于类的视图类的 url 定义。因为基于UpdateView类的视图必须提供一个特定的模型记录来编辑，所以它依赖于一个 url 参数来限制对单个记录的查询。在这种情况下，注意 url 包含传递给基于类的视图的pk url 参数——就像用DetailView基于类的视图一样。

例如，如果请求 url /items/edit/1/，1作为pk参数被传递给UpdateView基于类的视图，该视图又执行查询Item.objects.get(pk=1)来检索记录，并以表格的形式呈现出来以供编辑。

最后，清单 9-20 中的最后一部分展示了模板item_form.html，它显示了要编辑的表单中的记录。默认的UpdateView基于类的视图模板的一个重要方面是它与CreateView基于类的视图使用的默认模板相同。这是因为两个基于类的视图共享该功能的相同的基于类的父视图类，更不用说表单的目的是相同的(例如，CreateView基于类的视图中的表单是空的，供用户填写新的记录数据，而UpdateView基于类的视图中的表单是用预填充的记录发送的，以更新记录数据)。

出于这个原因，清单 9-20 中的模板与清单 9-9 中用于基于CreateView类的视图的模板几乎相同。微小的区别是，如果模板在其上下文中检测到object变量的存在，这意味着UpdateView基于类的视图正在传递一个记录进行编辑，并且表单按钮被设置为Update；否则，如果没有出现object变量，这意味着CreateView基于类的视图正在调用模板，表单按钮被设置为Create。

概括一下，UpdateView基于类的视图最重要的默认行为:

要更新的模型记录是根据model选项和 url pk参数确定的，该参数根据模型的主键将查询限定为单个记录。

呈现表单以更新记录的模板使用项目的TEMPLATES目录路径下的约定<app_name>/<model_name>_form.html,注意它与CreateView基于类的视图使用的默认模板相同，对于这种情况，您可以依靠object上下文变量的存在来确定是否是UpdateView调用了模板。

传递给模板(即包含记录的模板)的上下文变量被命名为object，尽管表单会自动填充这个记录值。

正如您在这个例子中看到的，从UpdateView类继承其行为的基于类的视图减少了编辑模型记录所需的样板代码。

更新视图字段和方法

像其他基于类的视图一样，UpdateView基于类的视图也可以用定制字段和方法来创建，以覆盖它们的默认行为。

事实证明，UpdateView类继承了许多其他基于 Django 类的视图的行为，如下所示:

django.views.generic.detail.SingleObjectTemplateResponseMixin
django.views.generic.base.TemplateResponseMixin
django.views.generic.edit.BaseUpdateView
django.views.generic.edit.ModelFormMixin
django.views.generic.edit.FormMixin
django.views.generic.detail.SingleObjectMixin
django.views.generic.edit.ProcessFormView
django.views.generic.base.View

Note

基于类的视图从它的父类继承了许多字段和方法。以下选项是最常见的选项；要获得详尽的列表，请查阅每个UpdateView父类。

基本更新视图选项:模型、form_class 和 success_url 字段，以及带有 pk 参数的 url

正如您在清单 9-20 中看到的，基于UpdateView类的视图实现的基本逻辑是获取一个模型记录，并以一种形式显示出来以供编辑。因此,model字段是这种基于类的视图的重要部分之一，必须始终提供。此外，因为记录是通过表单更新的，所以还需要通过form_class选项指定一个表单，以及当更新成功时通过success_url选项指定一个成功 url。

为了获得一个特定的模型记录，一个基于UpdateView类的视图还必须定义一个 url 参数来帮助它选择一个模型记录进行编辑。默认情况下，这个 url 参数必须被命名为pk，它的值用于使用pk字段对model值执行查询，这个字段通常相当于模型的id字段。

Tip

此外，因为一个基于UpdateView类的视图需要获得一个模型记录，所以它也可以使用pk_url_kwarg字段来接受一个不同于pk的 url 参数；slug_field字段指定一个备选记录查询字段；和slug_url_kwarg字段来接受不同于slug命名的不同 url 参数。

最后，UpdateView基于类的视图也可以使用get()和post()基于类的视图方法来获得对视图工作流的完全控制。前面的基于类的视图部分描述了如何使用所有这些基于类的视图字段和方法。

使用基于类别的视图删除视图删除记录

当您删除 Django 模型记录时，除了执行实际的删除操作之外，向用户显示一个确认页面通常是一个很好的实践。Django DeleteView基于类的视图是专门为减少删除模型记录所需的样板代码量而设计的，同时显示一个确认页面。清单 9-21 展示了一个DeleteView基于类的视图示例。

# views.py
from django.views.generic.edit import DeleteView
from .models import Item

class ItemDelete(UpdateView):
    model = Item
    success_url = reverse_lazy('items:index')

# urls.py
from django.conf.urls import url
from coffeehouse.items import views as items_views

urlpatterns = [
    url(r'^delete/(?P<pk>\d+)/$', items_views.ItemDelete.as_view(), name='delete'),  
]

# templates/items/item_confirm_delete.html
  <form method="post">
        {% csrf_token %}
        Do you really want to delete "{{ object }}"?
        <button class="btn btn-primary" type="submit">Yes, remove it!</button>
  </form>

Listing 9-21.Django class-based view with DeleteView to delete record

清单 9-21 中的第一个定义是ItemDelete类，它继承了基于DeleteView类的视图类的行为。ItemDelete类中的model字段为Item设置一个值，它告诉 Django 删除Item模型记录。此外，因为您希望用户确认删除操作，所以还必须声明success_url选项，以指定删除操作成功后将用户带到哪里。

清单 9-21 中的下一个是链接到DeleteView基于类的视图类的 url 定义。因为基于类的视图必须被告知删除哪个模型记录，所以它依赖 url 参数来提供这个查询分隔符。在这种情况下，注意 url 包含传递给基于类的视图的pk url 参数——就像用DetailView基于类的视图一样。

例如，如果请求 url /items/delete/1/，1作为pk参数被传递给DeleteView基于类的视图，后者接着执行查询Item.objects.get(pk=1)来准备删除记录。

最后，清单 9-21 的最后一部分展示了用于面向用户的删除序列的item_confirm_delete.html模板。注意，这个模板包含一个伪表单(即没有表单字段),带有一个问题和提交按钮。这种伪表单的原因是item_confirm_delete.html模板具有双重功能。

如果在一个基于DeleteView类的视图上发出一个 HTTP GET 请求，那么一个带有这个伪表单的页面将返回给用户，向他提出问题Do you really want to delete "{{ object }}"?，其中object是要删除的模型记录。如果用户点击这个伪表单提交按钮，它会向同一个基于DeleteView类的视图发出一个 HTTP POST 请求——注意<form method="post">标记——调用实际的删除过程。以这种方式，这种具有伪形式的模板允许用户在点击 url 删除链接(例如/items/delete/1/)之后确认他是否真的想要删除记录，而不是在点击 url 删除链接时立即删除记录。

概括一下，DeleteView基于类的视图最重要的默认行为如下:

要删除的模型记录是根据model选项和 url pk参数确定的，该参数根据模型的主键将查询限定为单个记录。

呈现表单以更新记录的模板使用项目的TEMPLATES目录路径下的约定<app_name>/<model_name>_confirm_delete.html。

传递给模板(即包含要删除的记录的模板)的上下文变量被命名为object。

对基于DeleteView类的视图的 HTTP GET 请求显示来自<app_name>/<model_name>_confirm_delete.html模板的确认页面。基于DeleteView类的视图上的 HTTP POST 请求执行实际的删除过程。

正如您在这个例子中看到的，从DeleteView类继承其行为的基于类的视图减少了删除模型记录所需的样板代码。

删除视图字段和方法

像其他基于类的视图一样，DeleteView基于类的视图也可以用定制字段和方法来创建，以覆盖它们的默认行为。

事实证明，DeleteView类继承了许多其他基于 Django 类的视图的行为，如下所示:

django.views.generic.detail.SingleObjectTemplateResponseMixin
django.views.generic.base.TemplateResponseMixin
django.views.generic.edit.BaseDeleteView
django.views.generic.edit.DeletionMixin
django.views.generic.detail.BaseDetailView
django.views.generic.detail.SingleObjectMixin
django.views.generic.base.View

Note

基于类的视图从它的父类继承了许多字段和方法。以下选项是最常见的选项；要获得详尽的列表，请查阅每个DeleteView父类。

基本删除视图选项:模型和 success_url 字段以及带有 pk 参数的 url

正如您在清单 9-21 中看到的，基于DeleteView类的视图实现的基本逻辑是获取一个模型记录，并在显示确认页面时删除它。因此,model字段是这种基于类的视图的重要部分之一，必须始终提供。此外，因为记录被设置为删除，所以还需要通过success_url选项指定一个成功的 url，以便在记录被删除后重定向用户。

为了获得一个特定的模型记录，一个基于类的视图还必须定义一个 url 参数来帮助它选择一个要删除的模型记录。默认情况下，这个 url 参数必须被命名为pk，它的值用于使用pk字段对model值执行查询，这个字段通常相当于模型的id字段。

Tip

此外，因为一个基于DeleteView类的视图需要获得一个模型记录，所以它也可以使用pk_url_kwarg字段来接受一个不同于pk的 url 参数；slug_field字段指定一个备选记录查询字段；和slug_url_kwarg字段来接受不同于slug命名的不同 url 参数。

最后，DeleteView基于类的视图也可以使用get()和 post()基于类的视图方法来获得对视图工作流的完全控制。前面的基于类的视图部分描述了如何使用所有这些基于类的视图字段和方法。

带有混合的基于类的视图

尽管所有操作模型的基于类的视图通常遵循相同的工作流程来创建、读取、更新和删除模型记录，但是公平地说，在看到前面的基于类的视图部分之后，您会发现自己经常调整基于类的视图的默认行为。

虽然多次调整基于类的视图的方法和字段是完全合理的，但是如果您需要一次又一次地在几十个或几百个基于类的视图中获得相同的功能，这可能会令人厌烦。

当您被迫在基于类的视图中定义一个get()或post()方法，以包含一些在基于类的视图中不支持的功能(例如，CreateView、ListView、DetailView、UpdateView、DeleteView)时，这一点尤为明显，这需要输入一个冗长的工作流，如果重复多次，结果可能会是重复的。为了减少基于类的视图上下文中的重复定制，可以使用 mixins。

首先，您已经在基于类的视图环境中使用了 mixins，即使您没有意识到这一点。如果您仔细观察为前面章节中描述的基于类的模型视图提供行为的基于类的视图类，您可能会注意到许多视图类的名称中都包含术语 mixin(例如，ModelFormMixin、FormMixin、SingleObjectMixin)。

软件 mixin 是一个允许类之间的类继承行为的构造，特别强调类继承。当您使用类继承时，父子类关系通常用“是一个”术语来描述(例如，如果饮料类从项目类继承其行为，则饮料是一个项目)。另一方面，mixin 类允许一个类采用 mixin 类的行为，而没有“是 a”行为。

换句话说，mixin 类是向类添加功能的一种方式，mixin 类充当可重用的组件。例如，您可以拥有一个由 Store 类和 OnlineStore 类使用的 mixin Checkout 类，这允许在任何其他类中重用 mixin 类的功能。注意，对于 mixin 类，继承“是 a”行为并不适用，你不能说 Store 是 Checkout 或 OnlineStore 是 Checkout，它更多的是“使用 a”行为。因此，尽管 mixin 类——从语义上来说——用于继承行为，但从技术上来说，它们不使用软件工程中通常所知的继承，因此使用了术语“类继承”。

那么为什么 mixins 对基于类的视图很重要呢？原来，您在上一节中学习的所有基于基类的视图类都是建立在基于类的视图混合之上的。这不仅意味着您可以混合和匹配 mixin 来创建定制的基于类的视图，而且您还可以创建或重用其他 mixin 来增强基于类的视图的功能。

早些时候，当你学习了基于类的视图时，你可能还记得清单 9-13 中的例子，9-14 增加了一个 Django 框架成功消息，当一个记录被创建时通知用户。在清单 9-13 的情况下，这需要接入form_valid()基于类的视图方法来添加这个消息，而在清单 9-14 的情况下，这需要接入post()基于类的视图方法。尽管这两种方法都非常有效，但是为了添加 Django 框架成功消息的唯一目的，在基于类的视图中声明这两种方法中的任何一种都需要做大量的工作。

通过在基于类的视图上使用 mixin，您可以简化将基于类的视图中的 Django 框架成功消息添加到单个字段，而不需要定制更复杂的方法和/或将逻辑添加到基于类的视图。

清单 9-22 展示了一个CreateView基于类的视图，该视图使用 mixin 来支持将 Django 框架成功消息添加到基于类的视图响应中的功能。

# views.py
from django.views.generic.edit import CreateView

from django.contrib.messages.views import SuccessMessageMixin

from .models import Item, ItemForm

class ItemCreation(SuccessMessageMixin,CreateView):
    model = Item
    form_class = ItemForm
    success_url = reverse_lazy('items:index')
    success_message = "Item %(name)s created successfully"

Listing 9-22.Django class-based view with CreateView and mixin class

Caution

在多重继承的基于类的视图(例如class ItemCreation(SuccessMessageMixin,CreateView))的上下文中，Mixin 类应该总是首先声明，以优先于粗粒度的基于类的视图类。

清单 9-22 的第一个重要方面是SuccessMessageMixin mixin 类的import语句，这使得任何基于类的视图都能够轻松添加成功消息。接下来，SuccessMessageMixin mixin 类和CreateView基于类的视图被添加到ItemCreation类中，为基于类的视图提供核心功能。注意，mixin 类是使用标准 Python 继承语法添加到基于类的视图中的。

一旦ItemCreation基于类的视图获得了对SuccessMessageMixin mixin 类行为的访问，生成成功消息所需要的就是在success_message字段中定义实际的消息。以这种方式，当在基于类的视图的上下文中发生成功操作时(例如，success_url被触发)，基于类的视图自动将success_message值添加到请求中以显示给终端用户。

正如您在清单 9-22 中看到的，将 Django 框架成功消息添加到基于类的视图的过程被大大简化了，并通过 mixin 类实现了可重用性。当您将它与清单 9-13 和 9-14 中采用的方法进行比较时，这一点尤其正确，清单 9-13 和清单 9-14 中采用的方法由覆盖基于类的视图方法组成，这些方法需要大量的输入(许多是重复的)来完成一个简单的任务。

十、Django 用户管理

在这一章中，你将学习 Django 管理用户、组和权限。您将了解如何根据用户有条件地显示内容，如何限制 URL 和基于类的视图，以及如何基于用户权限管理 Django 模型记录的 CRUD(创建-读取-更新-删除)权限。

此外，您还将了解如何定制 Django 的内置用户模型以支持额外的数据字段，以及如何自动化用户管理任务，如注册、密码提醒和密码重置电子邮件。最后，您将了解如何创建定制的身份验证后端，以使用不同的技术验证用户凭证，包括允许用户使用脸书、谷歌或 Twitter 帐户访问 Django 应用。

Django 用户系统介绍

Django 用户系统基于内置于 Django 框架中的django.contrib.auth包。在本节中，您将了解这个包提供的核心概念，它是各种 Django 应用(包括 Django admin)使用的默认用户系统。

用户类型、子类型、组和权限

Django 用户类主要有两种类型:User和AnonymousUser。如果用户验证了自己的身份(即提供了有效的用户名/密码)，Django 会将其识别为User。另一方面，如果用户只是在没有任何认证的情况下浏览应用，Django 会将他识别为AnonymousUser。

任何User都可以进一步分为各种子类型中的一种:

超级用户。-在 Django admin 中拥有创建、读取、更新和删除数据权限的最强大的用户，包括模型记录和其他用户。
工作人员。-标记为 staff 的用户可以访问 Django admin。但是在 Django admin 中创建、读取、更新和删除数据的权限必须明确授予用户。默认情况下，超级用户被标记为 staff。
活跃。-所有信誉良好的用户都被标记为活跃用户。被标记为不活跃的用户无法验证自己，这是一种常见的状态，如果有一个待定的注册后步骤(例如，确认电子邮件)或用户被禁止，而您不想删除他的数据。

Django 还提供了一个Group类的概念来授予一组用户相同的权限，而不必单独分配给他们。例如，您可以将权限授予某个组，然后将用户分配到该组，以使权限管理更容易。通过这种方式，您可以在一个步骤中撤销或添加一组用户的权限，并快速授予新用户相同的权限。

此外，您可以将 Django 权限粒度地分配给 a User或Group，以便它们在 Django 模型上执行 CRUD(创建-更新-删除)记录，这是一个通过权限模型记录完成的过程。或者，您也可以在 URL/视图方法或模板内容上分配粗粒度的 Django 权限，以授予User、Group，甚至Permission受让人访问权限。

现在您已经了解了 Django 用户系统背后的基本概念，让我们更详细地探索与 Django 用户相关的更常见的操作。

创建用户

您想要创建的第一个用户是超级用户。如果你已经在第一章中设置了 Django 管理员，那么你已经有了一个项目超级用户。无论哪种方式，我都会在这里重述这个过程，因为您可以拥有任意数量的超级用户。清单 10-1 展示了创建超级用户的各种方法。

Tip

参考本书附带的源代码来运行练习，以减少打字和自动访问测试数据。

[user@coffeehouse ∼]$ python manage.py createsuperuser
Username (leave blank to use 'admin'):
Email address: admin@coffeehouse.com
Password:
Password (again):
Superuser created successfully.

[user@coffeehouse ∼]$ python manage.py createsuperuser --username=bigboss
                      --email=bigboss@coffeehouse.com
Password:
Password (again):
Superuser created successfully.

[user@coffeehouse ∼]$ python manage.py shell
Python 2.7.3 (default, Apr 10 2013, 06:20:15)
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from django.contrib.auth.models import User
>>> user = User.objects.create_superuser(username='angelinvestor',
                                 email='angelinvestor@coffeehouse.com',
                                 password='seedfunding')
>>>

Listing 10-1.Create Django superuser

Note

Django 用户名必须是唯一的；先前存在的用户名被拒绝。

正如您在清单 10-1 中看到的，您可以在manage.py实用程序中使用createsuperuser命令创建一个超级用户，在这里您需要输入用户名、电子邮件。和密码。你也可以用同样的createsuperuser命令创建一个超级用户，使用内嵌参数--username和--email，在这种情况下，你只需要输入密码。

此外，还可以通过 Django shell 使用带有create_superuser()方法的User模型类来创建超级用户。注意create_superuser()方法是如何要求相同的用户名、电子邮件和密码参数的。

当您以任何一种方式创建超级用户时，该用户也会被自动设置为职员并标记为活动用户，因此您不需要采取任何额外的步骤来访问 Django admin(需要职员权限)或继续进行身份验证(需要将用户标记为活动用户)。

有时候你只想创建一个普通用户，这种情况下你可以使用 Django 的 shell 实用程序，通过User模型直接创建一个用户。清单 10-2 说明了这一过程。

[user@coffeehouse ∼]$ python manage.py shell
Python 2.7.3 (default, Apr 10 2013, 06:20:15)
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from django.contrib.auth.models import User
>>> user = User.objects.create_user(username='downtownbarista',
                                 email='downtownbarista@coffeehouse.com',
                                 password='cappuccino')
>>> user.is_staff
False
>>> user.is_active
True
>>> user.is_superuser
False
Listing 10-2.Create regular Django user through shell

正如您在清单 10-2 中看到的，在您获得对 Django shell 的访问权之后，您导入User模型类，并使用用户名、电子邮件和密码参数调用create_user()方法。create_user()方法的结果包含新创建的用户。

为了确认create_user()方法生成了一个普通用户，您可以在清单 10-2 中看到一个对各种User模型属性的调用，确认用户既不是员工也不是超级用户，只是被标记为活动的。

最后，还可以通过 Django admin 创建用户。要做到这一点，你首先需要确保你拥有 Django admin 的超级用户权限。一旦你进入 Django admin，你会看到一个如图 10-1 所示的屏幕，点击“用户”链接。“用户”链接将你带到如图 10-2 所示的屏幕，点击右上角的“添加用户+”按钮。点击“添加用户+”按钮，您将进入如图 10-3 所示的屏幕，在这里您可以介绍新用户的凭证。

图 10-3。

Django admin to create new user

图 10-2。

Django admin Users list

图 10-1。

Django admin site home page

如果您希望更改以这种方式创建的用户的子类型(即超级用户、职员)，您也可以在 Django admin 中完成，这个过程将在下一节中描述。

管理用户

一旦用户在 Django 应用中，您将最终管理他。这种管理可以是撤销他的特权、增加他的特权，或者甚至编辑他的简档信息。您可以通过两种方式管理 Django 用户，在 Django admin 中或者通过在 Django shell 中或者直接在您的应用中操作User模型。

管理用户最简单的方法是直接在 Django admin 中。一旦你进入 Django admin，你会看到如图 10-1 所示的屏幕，如果你点击“用户”链接，你会被带到如图 10-2 所示的屏幕，其中包含 Django 用户列表。图 10-2 中显示的每个 Django 用户都有一个用户名链接，如果你点击这个链接，你会被带到用户页面，如图 10-4 、 10-5 和 10-6 所示，在这里你可以编辑用户的个人资料。

图 10-6。

Django admin change user page - Part 3

图 10-5。

Django admin change user page - Part 2

图 10-4。

Django admin change user page - Part 1

您可以编辑的用户资料的第一部分如图 10-4 所示。您可以在这里编辑他的用户名和密码——通过点击小文本末尾的“此表格”链接——他的名字、姓氏以及电子邮件。此外，您可以看到有三个复选框，可以在其中更改用户的活动、员工和超级用户状态。

如果你向下滚动，你会看到你可以编辑的用户资料的第二部分，如图 10-5 所示。在这里，您可以将一个用户分配到不同的组，以及分配一个用户对 Django 模型的 CRUD 权限。在这里，我建议您仔细评估为用户分配单独的 CRUD 权限的必要性；一种更灵活的方法是创建组，并为它们分配 CRUD 权限，然后将用户分配到组中，这样权限就更容易跟踪，并可供其他用户重用。

如果你继续向下滚动到最后，你会看到你可以编辑的用户资料的第三部分，如图 10-6 所示。在这里，您可以查看和更新用户的上次登录，以及用户的创建日期。在页面的右下角，您可以看到各种保存按钮，用于保存对页面所做的任何更改。此外，在左下角有一个“删除”按钮，可以完全删除用户；但是，我建议您考虑取消选中用户的活动状态来限制访问。这最后一步足以阻止用户再次访问应用，并保持他的其他数据不变，以防您想要撤销该操作。

修改用户资料的另一个选项是直接操作他的User模型记录。如清单 10-3 所示，首先查询所需的用户，然后修改模型属性或执行User模型助手方法之一。

[user@coffeehouse ∼]$ python manage.py shell
Python 2.7.3 (default, Apr 10 2013, 06:20:15)
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from django.contrib.auth.models import User
>>> user = User.objects.get(id=1)
>>> user.username = 'superadmin'
>>> user.save()
>>> userbig = User.objects.get(username='bigboss')
>>> userbig.is_superuser
True
>>> userbig.superuser = False
>>> userbig.first_name = 'Big'
>>> userbig.last_name = 'Boss'
>>> userbig.save()
>>> userbig.is_superuser
False
>>> userbig.get_full_name()
u'Big Boss'
>>> userbarista = User.objects.get(email='downtownbarista@coffeehouse.com')
>>> userbarista.email ='barista@coffeehouse.com'
>>> userbarista.save()
>>> userbarista.set_password('mynewpass')
>>> userbarista.check_password('oldpass')
False
>>> userbarista.check_password('mynewpass')
True
Listing 10-3.Manage Django user through shell

正如您在清单 10-3 中看到的，您可以修改图 10-4 、 10-5 和 10-6 中 Django admin 中呈现的相同的User配置文件值。请注意，因为您正在进行查询，所以对字段所做的任何更改之后都必须调用对要持久化的字段的引用的save()方法。表 10-1 和表 10-2 包含User模型上可用的字段和方法的完整列表。

表 10-2。

Django django.contrib.auth.models.User methods

| 方法 | 描述 | | --- | --- | | 获取用户名() | 返回用户的用户名。由于用户模型可以更改为另一个用户模型，因此推荐使用这种方法，而不是直接引用 username 属性。 | | is_anonymous() | 对于用户，该方法总是返回 False 这只是用来区分用户和匿名用户的一种方式。 | | is_authenticated() | 对于用户来说，该方法总是返回 True，因为它仅用于确定用户是否已经通过了 AuthenticationMiddleware(表示当前登录的用户)。 | | 获取全名() | 返回名和姓字段，中间有一个空格。 | | get_short_name() | 返回名字。 | | 设置密码(原始密码) | 将用户的密码设置为给定的原始字符串，注意密码哈希。请注意，当 raw_password 为 None 时，密码被设置为不可用的密码，就像使用 set_unusable_password()一样。 | | 检查密码(原始密码) | 如果给定的原始字符串是用户的正确密码，则返回 True，并注意进行比较的密码哈希。 | | set_unusable_password() | 将用户标记为未设置密码。请注意，这不同于使用空白字符串作为密码。该用户的 check_password()永远不会返回 True。如果针对现有外部源(例如，LDAP 目录)进行身份验证，这将很有帮助。 | | has_usable_password() | 如果为用户调用了 set_unusable_password()，则返回 False。 | | 获取组权限(obj =无) | 为用户返回一组组权限字符串。如果 obj 被传递，则仅返回特定对象的组权限。 | | 获取所有权限(obj =无) | 为用户返回一组组和用户权限字符串。如果 obj 被传递，则仅返回特定对象的组权限。 | | has_perm(perm，obj=None) | 如果用户具有指定的权限，则返回 True，其中 perm 的格式为。”。注意如果用户处于非活动状态，该方法总是返回 False。如果 obj 被传递，检查发生在特定的对象上，而不是模型上。 | | has_perms(perm_list，obj=None) | 如果用户拥有每个指定的权限，则返回 True，其中每个 perm 的格式为。”。注意如果用户处于非活动状态，该方法总是返回 False。如果 obj 被传递，检查发生在特定的对象上，而不是模型上。 | | has_module_perms(包名) | 如果用户拥有给定包(即 Django 应用标签)中的权限，则返回 True。如果用户不活动，该方法总是返回 False。 | | email_user(主题，消息，from _ email =无，**kwargs) | 向用户发送电子邮件。如果 from_email 为 None，Django 使用 settings.py 中的缺省 _FROM_EMAIL。还要注意，该方法依赖于 Django 的 send_mail()方法，它向该方法传递**kwargs 参数。有关 send_mail()方法和**kwargs 值的更多详细信息，请参见 Django 电子邮件快捷方式方法， |

表 10-1。

Django django.contrib.auth.models.User fields

| 田 | 描述 | | --- | --- | | 用户名 | (必需)30 个字符或更少，可以包含字母数字、_、@、+、。和-字符。 | | 名字 | (可选)30 个字符或更少。 | | 姓氏 | (可选)30 个字符或更少。 | | 电子邮件 | (可选)电子邮件地址。 | | 密码 | (必需)密码的散列和元数据。注意，Django 不存储原始密码。 | | 组 | 与 django . contrib . auth . models . group 的多对多关系 | | 用户权限 | 与 django.contrib.auth.Permission 的多对多关系。 | | is_staff(布尔值) | 指定用户是否可以访问管理网站。 | | is_active(布尔值) | 指定用户是否被视为活动用户。 | | is _ 超级用户 | (布尔值)指定用户是否拥有所有权限，而无需显式分配这些权限。 | | 最后一次登录 | 用户上次登录的日期时间，如果用户从未登录，则设置为 NULL。 | | 日期 _ 加入 | 指定帐户创建时间的日期时间。创建帐户时，默认设置为当前日期/时间。 |

Tip

用户模型数据存储在数据库表 auth_user 中。

Password Strength Options

默认情况下，Django 强制密码遵循某些规则，比如不要与用户名相似，包含最少数量的字符，避免常用词，以及强制密码不仅仅由数字组成。这些密码规则是在项目的 settings.py 文件的 AUTH_PASSWORD_VALIDATORS 变量中定义的，如下所示:

AUTH_PASSWORD_VALIDATORS = [
    {
        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
    },
]

这个验证器列表可以被编辑以适应项目的需要，通过删除某些规则或者包含使它们对选项更严格。 ¹

创建和管理组

Django 组可以在 Django 管理中创建。用一个超级用户帐号，进入 Django admin，你会看到一个类似图 10-1 的屏幕，点击“Groups”链接。“组”链接将你带到如图 10-7 所示的屏幕，然后点击右上角的“添加组+”按钮。点击“添加群组+”按钮，您将进入如图 10-8 所示的屏幕，在这里您可以创建一个新群组并介绍其名称。

图 10-8。

Django admin to create new group

图 10-7。

Django admin Groups list

正如你在图 10-8 中看到的，创建一个组所需要的只是一个名字，你可以选择指定给这个组的权限，在应用中对 Django 模型进行 CRUD 操作。

组的管理比用户简单，也可以完全从 Django admin 中完成。大多数时候，您最终要做的是将用户分配到组中。

要将用户分配到一个组，当您编辑用户时，您会看到一个选择网格，如图 10-5 所示。要编辑一个组的属性-名称和创建-删除-更新 Django 模型权限-你可以在如图 10-8 所示的创建它的同一个页面上进行。要从图 10-7 所示的群组列表中删除一个群组，选择您想要删除的群组，并从下拉列表中选择动作，如图 10-9 所示。

图 10-9。

Django admin to delete group Tip

组模型数据存储在数据库表 auth_group 中。和用户组关系存储在数据库表 auth_user_groups 中。

权限类型

默认情况下，Django 项目中的权限会强制执行某些操作。在上一节中，您了解了如何给予用户超级用户、职员和活动状态，所有这些都是用于 Django 管理和 Django 项目的整个访问工作流的权限。此外，您还了解了如何赋予用户或组创建、删除或更新 Django 模型记录的能力，所有这些都是分配给各个 Django 模型的权限。

在这一节中，我将扩展权限的主题，并描述权限的默认行为，以及如何为其他目的创建自己的权限。

用户权限:超级用户、员工和活跃用户

在上一节中，您学习了如何为 Django 用户分配不同的子类型:超级用户、职员和活动用户。以下是与这些用户子类型相关联的权限列表:

超级用户。-在 Django admin 中创建、读取、更新和删除用户的权限，以及通过 Django admin 创建、读取、更新和删除项目中所有 Django 模型记录的权限。
工作人员。-允许访问 Django admin。即使用户被标记为超级用户，用户也必须被标记为职员才能访问 Django admin。标记为 staff 的用户必须在每个 Django 模型上获得额外的权限来执行任务。
活跃。-允许登录应用(Django admin 或其他地方)。一个不活跃的用户被有效地禁止使用他的凭证来认证一个 Django 项目。例如，为了访问 Django admin，除了 staff 之外，用户必须被标记为 active。此外，Django 项目的任何部分(例如视图或模板)都可以标记为需要活动状态，迫使用户登录。

所有三个用户子类型都作为User模型的一部分存储在数据库中，这些子类型可以通过使用属于User模型的表 10-2 中的方法来确认。虽然User权限在 Django admin 中被大量使用，但这并不意味着它们仅限于此。例如，可以依靠User权限，如超级用户、职员或 active，来允许或拒绝对 Django 项目其他部分的访问(例如，模板中的链接、url/view 方法或其他操作)。

关于权限实施的下一节将详细描述这些过程。接下来，我将描述与 Django 模型相关的另一种类型的权限。

模型权限:添加、更改、删除和自定义

模型权限与创建、删除或更新 Django 模型记录的能力相关联。在本章的第一节中，你可以在图 10-5 中看到一个选择网格，它将单个模型上的add、change和delete权限分配给 Django 项目中的每个用户。在图 10-8 中，您可以看到一个等价的选择网格，为 Django 项目中的每个组分配相同类型的add、change和delete对单个模型的权限。

这些add、change和delete权限通过权限模型记录在数据库级别进行管理，这些记录是在您运行 Django 模型的第一次迁移时自动创建的。一旦创建了这些类型的权限，管理它们是非常简单的，因为分配是直接在用户上进行的——如图 10-5 所示——或者如图 10-8 所示的组。

Tip

模型权限数据存储在数据库表 auth_permission 中，该表还引用 django_content_type 表，该表维护已安装的 django 模型的列表。此外，模型权限-用户关系存储在数据库表 auth_user_user_permissions 中，模型权限-组关系存储在数据库表 auth_group_permissions 中。

与用户权限的行为类似，模型权限不一定局限于模型操作。例如，如果一个用户或组有一定的模型权限(例如，如果一个User有能力创建一个Store模型或改变一个Item模型，并允许访问一个页面或链接)，那么允许或拒绝访问一个视图或模板部分是完全可能的。

但是，下一节关于权限实施的内容将详细描述这些过程。接下来，我将描述如何为 Django 模型定制模型权限。

模型元权限选项:默认权限和权限

有时可能需要更改模型的默认权限。默认情况下，所有 Django 模型都被赋予了add、change和delete权限。尽管授予用户和组这些权限是由管理员决定的，但有时可能有必要从 Django 模型中删除部分或全部权限(例如，从数据敏感模型中删除change和delete权限)。

此外，有时可能还需要向不符合默认add、change和delete权限的模型添加自定义权限(例如，give_refund或can_hire等权限，用于分配用户/组访问应用某些部分的权限)。

要改变给予模型的默认权限(例如，add、change和delete，您可以使用模型的元类default_permissions字段。此外，您可以通过模型的元类permissions字段向模型的权限添加自定义权限。

清单 10-4 展示了一个利用模型元permissions和default_permissions字段的模型类。

class Store(models.Model):
    name = models.CharField(max_length=30)    
    address = models.CharField(max_length=30,unique=True)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    class Meta:

        default_permissions = ('add',)

        permissions = (('give_refund','Can refund customers'),('can_hire','Can hire employees'))

Listing 10-4.Customize a Django model’s permissions with default_permissions and permissions

注意，在清单 10-4 中，Store模型的default_permissions字段被设置为('add',)，这实际上删除了change和delete权限。如果您添加这个模型元语句，您会注意到Store模型的默认权限发生了变化，如 UI 图 10-10 所示。

图 10-10。

Custom default model permissions and custom model permissions

此外，在清单 10-4 中，请注意模型元权限字段设置了两个自定义权限:give_refund和can_hire，其中每个自定义权限由一个元组组成，第一个元素表示代码(在数据库中使用),第二个元素表示友好的 UI 名称。如果您添加这个模型元语句，您会注意到Store模型添加了这两个自定义权限，如 UI 图 10-10 所示。

权限检查和实施

现在您已经了解了不同类型的 Django 权限，我们可以探索如何在它们的主要上下文之外利用这些权限(例如，Django 管理之外的用户权限和 Django CRUD 操作之外的模型权限)。

接下来，您将学习如何在视图、URL、模板、模型和基于类的视图中更改和实施 Django 权限。

查看方法权限检查

因为视图方法处理传入的请求并将响应分派给最终用户，所以它们代表了实施权限检查的理想位置。例如，您可以使用查看方法的权限检查来返回不同的内容，这取决于用户是否登录(即，是User还是AnonymousUser)或者是超级用户、职员还是活动子类型。

清单 10-5 展示了一个视图方法逻辑内部的权限检查，根据用户的登录状态返回不同的结果，以及另一个使用装饰器根据用户的登录状态限制视图方法访问的变体。

# Internal check to see if user is anonymous or not
def homepage(request):
    if request.user.is_anonymous():
        # Logic for AnonymousUser
    else:
        # Logic for User

# Method check to see if user is logged in or not (i.e. a User)
from django.contrib.auth.decorators import login_required

@login_required
def profile(request):
    # Logic for profile

Listing 10-5.Permission check in view methods with internal checks and @login_required

Note

由于 Django 默认启用的AuthenticationMiddleware，所有视图方法请求(例如request.user)都可以使用User模型。关于 Django 中间件的更多细节，请参见第二章。

清单 10-5 中的第一个例子使用了所有User车型上可用的is_anonymous()方法——如表 10-2 所述。如果最后一种方法确定发出请求的用户是匿名的——这意味着他没有登录过——就会采取某种行动和响应。另一方面，如果is_anonymous()方法确定发出请求的用户已经登录，就会采取另一种行动和响应。

Tip

除了 is_anonymous 方法之外，您还可以使用任何用户模型字段或方法——在表 10-1 或表 10-2 中——来执行检查(例如，is_staff，is_superuser)。

清单 10-5 中的第二个例子使用@login_required()装饰器将整个视图方法限制为登录用户(即，具有User的请求和具有AnonymousUser的阻塞请求)。当预先知道 view 方法不需要像清单 10-5 中的第一个例子那样的条件许可工作流时，最后一个技术是很有帮助的。

还可以对视图方法执行权限检查，以验证用户是否符合特定的权限测试。例如，可以阻止属于特定组的用户或具有特定模型权限的用户使用查看方法。清单 10-6 展示了使用@user_passes_test和@permission_required装饰器的三个额外的视图方法权限检查。

# Method check to see if User belongs to group called 'Barista'
from django.contrib.auth.decorators import user_passes_test
from django.contrib.auth.models import Group

@user_passes_test(lambda u: Group.objects.get(name='Baristas') in u.groups.all())
def dashboard(request):
    # Logic for dashboard

# Explicit method check, if User is authenticated and has permissions to change Store model

# Explicit method with test
def user_of_stores(user):
    if user.is_authenticated() and user.has_perm("stores.change_store"):
        return True
    else:
        return False

# Method check using method
@user_passes_test(user_of_stores)
def store_manager(request):
    # Logic for store_manager

# Method check to see if User has permissions to add Store model

from django.contrib.auth.decorators import permission_required

@permission_required('stores.add_store')
def store_creator(request):
    # Logic for store_creator

Listing 10-6.Permission check in view methods with @user_passes_test and @permission_required

清单 10-6 中的第一个例子使用了@user_passes_test装饰器并定义了一个内嵌测试。代码片段lambda u: Group.objects.get(name='Baristas') in u.groups.all()获取名为Baristas的Group模型记录，并检查请求用户是否属于这个组。如果请求用户不属于Baristas组，则测试失败，访问被拒绝；否则，允许用户运行视图方法。

第二个例子也使用了@user_passes_test装饰器，但是它依赖于user_of_stores()方法来执行测试逻辑，而不是定义一个内联测试。如果测试很复杂，与常规方法相比，很难遵循内联逻辑，这一点尤其有用。正如您在清单 10-6 中看到的，user_of_stores()验证用户是否通过了身份验证，以及他是否拥有对Store模型的更新权限——注意字符串stores.change_store是 Django 的权限模型记录使用的语法。

清单 10-6 中的最后一个例子使用了@permission_required装饰器，用于验证用户是否有给定的Permission记录。在这种情况下，注意装饰器有一个输入字符串stores.add_store,它表明只有有权限添加Store模型的用户才能运行 view 方法。

What Happens When a User Fails a Permission Check?

对于内部验证检查(例如，在方法体中进行的检查，如if request.user.is_anonymous():)您拥有绝对控制权，因此您可以将用户重定向到任何页面，或者添加 flash 消息以显示在模板上。

对于装饰者验证检查@login_required、@user_passes_test和@permission_required，默认的失败行为是将用户重定向到 Django 的登录页面。Django 的默认登录页面 URL 是/account/login/，这个值可以用settings.py中的LOGIN_URL变量覆盖，我将在下一节中提供细节。

对于@permission_required装饰器，也可以通过添加raise_exception=True属性(例如@permission_required('stores.add_store',raise_exception=True))将失败的测试重定向到 Django 的 HTTP 403(禁止)页面。

URL 权限检查

在某些情况下，您可以拥有一个 Django 工作流，它不涉及视图方法，只是简单地将控制从 URL 直接发送到静态模板。在这种情况下，也可以直接对 URL 定义进行权限检查。清单 10-7 展示了类似清单 10-5 和 10-6 中应用于urls.py中 URL 定义的验证检查。

from django.conf.urls import  include, url
from django.views.generic import TemplateView

from django.contrib.auth.decorators import login_required,permission_required,user_passes_test
from django.contrib.auth.models import Group

urlpatterns = [
      url(r'^online/baristas/',
         user_passes_test(lambda u: Group.objects.get(name='Baristas') in u.groups.all())
         (TemplateView.as_view(template_name='online/baristas.html')),name="onlinebaristas"),
      url(r'^online/dashboard/',
         permission_required('stores.add_store')
         (TemplateView.as_view(template_name='online/dashboard.html')),name="onlinedashboard"),
      url(r'^online/',
         login_required(TemplateView.as_view(template_name='online/index.html')),name='online'),
]

Listing 10-7.Permission checks in urls.py for static templates

正如您在清单 10-7 中看到的，导入所需的装饰器后，您只需要在 URL 定义中集成验证测试。@user_passes_test和@permission_required装饰器被声明为独立的方法，后跟 URL 定义(例如，user_pass_test()(TemplateView.as_view...))。@login_required装饰器将TemplateView语句作为其输入。应该指出的是，清单 10-7 中失败测试的行为与清单 10-5 和 10-6 中的行为相同，在侧栏“当用户权限检查失败时会发生什么？"

验证检查的另一种可能性是在一组视图方法/URL 上执行它们，这样就不用给每个单独的视图方法添加装饰器了——如清单 10-6 所示——你只需要为整个组做一次。当通过include()方法在urls.py中定义 URL 时，这种视图方法/URL 分组过程尤其常见。清单 10-8 展示了如何对使用include()方法的 URL 集合进行验证检查。

from django.conf.urls import include, url
from django.core.urlresolvers import RegexURLResolver, RegexURLPattern

class DecoratedURLPattern(RegexURLPattern):
    def resolve(self, *args, **kwargs):
        result = super(DecoratedURLPattern, self).resolve(*args, **kwargs)
        if result:
            result.func = self._decorate_with(result.func)
        return result

class DecoratedRegexURLResolver(RegexURLResolver):
    def resolve(self, *args, **kwargs):
        result = super(DecoratedRegexURLResolver, self).resolve(*args, **kwargs)
        if result:
            result.func = self._decorate_with(result.func)
        return result

def decorated_includes(func, includes, *args, **kwargs):
    urlconf_module, app_name, namespace = includes
    patterns = getattr(urlconf_module, 'urlpatterns', urlconf_module)    
    for item in patterns:
        if isinstance(item, RegexURLPattern):
            item.__class__ = DecoratedURLPattern
            item._decorate_with = func

        elif isinstance(item, RegexURLResolver):
            item.__class__ = DecoratedRegexURLResolver
            item._decorate_with = func

    return urlconf_module, app_name, namespace

from django.contrib.auth.decorators import login_required,permission_required,user_passes_test
from django.contrib.auth.models import Group

from coffeehouse.items.urls import urlpatterns as drinks_url_patterns

urlpatterns = [
    url(r'^items/',
       decorated_includes(login_required,include(items_url_patterns,namespace="items"))),
    url(r'^stores/',
      decorated_includes(permission_required('stores.add_store'),
      include('coffeehouse.stores.urls',namespace="stores"))),
    url(r'^social/',
      decorated_includes(user_passes_test(lambda u: Group.objects.get(name='Baristas') in u.groups.all()),
      include('coffeehouse.social.urls',namespace="social"))),
]

Listing 10-8.Permission checks in urls.py for include() definitions

因为 Django 在include()定义中没有内置的权限检查支持，你可以在清单 10-8 中看到，我们首先定义了两个自定义类，然后是自定义方法decorated_includes。如果您按照清单 10-8 中的顺序，您可以看到decorated_includes()方法接受两个输入参数，首先是权限测试(例如login_required、permission_required)，然后是带有 URL 定义的标准include()方法。还应该指出的是，清单 10-8 中失败测试的行为与之前清单中的行为相同，在侧栏“当用户权限检查失败时会发生什么？”

模板权限检查

Django 项目中另一个可用的权限检查是在模板中，如果您想根据用户的权限显示/隐藏内容(例如链接)，这个过程会很有帮助。清单 10-9 展示了一系列 Django 模板语法示例。

{% if user.is_authenticated %}
   {#  Content for authenticated users  #}
{% endif %}

{% if perms.stores.add_store %}
   {#  Content for users that can add stores #}
{% endif %}

{% for group in user.groups.all %}
   {% if group.name == 'Baristas'  %}
        {# Content for users with 'Baristas' group #}
   {% endif %}
{% endfor %}

Listing 10-9.Permission checks in templates

Note

由于 Django 的auth上下文处理器，用于在模板中执行权限检查的user和 perms 变量是可用的，该处理器在默认情况下是启用的——参见第三章关于 Django 上下文处理器使用的详细信息。

您可以在清单 10-9 中看到，所有模板语法示例都使用了user和perms变量来执行条件权限检查。第一个例子检查用户是否通过了is_authenticated的认证。第二个例子使用 Django 的权限语法stores.add_store验证持有用户权限的perms是否有权创建Store模型记录。清单 10-9 中的第三个例子遍历一个用户组，检查用户是否在Baristas组中；如果是，它将为这类用户输出内容。

Tip

Django 模板中检查属性的循环效率非常低。尽管清单 10-9 中的最后一个例子可以工作，但这是一个非常低效的机制。更好的解决方案是创建一个自定义过滤器，并在过滤器中执行直接查询(例如，{ % if user|has_group:"Baristas" %}，其中has_group过滤器包含大部分逻辑检查)。在这种情况下，我选择了清单 10-9 中的语法，将所有内容放在一个地方，但是要知道，对于这种类型的逻辑，更有效的解决方案是使用第三章中描述的自定义过滤器。

基于类的查看权限检查

正如你在第二章和第九章的结尾所学到的，基于类的视图为视图方法中包含的逻辑提供了更好的可重用性和封装。然而，由于基于类的视图的组成方式，它们需要一种不同于清单 10-5 和 10-6 中常规视图方法的方法来检查权限。

虽然从技术上来说，您可以在基于类的视图中检查权限——就像在标准视图方法中一样——通过定义基于类的视图的get()和/或post()方法，这种技术也迫使您声明视图的大部分逻辑，如果您试图做的只是合并权限检查，这在基于类的视图中是低效的。

清单 10-10 展示了在基于类的视图中执行权限检查的一系列选项。

from django.views.generic import ListView
from django.views.generic.detail import DetailView
from django.views.generic.edit import CreateView, UpdateView, DeleteView
from django.utils.decorators import method_decorator
from django.core.urlresolvers import reverse_lazy
from django.contrib.messages.views import SuccessMessageMixin

from django.contrib.auth.decorators import login_required,user_passes_test
from django.contrib.auth.models import Group

from django.contrib.auth.mixins import LoginRequiredMixin, UserPassesTestMixin, PermissionRequiredMixin

class ItemList(LoginRequiredMixin,ListView):
    model = Item
    context_object_name = 'items'
    template_name = 'items/index.html'

class ItemDetail(UserPassesTestMixin,DetailView):
    model = Item
    pk_url_kwarg = 'item_id'    
    template_name = 'items/detail.html'
    def test_func(self):

        return self.request.user.is_authenticated

class ItemCreation(PermissionRequiredMixin,SuccessMessageMixin,CreateView):
    model = Item
    form_class = ItemForm
    success_url = reverse_lazy('items:index')
    success_message = "Item %(name)s created successfully"
    permission_required = ('items.add_item',)

@method_decorator(login_required, name='dispatch')
class ItemUpdate(SuccessMessageMixin,UpdateView):
    model = Item
    pk_url_kwarg = 'item_id'    
    form_class = ItemForm
    success_url = reverse_lazy('items:index')
    success_message = "Item %(name)s updated successfully"

@method_decorator(user_passes_test(lambda u: Group.objects.get(name='Baristas') in u.groups.all()), name='dispatch')
class ItemDelete(DeleteView):
    model = Item
    pk_url_kwarg = 'item_id'    
    success_url = reverse_lazy('items:index')

Listing 10-10.Permission checks in class-based views

清单 10-10中的第一个基于类的视图使用LoginRequiredMixin mixin 来强制只有登录的用户才能访问基于类的视图。第二个基于类的视图ItemDetail使用另一个名为UserPassesTestMixin的 mixin 来确保只有通过权限测试的用户才被允许访问基于类的视图。要为使用UserPassesTestMixin mixin 的基于类的视图定义权限测试，请注意使用了test_func()方法。最后一个方法通过self.request获得对用户的访问权，并基于测试返回一个True或False值，在清单 10-10 中只需调用is_authenticated即可。

清单 10-10 ItemCreation中的第三个基于类的视图使用PermissionRequiredMixin mixin 来强制只有拥有特定模型权限的用户才被允许访问基于类的视图。为了在使用PermissionRequiredMixin mixin 的基于类的视图上声明模型权限，使用了带有权限元组值的permission_required选项。在清单 10-10 的情况下，('items.add_item',)值遵循模型权限语法<app_name>.<app_permission>，确保只有有权向items应用添加Item记录的用户才被允许访问基于类的视图。

清单 10-10和ItemDelete中最后两个基于类的视图利用@method_decorator装饰器来实施基于类的权限。@method_decorator装饰器是专门为将标准视图方法装饰器——如清单 10-5 和 10-6 中使用的那些——应用于基于类的视图方法而设计的，它接受两个参数:一个装饰器和基于类的视图方法，在该方法上应用装饰器。在清单 10-10 的例子中，您可以看到ItemUpdate基于类的视图将login_required装饰器应用于dispatch()方法，只允许登录的用户访问基于类的视图。而ItemDelete基于类的视图将user_passes_test装饰器应用于dispatch()方法，只允许属于Baristas组的用户访问基于类的视图。

用户认证和自动管理

在本章的第一节中，您学习了如何创建用户。但是回想一下，要使这个过程正常工作，您要么必须使用 Django 命令行工具，要么必须使用 Django admin。这些技术虽然有效，但并不是为访问应用的最终用户设计的，也不会扩展。

类似地，到本章的这一点为止，用户登录和注销的唯一位置是通过 Django admin 认证表单。最后一种形式对最终用户来说也不是理想的位置，不仅因为它缺少为应用设计的布局，还因为它不适合从不打算与项目数据库交互的用户。

如果您计划让最终用户在应用中进行身份验证，那么您需要为用户提供一种注册、登录和注销的方式，以及让用户记住和更改密码的方式。支持User模型的同一个django.contrib.auth包还包括一系列用于创建用户认证工作流的预构建结构。

第一个可用于验证用户身份的预建机制是一组 URL，允许用户登录和注销应用，允许用户更改他们的密码，以及允许用户通过电子邮件通知重置他们的密码。

清单 10-11 展示了如何将全套的django.contrib.authURL 添加到主urls.py文件中——使用一条include语句——以及等效的单个url语句，以防您想要有选择地挑选在项目中使用哪些 URL。

from django.conf.urls import url
from django.contrib.auth import views

# Option 1 to include all urls (See option 2 for included urls)
urlpatterns = [
    url(r'^accounts/', include('django.contrib.auth.urls')),
]

# Option 2) (Explicit urls, all included in django.contrib.auth)
urlpatterns = [
    url(r'^accounts/login/$', views.LoginView.as_view(), name='login'),
    url(r'^accounts/logout/$', views.LogoutView.as_view(), name='logout'),

    url(r'^accounts/password_change/$', views.PasswordChangeView.as_view(), name='password_change'),
    url(r'^accounts/password_change/done/$', views.PasswordChangeDoneView.as_view(), name='password_change_done'),

    url(r'^accounts/password_reset/$', views.PasswordResetView.as_view(), name='password_reset'),
    url(r'^accounts/password_reset/done/$', views.PasswordResetDoneView.as_view(), name='password_reset_done'),
    url(r'^accounts/reset/(?P<uidb64>[0-9A-Za-z_\-]+)/(?P<token>[0-9A-Za-z]{1,13}-[0-9A-Za-z]{1,20})/$',
        views.PasswordResetConfirmView.as_view(), name='password_reset_confirm'),
    url(r'^accounts/reset/done/$', views.PasswordResetCompleteView.as_view(), name='password_reset_complete'),
]

Listing 10-11.Configure urls from django.contrib.auth package

清单 10-11 中的第一个选项在accounts url 上配置所有的django.contrib.authURL。这引发了一个问题，为什么是accounts的网址？因为，默认情况下，所有的django.contrib.auth动作都使用这个 url 作为它们的根(例如，在前面的章节中，回想一下试图访问需要登录的资源会执行到/accounts/login的重定向)。因此，通过将这个 url include()语句与django.contrib.auth.urls一起使用，所有的django.contrib.auth动作都获得了一个有效的 url，它也得到必要的视图方法逻辑的支持！但是稍后将更多地讨论视图方法逻辑。

因为 url include()语句有一个‘使用所有 url 或者不使用’的行为，清单 10-11 中的第二个选项代表使用粒度 url 语句来配置相同的django.contrib.authURL。如果您想要禁用某些django.contrib.authURL，但仍保持其他django.contrib.authURL 活动(例如，禁用密码更改 URL，但保持登录和注销 URL)，最后一个选项很有帮助。

正如你所看到的，使用清单 10-11 中的任一选项都可以为你提供一个快速的解决方案，将django.contrib.auth动作连接到 URL，后者也被连接到默认的基于类的视图，这些视图也是django.contrib.auth包的一部分。

登录和注销工作流

登录和注销工作流的入口点——如清单 10-11 所示——分别是/accounts/login/和/accounts/logout/URL。如果在/accounts/login/ url 上进行调用，则触发django.contrib.auth.views.LoginView基于类的视图，如果在/accounts/logout/ url 上进行调用，则触发django.contrib.auth.views.LogoutView基于类的视图。

像所有 Django 内置的基于类的视图一样，LoginView和LogoutView基于类的视图在代码和配置方面几乎不需要任何东西。它们唯一需要的是一个显示登录表单的模板和一个显示注销成功消息的模板。

LoginView基于类的视图在定义为settings.py中TEMPLATES/DIRS变量一部分的目录下寻找模板registration/login.html。并且LogoutView基于类的视图寻找模板registration/logout.html，也在定义为settings.py中TEMPLATES/DIRS变量的一部分的目录下。

Tip

关于registration/login.html和registration/logout.html模板所需的布局和字段，请参见本书附带的源代码。

登录工作流在settings.py中提供了两个配置选项，允许您修改其行为，而无需定制LoginView基于类的视图。LOGIN_URL变量默认为/accounts/login/，当用户试图访问需要认证的资源但没有登录时，它被用作重定向到的 url。LOGIC_REDIRECT变量默认为/accounts/profile/，是用户成功登录后被重定向到的 url。django.contrib.auth包没有为/accounts/profile/ url 提供入口点，因此您必须要么配置这个 url，要么简单地将其更改到不同的位置(例如，LOGIN_REDIRECT='/'在成功登录后将用户重定向到主页)。

注销工作流支持settings.py中的LOGOUT_REDIRECT变量来定义用户注销时被带到哪里。LOGOUT_REDIRECT变量默认为/accounts/logout/，但是可以更新以将用户重定向到不同的位置(例如，LOGOUT_REDIRECT='/'在用户注销后将用户重定向到主页)。

除了创建模板、设置 url——如清单 10-11 所述——以及可选地更改登录 URL 位置和登录/退出重定向行为，您不需要做任何其他事情来启用由django.contrib.auth包提供的登录和注销工作流。如果你想让用户登录，只需将他们指向/accounts/login/ url，如果你想让他们退出，将他们指向/accounts/logout/ url。所有其他工作流细节(例如，身份验证、密码验证、错误表单处理、会话到期)由LoginView和LogoutView基于类的视图负责。

密码更改工作流

密码更改工作流需要两个 url 入口点:触发PasswordChangeView基于类的视图的/accounts/password_change/ url 和触发PasswordChangeDoneView基于类的视图的/accounts/password_change/done/ url。

PasswordChangeView基于类的视图在定义为settings.py中的TEMPLATES/DIRS变量的一部分的目录下寻找一个包含表单的模板，以更改registration/password_change_form.html中的密码。并且PasswordChangeDoneView基于类的视图在registration/password_change_done.html中寻找包含成功消息的模板，也在定义为settings.py中TEMPLATES/DIRS变量的一部分的目录下。

Tip

关于registration/password_change_form.html和registration/password_change_done .html模板所需的布局和字段，请参见本书附带的源代码。

除了创建模板和设置 urls 如清单 10-11 所述——您不需要做任何其他事情来启用django.contrib.auth包提供的密码更改工作流。如果你想让用户修改他的密码，只需将他们指向/accounts/password_change/ url。所有其他工作流细节(例如，密码验证、数据库更新、表单错误处理)由PasswordChangeView和PasswordChangeDoneView基于类的视图负责。

密码重置工作流程

密码重置工作流由两个子工作流组成。第一个子工作流捕获用户的电子邮件，并向他发送一封包含重置密码链接的电子邮件。第二个子工作流处理重置链接并验证用户的新密码。

第一个子工作流使用/accounts/password_reset/ url，它触发PasswordResetView基于类的视图，以及/accounts/password_reset/done/ url，它触发PasswordResetDoneView基于类的视图。第二个子工作流使用/accounts/reset/ url，它触发PasswordResetConfirmView基于类的视图，以及/accounts/reset/done/ url，它触发PasswordResetCompleteView基于类的视图。

基于PasswordResetView类的视图在registration/password_reset_form.html中寻找包含重置用户密码表单的模板，基于PasswordResetDoneView类的视图在registration/password_reset_done.html中寻找成功消息模板，这两个视图都位于定义为settings.py中TEMPLATES/DIRS变量一部分的目录下。对于第二个子工作流，PasswordResetConfirmView基于类的视图在registration/password_reset_confirm.html中寻找带有引入新用户密码的表单的模板，而PasswordResetCompleteView基于类的视图在registration/password_reset_complete.html中寻找成功消息模板，这两个视图都位于定义为settings.py中TEMPLATES/DIRS变量的一部分的目录下。

默认情况下，密码重置工作流会生成一封电子邮件，其中包含将用户带到第二个子工作流以重置其密码的说明。同样默认情况下，重置电子邮件包含一个到域localhost:8000的链接，可以通过安装 Django 站点django.contrib.sites应用进行定制(例如，将django.contrib.sites添加到INSTALLED_APPS和settings.py中的SITE_ID=1，并在 Django 管理中更新 id 为 1 的站点以反映一个新的域)。此外，您可以在registration/password_reset_email.html模板中定义一个定制的电子邮件布局，并将其放在一个目录下，该目录被定义为settings.py中TEMPLATES变量的一部分。

Tip

关于registration/password_reset_form.html, registration/password_reset_done.html、registration/password_reset_confirm.html、registration/password_reset_complete.html和registration/password_reset_email.html模板所需的布局和字段，请参见本书随附的源代码。

除了创建模板和设置 urls 如清单 10-11 所述——以及可选地更改默认的电子邮件布局之外，您不需要做任何其他事情来启用或允许用户使用django.contrib.auth包提供的工作流记住他们的密码。如果你想让用户记住他的密码，只需将他们指向/accounts/password_reset/ url。所有其他工作流细节(例如，电子邮件令牌验证、密码验证、数据库更新、表单错误处理)由PasswordResetView、PasswordResetDoneView、PasswordResetConfirmView和PasswordResetCompleteView基于类的视图负责。

用户注册工作流

用户可以在来自django.contrib.auth包的一些构造的帮助下自动注册一个 Django 应用。尽管用户注册工作流不像以前的用户相关工作流那样嵌入到django.contrib.auth包中，但是仍然很容易创建。

创建用户注册工作流的第一步是配置一个 url 入口点，以允许用户创建一个帐户，如清单 10-12 所示。

# urls.py main
from django.conf.urls import url
from django.contrib.auth import views

from coffeehouse.registration import views as registration_views

urlpatterns = [
    url(r'^accounts/', include('django.contrib.auth.urls')),
    url(r'^accounts/signup/$',registration_views.UserSignUp.as_view(),name="signup"),    
]

Listing 10-12.Configure url for user sing up workflow

清单 10-12 展示了一个在/accounts/signup/可访问的 url，此外还有由django.contrib.auth包提供的所有 URL，包括之前与用户相关的工作流。请注意，/accounts/signup/ url 被设置为由来自coffeehouse.registration应用的UserSignUp基于类的视图处理，这意味着您需要为项目创建一个基于类的视图。

清单 10-13 展示了负责用户注册工作流的UserSignUp基于类的视图，它自动创建User模型记录，这在以前是使用 Django 命令行工具或 Django admin 完成的。

from django.core.urlresolvers import reverse_lazy
from django.http import HttpResponseRedirect
from django.contrib.messages.views import SuccessMessageMixin

from django.contrib.auth.forms import UserCreationForm
from django.contrib.auth.models import User
from django.contrib.auth import authenticate, login

class UserSignupForm(UserCreationForm):
    email = forms.EmailField(required=True)
    class Meta:
        model = User
        fields = ("username", "email", "password1", "password2")

class UserSignUp(SuccessMessageMixin,CreateView):
    model = User
    form_class = UserSignupForm
    success_url = reverse_lazy('items:index')
    success_message = "User created successfully"
    template_name = "registration/signup.html"
    def form_valid(self, form):
        super(UserSignUp,self).form_valid(form)        
        # The form is valid, automatically sign-in the user
        user = authenticate(self.request, username=form.cleaned_data['username'],
                                                 password=form.cleaned_data['password1'])
        if user == None:
            # User not validated for some reason, return standard form_valid() response
            return self.render_to_response(self.get_context_data(form=form))            
        else:
            # Log the user in
            login(self.request, user)
            # Redirect to success url
            return HttpResponseRedirect(self.get_success_url())

Listing 10-13.Signup workflow fulfilled by custom CreateView class-based view

清单 10-13 中的UserSignUp基于类的视图是一个标准的CreateView基于类的视图，它使用 mixinSuccessMessageMixin——如果你不熟悉这种基于类的视图来创建模型记录或 mixin 的概念，请参阅上一章，其中解释了这两个主题。

UserSignUp基于类的视图将模型选项设置为User,告诉 Django 创建django.contrib.auth.models.User记录。接下来，将form_class选项设置为UserSignupForm，这也在清单 10-13 中定义。接下来是success_url和success_message选项，用于在创建User记录时指示 url 和成功消息，以及template_name选项，用于指定一个带有表单的模板，以捕获User字段。

清单 10-13 中的自定义UserSignupForm模型表单基于django.contrib.auth包中的UserCreationForm。从实用的角度来看，UserSignUp基于类的视图可以使用UserCreationForm作为它的form_class，然而，这个最后的内置表单只包含username和password字段。在这种情况下，作为用户注册过程的一部分，定制的UserSignupForm模型表单将email字段添加到基础UserCreationForm表单类中。请注意，因为支持User模型已经包含了一个email字段，所以不需要对模型进行修改。

为了在创建了User模型记录后自动登录用户，UserSignUp基于类的视图在其form_valid()方法中包含了定制逻辑。在清单 10-13 的例子中，来自django.contrib.auth包的authenticate方法被表单值调用，验证凭证是否有效。如果凭证是有效的——给定工作流应该是 100%的时间，除非发生不可预见的黑客事件——authenticate方法返回一个User实例并立即执行login方法——也来自django.contrib.auth包——创建一个用户会话(即登录),之后控制被重定向到基于类的视图的成功页面。在不可预见的事件中，authenticate方法没有返回一个User实例，form_valid()方法返回它的标准有效载荷，也就是经过验证的形式。

从清单 10-12 和 10-13 中可以看到，您可以创建一个用户注册工作流，让用户创建自己的帐户，并减轻从 Django admin 或 Django 命令行工具创建用户帐户的管理负担。

Tip

清单 10-13 中的注册工作流是许可的，因为它不验证电子邮件并自动让用户登录。这样做是为了简单，并且可能适用于大多数项目。但是您可以在创建User记录之前或之后，通过将此逻辑添加到不同的基于类的视图方法中，为注册工作流添加额外的保护措施(例如，发送验证链接，将用户设置为非活动，直到验证链接被点击)。

Tip 2

Django allauth 包(将在本章后面介绍)内置了对电子邮件验证的支持。

自定义用户模型字段

默认的 Django User模型(即django.contrib.auth.models.User类)使用最小的一组数据字段，包括username、email、first_name、last_name、date_joined和last_login；除了权限相关字段password、is_superuser、is_staff和is_active。

虽然最后这些字段对于 Django 的内置用户功能来说已经足够了，但是如果您希望存储额外的用户数据(例如年龄、电话、地址)，它们就不够用了。有两种方法可以支持额外的用户数据:创建一个单独的模型来存储额外的数据，并创建一个与之相关的用户关系(例如，一个带有ForeignKey的User)或者覆盖默认的django.contrib.auth.models.User类来创建一个定制的用户类。

清单 10-14 通过创建一个额外的模型来存储额外的用户数据并创建一个与django.contrib.auth.models.User类的关系来展示第一种技术。

from django.contrib.auth.models import User
from django.db import models

class UserExtra(models.Model):
    user = models.ForeignKey(User)
    age = models.IntegerField(blank=True,null=True)
    telephone = models.CharField(max_length=15,blank=True,null=True)

Listing 10-14.Model with extra user fields related to default Django user model

清单 10-14 中的UserExtra模型的功能类似于任何其他具有ForeignKey数据类型的模型，因此，在这些情况下使用时，会涉及一些性能和维护问题。另一方面，用户数据分布在两个数据库表中。一个表用于User记录，另一个表用于UserExtra记录，这不可避免地需要两个查询或一个连接查询来获取给定用户的所有数据——参见第七章了解跨模型关系的查询。从积极的方面来看，这种技术保持了项目的默认 Django User模型类的完整性，不需要额外的配置或开发工作。

接下来，让我们看看第二种技术，它包括创建一个定制的用户类，这个过程在清单 10-15 中进行了说明。

# models.py (app registration)
from django.contrib.auth.models import AbstractUser
from django.db import models

class CoffeehouseUser(AbstractUser):
    age = models.IntegerField(blank=True,null=True)
    telephone = models.CharField(max_length=15,blank=True,null=True)

# admin.py (app registration)
from django.contrib import admin
from .models import CoffeehouseUser

class CoffeehouseUserAdmin(admin.ModelAdmin):
    pass

admin.site.register(CoffeehouseUser, CoffeehouseUserAdmin)

# settings.py
AUTH_USER_MODEL = 'registration.CoffeehouseUser'

Listing 10-15.Custom User model to override default Django User model

清单 10-15 中的第一部分显示了用作定制用户类的CoffeehouseUser类。注意这个类从AbstractUser类继承了它的行为，这个类给了它与默认的User类相同的字段和行为(例如username、email等)。).接下来，CoffeehouseUser类使用标准模型字段声明了age和telephone字段，为定制用户类提供了比默认User类多两个字段。

因为自定义的CoffeehouseUser类将覆盖项目的默认User类，这意味着默认的django.contrib.auth.models.User类不再被使用。因此，您必须配置 Django，以便在任何需要用户逻辑的地方使用定制的CoffeehouseUser类。

清单 10-15 中的第二部分展示了从 Django admin 访问新的定制用户类所必需的 Django admin 配置，并且能够创建、读取、更新和删除用户，就像用标准的django.contrib.auth.models.User模型类所做的一样。注意下一章将更详细地介绍 Django 管理配置。

最后，清单 10-15 中的第三部分显示了 Django settings.py文件，其中AUTH_USER_MODEL设置为registration.CoffeehouseUser，其中registration表示应用名称，CoffeehouseUser表示定制用户模型。这最后一个配置确保整个项目中的用户逻辑是在CoffeehouseUser模型而不是默认的User模型上生成的。

一旦您使用清单 10-15 中的定制用户模型类和配置运行迁移操作，您将看到 Django 项目用户获得了两个额外的字段。

Caution

类似于清单 10-15 中的定制用户模型实现应该只在项目开始时进行(例如，第一批项目迁移之一)。

因为用户模型在管理对 Django 项目的访问中起着如此重要的作用，所以您不应该试图在项目中途实现定制的用户模型，如清单 10-15 中所示。这样做有破坏依赖关系(外键)的风险，这些依赖关系被其他模型用来引用默认的django.contrib.auth.models.User模型记录；此外，这还会更改存储用户数据的底层数据库表。通过在项目开始时实现自定义用户模型，您可以保证对用户进行的任何可能的模型依赖都是针对自定义用户记录进行的，并且用户数据从一开始就存储在单个数据库表中。

事实上，如果您计划使用自定义用户模型，但不知道一开始要添加哪些新字段，您可以创建一个占位符用户模型，如下所示:

class CoffeehouseUser(AbstractUser):
      pass

这个代码片段创建了一个与默认的django.contrib.auth.models.User类相同的模型，但是为在定制模型上创建用户依赖关系打下了基础，同时允许向定制模型添加字段，因为像任何其他模型一样，标准迁移需要这些字段。

最后，使用定制用户模型时要考虑的另一个因素——在清单 10-15 中并不明显——是如何在项目的其他地方引用定制用户模型。当您使用默认的User类时，语句from django.contrib.auth.models import User在models.py和views.py文件中引用用户是常见的，但是对于定制模型，这种引用不再适用。

为了支持定制用户模型，Django 提供了助手方法get_user_model，该方法返回对在settings.py的AUTH_USER_MODEL变量中定义的任何用户模型的引用。以这种方式，您可以使用语句from django.contrib.auth import get_user_model从项目中的任何地方获得对项目用户模型的引用。下一节包含一个使用get_user_model方法的例子。

自定义身份验证后端

身份验证过程非常重要，因为它决定了允许哪些用户访问应用。Django 使用的默认认证过程包括将用户名和密码(在 web 表单上提供)与数据库中的User记录进行比较。如果用户名和密码与User记录匹配，则认证过程被认为是成功的，但是如果值不匹配，则认证过程被认为是失败的。

Django 本身包括一系列内置的认证后端类 ² 来支持这个认证过程的变化。此外，在本章的最后一节，我将向您介绍 allauth Django 包，它支持一系列的认证后端(例如，针对社交媒体帐户的认证)。

但是为了从头开始说明自定义身份验证后端的概念，我将创建一个简单的身份验证后端，它依赖于电子邮件进行身份验证，并且可以使用任何用户类型(即自定义用户模型或默认的User模型)。

默认情况下，Django 项目使用django.contrib.auth.backends.ModelBackend身份验证后端类，用于将最终用户提供的用户名和密码集与数据库中的项目用户进行比较。现在问问你自己，你认为登录凭证、用户名或电子邮件哪个更容易记住？如果你和这个时代的大多数人一样，你很可能已经回复了邮件。

清单 10-16 展示了一个定制的认证后端，它能够通过电子邮件凭证而不是默认用户名来认证用户。

# models.py (registration app)
from django.contrib.auth import get_user_model

class EmailBackend(object):
    def authenticate(self, request, username=None, password=None, **kwargs):
        User = get_user_model()
        try:
            user = User.objects.get(email=username)
        except User.DoesNotExist:
            return None
        else:
            if getattr(user, 'is_active', False) and  user.check_password(password):
                return user
        return None
    def get_user(self, user_id):
        User = get_user_model()        
        try:
            return User.objects.get(pk=user_id)
        except User.DoesNotExist:
            return None

# setting.py
AUTHENTICATION_BACKENDS = ['django.contrib.auth.backends.ModelBackend',       
                                 'coffeehouse.registration.models.EmailBackend']

Listing 10-16.Custom authentication back end to support authentication with email

清单 10-16 为定制认证后端声明了EmailBackend类。像所有定制认证后端类一样，您必须至少声明authenticate()和get_user()方法，其中第一个方法用于定义认证逻辑，第二个方法用于返回请求的用户。

作为基本身份验证工作流的一部分，authenticate()方法可以访问终端用户提供的username和password字段。接下来，您可以看到authenticate()方法依靠get_user_model()方法助手获得了对项目用户模型的访问，这确保了即使项目使用定制用户模型，认证工作流也是在正确的用户类上完成的，如前一节所述。

一旦获得了对项目的用户类的引用，请注意，authenticate()方法使用提供的username在email字段上为用户执行查询，这有效地允许将用户提供的username值作为电子邮件字段进行身份验证。如果用户匹配作为username值提供的电子邮件，那么清单 10-16 中的try-except-else块调用check_password()来验证匹配用户的密码。如果密码匹配，authenticate()返回认证用户，如果密码不匹配，authenticate()返回None。

清单 10-16 中的最后一部分是settings.py中的AUTHENTICATION_BACKENDS变量，它被分配了一个认证后端类列表。在这种情况下，保留默认的django.contrib.auth.backends.ModelBackend类，以确保首先尝试用户名/密码的默认认证工作流。接下来，添加清单 10-16 中的自定义EmailBackend身份验证后端类，以确保身份验证工作流将输入数据视为电子邮件/密码集。

从清单 10-16 中的例子可以看出，通过添加这个简单的定制身份验证后端类，您可以允许用户输入他们的用户名或电子邮件来在 Django 应用中进行身份验证。

Tip

如果您使用清单 10-16 中的自定义身份验证后端类，请将登录表单中的用户名标签更改为‘用户名/电子邮件’,以通知用户他们可以同时使用这两个类别。

Django allauth 的用户管理

正如您在本章中所看到的，django.contrib.auth包提供了大量管理用户和组、权限以及认证工作流的功能。但是您可能也意识到了，django.contrib.auth包也可能会受到很多遗留行为的影响，这些行为在当今时代不适用于 web 应用。例如，django.contrib.auth不支持社交认证之类的东西——这几乎是当今互联网的一项要求——此外，django.contrib.auth还被设计为使用开箱即用的用户名，而不是电子邮件——这也是一种非常过时的做法。

仍然因为django.contrib.auth包被构建到 Django 中，所以经常有许多 Django 包(例如，Django admin 和其他第三方包)假定 Django 项目使用django.contrib.auth包及其功能。

因此，一方面，您必须继续使用django.contrib.auth包来维护跨其他 Django 包的用户管理兼容性，这些 Django 包需要使用django.contrib.auth，但另一方面，您不希望被 2005 年的做法所束缚，即要求用户提供用户名，并且不允许他们使用社交媒体帐户进行身份验证。

在众多可用于解决 Django 用户管理集成的第三方包和潜在解决方案中，Django allauth 包提供了最佳功能集之一(例如，基于社交认证和电子邮件的用户)，以及与django.contrib.auth包的最佳集成。接下来，我将描述 Django allauth 包的设置过程。

安装并设置 django-allauth

要安装 Django allauth 包，使用下面的pip语句:

pip install django-allauth

安装完成后，让我们创建一个基本的 Django allauth 配置，以实现以下用户管理特性:

使用 email 作为主要的用户标识符，但是保留用户名凭证以与其他包兼容(例如 Django admin)。
要求电子邮件验证，以避免垃圾用户。
为添加 Django 社交认证(脸书、谷歌、Twitter)奠定基础。)

清单 10-17 展示了对项目的settings.py文件进行必要的添加，以使一个基本 Django allauth 配置具备这些特性。

# Ensure the 'django.contrib.sites' is declared in INSTALLED_APPS
# And also add the allauth, allauth.account and allauth.socialaccount to INSTALLED_APPS

INSTALLED_APPS = [
    # Django sites app  required
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
]

# Ensure SITE_ID is set sites app
SITE_ID = 1

# Add the 'allauth' backend to AUTHENTICATION_BACKEND and keep default ModelBackend
AUTHENTICATION_BACKENDS = [ 'django.contrib.auth.backends.ModelBackend',
                           'allauth.account.auth_backends.AuthenticationBackend']

# EMAIL_BACKEND so allauth can proceed to send confirmation emails
# ONLY for development/testing use console
EMAIL_BACKEND='django.core.mail.backends.console.EmailBackend'

# Custom allauth settings
# Use email as the primary identifier
ACCOUNT_AUTHENTICATION_METHOD = 'email'
ACCOUNT_EMAIL_REQUIRED = True
# Make email verification mandatory to avoid junk email accounts
ACCOUNT_EMAIL_VERIFICATION = 'mandatory'
# Eliminate need to provide username, as it's a very old practice
ACCOUNT_USERNAME_REQUIRED = False

Listing 10-17.Base Django allauth settings.py configuration

除了清单 10-17 到settings.py文件的变化之外，您还需要在主urls.py文件中注册 Django allauth url 入口点。清单 10-18 展示了您需要对主urls.py文件进行的修改。

urlpatterns = [
    ...
    url(r'^accounts/', include('allauth.urls')),
    ...
]
Listing 10-18.Django allauth url configuration urls.py

正如您在清单 10-18 中看到的，url 正则表达式告诉 Django 在/accounts/路径下挂载 Django allauthallauth.urlsURL，就像清单 10-11 中对标准 Django django.contrib.auth包 URL 所做的那样。

Django allauth 使用与标准django.contrib.auth包几乎完全相同的 url 模式和行为。这意味着 Django allauth 将其登录页面配置在/accounts/login/ url，注销页面配置在/accounts/logout/ url。Django allauth 确实在清单 10-18 的include()语句中包含了一系列新的 URL(例如，电子邮件验证)，但是我将在我们继续讨论时描述这些新的 URL。

类似地，标准django.contrib.auth包用于认证目的的相同settings.py变量也适用于 Django allauth。例如，您可以设置LOGIN_URL来覆盖默认的/accounts/login/ url 位置，也可以设置默认为/accounts/profile/ url 的LOGIN_REDIRECT_URL。事实上，就像django.contrib.auth包一样，Django allauth 不包含/accounts/profile/ url 入口点，所以您也可以覆盖settings.py中的LOGIN_REDIRECT_URL变量以指向另一个 url(例如，LOGIN_REDIRECT_URL='/'在成功登录后将用户重定向到主页)。

最后，一旦您完成了这些配置步骤，您需要执行以下其他步骤来确保 Django allauth 正确运行:

从命令行运行python manage.py migrate,确保 Django allauth 所需的所有数据库表都已创建。
确保django.contrib.sites包反映了应用的域。默认情况下，django.contrib.sites默认为域example.com，您可以在 Django admin 中更改该值，以确保某些特性(如电子邮件)使用正确的应用域。

首先用 Django allauth 中的超级用户登录和注销

首先，使用清单 10-1 中本章开头概述的任何技术创建一个 Django 超级用户，并记下电子邮件。接下来，直接进入/accounts/login/网址，你会看到一个如图 10-11 所示的页面。

图 10-11。

Django allauth defult login screen

现在让我们暂停一下，思考一下 Django·阿劳斯刚刚提供了什么。图 10-11 展示了一个登录页面，与django.contrib.auth登录工作流不同，你甚至不必为其创建模板。此外，请注意图 10-11 中的登录表单要求提供电子邮件凭证，您甚至不需要创建一个自定义认证后端来支持该功能。

接下来，在图 10-11 中的登录表单中输入超级用户的电子邮件/密码，并点击“登录”按钮，如果凭证正确，您将被重定向到“验证您的电子邮件地址”页面。这是有意的，请记住清单 10-17 中的基本 Django allauth 配置强制电子邮件验证(ACCOUNT_EMAIL_VERIFICATION = 'mandatory')；因此，在用户的电子邮件地址被验证之前，访问是被拒绝的。

如果您正在使用清单 10-17 中描述的相同电子邮件设置——向控制台发送电子邮件——您将会看到类似于清单 10-18 中运行 Django 开发服务器的电子邮件。

MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
Subject: [coffeehouse.com] Please Confirm Your E-mail Address
From: webmaster@localhost
To: cashier@coffeehouse.com
Date: Wed, 12 Aug 2018 00:57:50 -0000
Message-ID: <20180812005750.15177.32621@laptop>

Hello from coffeehouse.com!

You're receiving this e-mail because user daniel at example.com has given yours as an e-mail address to connect their account.

To confirm this is correct, go to http://localhost:8000/accounts/confirm-email/1aflixsbb6sn14hptkntiyrgvk1r0pppqsurx6fxrs6wmlb96u8y3gotxzep0qie/

Thank you from coffeehouse.com!
coffeehouse.com

Listing 10-18.Confirm email for new user in django-allauth

将电子邮件中的验证链接复制并粘贴到您的浏览器中。一旦你点击验证链接，你将被要求确认用户的电子邮件。当您点击“确认”按钮进行最终验证时，您将再次被发送到/accounts/login/ url，显示一条简短的消息，表明帐户已被确认。

现在再次在图 10-11 的登录表单中重新输入超级用户邮箱/密码，并点击“登录”按钮。这一次你将被重定向到/accounts/profile/ url 或者在settings.py的LOGIN_REDIRECT_URL变量中定义的 url。

此时，您使用 Django allauth 提供的登录工作流表单作为超级用户登录到应用。接下来，直接进入 Django admin /admin/ url，你可以确认你能够直接访问它！在这种情况下，不需要使用 Django admin 表单重新认证自己，因为您已经使用 Django allauth 工作流登录。

最后，为了退出应用，您可以访问/accounts/logout/ url，在这里您会看到一个确认问题，询问您是否确定要退出，然后单击“退出”按钮实现退出操作。

正如您在本练习中所看到的，Django allauth 提供了与 Django admin 和django.contrib.auth包所使用的标准登录工作流的紧密集成，此外还提供了已经概述的特性:电子邮件验证、内置模板、内置电子邮件身份验证工作流，以及与用户名的向后兼容性。

Django allauth 用户注册

如果你查看图 10-11 中所示的/accounts/login/网址，你可以看到有一个“注册”链接带你到网址/accounts/signup/。点击这个链接，你会看到一个表单，要求输入电子邮件和密码来创建一个用户帐户。

填写完表格后，点击“注册”按钮。如果提交成功，您将被重定向到“验证您的电子邮件地址”页面。这与上一节描述的行为相同，因为 Django allauth 要求在允许访问应用之前进行电子邮件验证。

类似地，继续检查 Django allauth 生成的电子邮件，并复制粘贴验证链接以完成用户注册过程。接下来，您可以继续使用这个用户的凭据登录，默认情况下是一个普通用户。

关于这个注册过程的一个有趣的点可能不是很明显，Django allauth 创建了一个只使用他的电子邮件的用户，这提出了一些问题:如果这个用户后来成为超级用户或职员来访问 Django admin 会发生什么？依赖用户名的 Django admin 登录表单会失效吗？没有这样的事；它将按预期工作。

在幕后，Django allauth 创建了一个常规的 Django 用户，并将其与 Django allauth 功能(例如，电子邮件登录、社交认证)集成在一起。这种内置的集成是一个非常好的特性，因为您可以获得 Django allauth 的所有好处，而且用户可以保留 Django 的默认用户管理，同一个用户可以获得 Django admin 访问、超级用户和员工权限、属于组的能力以及权限分配。

Django allauth 创建用户名的惯例是将电子邮件的本地部分(即@)作为用户名句柄。对于多个同名电子邮件创建一个账户的情况，Django allauth 会为用户名分配一个数字(如nancy@coffeehouse.com=nancy、nancy@hotmail.com=nancy2、nancy@gmail.com=nancy3)。

使用 Django allauth 重置和更改密码

用户需要的最常见的管理任务之一通常与密码有关，无论是因为忘记密码而重置密码，还是出于安全原因而更改密码。Django allauth 为这两种密码场景提供了内置支持。如果你转到/accounts/password/reset/网址，你会看到一个表单，用户可以在其中输入自己的电子邮件来重置密码。

一旦你在最后一个表单上输入了一封电子邮件，点击“重置我的密码”按钮，Django allauth 就会发送一封确认邮件，就像清单 10-19 中的那封一样，带有一个密码重置链接。

MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
Subject: [coffeehouse.com] Password Reset E-mail
From: webmaster@localhost
To: nancy@coffeehouse.com
Date: Wed, 19 Aug 2018 03:05:09 -0000
Message-ID: <20180819030509.15780.98825@laptop>

Hello from coffeehouse.com!

You're receiving this e-mail because you or someone else has requested a password for your user account at coffeehouse.com.
It can be safely ignored if you did not request a password reset. Click the link below to reset your password.

http://localhost:8000/accounts/password/reset/key/5-44f-0f6fbf1251fd33ee4b40/

Thank you for using coffeehouse.com!
coffeehouse.com
-------------------------------------------------------------------------------

Listing 10-19.Reset email for new password django-allauth

接下来，如果您单击电子邮件中的重置链接，您将被带到另一个页面，在那里您可以输入新密码。单击“更改密码”按钮后，如果该过程成功，您将看到一条密码确认提示消息，指示用户密码已更新。

django-allauth 中另一个与密码相关的选项是允许用户在登录时修改密码。如果你转到/accounts/password/change/网址，你会看到一个屏幕，上面有一个介绍新密码的表格。单击“更改密码”按钮后，您将在同一屏幕上看到一条确认消息，表明用户密码已更新。

使用 Django allauth 添加和更改用户电子邮件

为了帮助用户改变他们最初的电子邮件注册地址，Django allauth 有一个专门的页面来管理电子邮件地址。如果你转到/accounts/email/网址，你会看到如图 10-12 所示的页面。

图 10-12。

Django allauth email management

如图 10-12 所示，除了可以向帐户添加其他电子邮件之外，用户还可以更改其主要电子邮件、重新发送电子邮件验证，甚至删除与帐户相关的电子邮件。

更改 Django allauth 的模板

Django allauth 内置模板提供了您在前面章节中看到的基本功能。所有内置模板都从名为base.html的模板中继承它们的行为，它们的内容包含在{% block content %}{% block %}中。这意味着您可以在您的 Django 项目中创建一个名为base.html的模板，其中包含您想要的所有元素(例如，自定义颜色、标题菜单)，并在其中声明{% block content %}{% block %}，Django allauth 内置模板将在此上下文中呈现。

如果您想完全定制 Django allauth 使用的模板(例如，包括移动友好的表单或一些其他的深层变化)，您可以在您的 Django 项目中提供覆盖模板。

Django allauth 依赖超过 15 个 HTML 模板和 6 个电子邮件模板；出于这个原因，如果您将 Django allauth 默认模板复制到您的 Django 项目中，然后根据需要修改它们，会更容易。您应该确保 Django allauth 模板与它们原来的account子文件夹一起被复制，这些子文件夹应该可以在settings.py中的TEMPLATES变量的DIRS值下被访问。根据您的 Python 安装，默认的 Django allauth 模板可以在路径/ lib/python3.5/site-packages/allauth/templates/中找到。

Tip

请参阅该书附带的源代码，其中包括所有 Django allauth 模板的布局。

Django allauth 背后的模型和数据库表

虽然 Django allauth 利用了 Django 的默认用户模型django.contrib.auth.models.User或自定义用户模型(如果它作为AUTH_USER_MODEL配置的一部分提供的话),但是 Django allauth 依靠一系列新模型来支持其高级用户管理特性。图 10-13 展示了 Django admin 展示的 Django allauth 系列模型。

图 10-13。

Django admin with models for django-allauth

图 10-13 所示的第一个 Django allauth 包含对应于“账户”应用，包括“电子邮件地址”模型。“电子邮件地址”模型跟踪电子邮件、它们与用户模型记录的关联(例如django.contrib.auth.models.User)、主要电子邮件状态以及电子邮件的验证状态。应注意,“电子邮件地址”模型记录存储在account_emailaddress数据库表中。

同样值得一提的是，在图 10-13 中，您可以看到django.contrib.auth.models.User包中的标准“用户”和“组”模型。Django allauth 继续利用项目的用户模型来存储核心用户数据(如密码)

图 10-13 中包含的第二组 Django allauth 模型对应于社交账户，用于允许 Django 在社交媒体网站(如脸书、谷歌、Twitter)上进行身份验证，这是本章下一节也是最后一节的主题。

Django allauth 的社会认证

社交认证包括在第三方网站(如脸书、谷歌、Twitter)上创建工作流(也称为应用),让这些网站的用户能够重用他们的身份来访问外部资源，在我们的例子中就是 Django 应用。这种能力在 Django 应用中是一个非常有价值的特性，因为它允许用户点击几次就可以注册，而不是经历一个更复杂的注册过程。

在最基本的层面上，社会认证过程涉及用户授权的令牌，然后在第三方站点和请求方(即您的 Django 应用)之间交换令牌以表明用户的同意。此外，根据应用及其配置，请求方(即 Django 应用)可以从第三方站点请求基本用户信息(例如电子邮件)以及更详细的信息(例如脸书应用中用户的朋友)。

Note

下面几节假设您已经设置了一个基本的 Django allauth 配置，如前一节所述。

为不同的社会服务提供者设置 Django allauth

Django allauth 支持许多社交提供者，每个提供者都通过其自己的包得到支持，这些包需要添加到settings.py中的INSTALLED_APPS列表中，如清单 10-20 所示。

INSTALLED_APPS = [
    # Django sites framework is required
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    'allauth.socialaccount.providers.facebook',
    'allauth.socialaccount.providers.google',
    'allauth.socialaccount.providers.twitter',  
]

SOCIALACCOUNT_PROVIDERS = {'facebook': {}, 'google':{}, 'twitter':{}}

Listing 10-20.Social provider app installation for Django allauth in settings.py

正如你在清单 10-20 中看到的，清单INSTALLED_APPS中的最后三个应用对应于三个社交提供商:脸书、谷歌和推特。将这些提供者添加到INSTALLED_APPS是使他们能够通过 Django allauth 进行社交认证的第一步。

除了google、facebook和twitter应用，Django allauth 还支持来自不同提供商 ³ 的 50 多个其他社交认证工作流，在同一个allauth.socialaccount.providers包下。

在清单 10-20 中，您还可以看到SOCIALACCOUNT_PROVIDERS变量，它有一个对应于每个社交提供者的键字典。每个键都有一个空的字典值，该值最终将包含特定于提供者的配置选项。在接下来的部分中，我将描述如何设置每个社交提供者并填写这些配置值。

Caution

在获得社交提供商的真实连接参数之前，不要将社交提供商配置添加到settings.py。由于登录页面和其他工作流身份验证页面中缺少配置，您会得到错误。

除了SOCIALACCOUNT_PROVIDERS中的配置参数，您还需要通过 Django admin 添加一个社交提供商的应用凭证作为“社交应用”模型记录。进入 Django admin，点击“社交应用”模型，如图 10-13 所示。

接下来，您将看到如图 10-14 所示的屏幕，您可以在此编辑和添加社交应用，并点击右上角的“添加社交应用”按钮。在此页面上，您将看到如图 10-15 所示的屏幕，您可以在此选择社交提供商并引入与社交应用相关的各种值(如姓名、客户 id、密钥)。目前我们还没有这些值，但是让这个 Django 管理页面保持打开，因为接下来我将描述从哪里获得您添加到清单 10-20 中的INSTALLED_APPS变量的三个社交提供者的值。

图 10-15。

Django social application create/edit page

图 10-14。

Django social application list page

和 Django·阿劳斯一起建立脸书

要在 Django allauth 设置脸书社交认证，您需要一个脸书帐户来创建他们网站上的应用。前往developers.facebook.com/apps。如果你之前已经创建了一个脸书应用，你会看到如图 10-16 所示的屏幕，但是如果你从未创建过应用，那么你不会看到应用列表，但是你仍然会看到右上角的“添加新应用”绿色按钮，如图 10-16 所示。

图 10-16。

Facebook application list page

点击图 10-16 右上角的“添加新应用”按钮，您将看到如图 10-17 所示的弹出窗口。填写应用名称(如 Coffeehouse)和联系电子邮件的两个选项，然后点击“创建应用 ID”按钮。

图 10-17。

Facebook create application pop-up

当你点击“创建应用 ID”按钮时，应用创建完毕，你将进入应用的主页。接下来，让我们回到图 10-16 所示的应用列表页面，点击左栏下拉菜单中的“查看所有应用”按钮或再次访问 https://developers.facebook.com/apps 网址，稍后你可以点击应用列表页面上的应用返回应用主页。

在脸书应用列表页面(图 10-16 )上，将鼠标指针悬停在您刚刚创建的应用的右上角，直到出现一个箭头，单击该箭头，并从弹出菜单中单击“创建测试应用”选项，如图 10-18 所示。

图 10-18。

Facebook created test application pop-up menu

接下来，会出现一个弹出窗口，您可以在其中为测试应用指定一个名称或保留默认名称；据此选择。终止后，您将看到如图 10-19 所示的屏幕，显示所有应用配置参数。如果没有看到图 10-19 ，回到图 10-16 的脸书 app 列表页面，再次悬停在右上角，从弹出菜单中选择测试应用。

图 10-19。

Facebook test app main page

在图 10-19 中，您可以看到有一个“应用 ID”值，以及一个隐藏的“应用秘密”值，您可以通过单击“显示”按钮来查看。此外，在左侧，您可以看到一系列选项卡，用于进一步定制应用的参数。点击左侧栏中的“设置”/“基本”菜单。

在“设置”/“基本”菜单上，在页面底部中间你会看到一个大按钮“+添加平台”，如图 10-20 所示。点击“+添加平台”按钮，并在弹出菜单中选择“网站”选项。这将在“+添加平台”按钮上方添加一个“网站”框，在该框的输入字段中添加您的 Django 应用的 url(如http://localhost)以告知脸书接受来自该域的登录请求——如图 10-20 所示——此外，在页面顶部附近的“应用域”输入字段中也添加您的 Django 应用的 URL——如图 10-20 所示。

图 10-20。

Facebook test app configuration for authorized domain requests

接下来，转到 Django admin，在“社交应用”模型创建/编辑页面——如图 10-15 所示——通过从提供商列表中选择“脸书”来创建一个脸书应用，在“名称”框中引入一个友好的名称，在“客户端 Id”框中引入脸书的“应用 ID”值，在“密钥”框中引入脸书的“应用秘密”值。

接下来，打开 Django 项目的settings.py文件，用清单 10-21 中所示的脸书配置参数更新SOCIALACCOUNT_PROVIDERS变量。

SOCIALACCOUNT_PROVIDERS =  { 'facebook':
                               {'METHOD': 'oauth2',
                                'SCOPE': ['email'],
                                'AUTH_PARAMS': {'auth_type': 'reauthenticate'},
                                'LOCALE_FUNC': lambda request: 'en_US',
                                'VERSION': 'v2.4'
                               }
                           }
Listing 10-21.Facebook social provider configuration for Django allauth in settings.py

清单 10-21 中的设置是运行脸书认证的最基本的一组值，但是您可以在 Django allauth 文档中查阅许多其他选项。接下来，启动 Django 应用并访问/accounts/login/页面尝试登录，您将看到如图 10-21 所示的页面。

图 10-21。

Django login with social authentication options

正如你在图 10-21 中看到的，与基于 Django allauth 的配置中的登录页面不同，现在有了向脸书、谷歌和 Twitter 注册的选项。点击脸书链接，你将被重定向到脸书页面进行授权，如图 10-22 所示。

图 10-22。

Facebook social authorization pop-up

如图 10-22 所示，用户被告知该操作将在确认后共享其公共档案和电子邮件。如果用户单击“继续为...”按钮脸书用一个令牌和用户的信息(即，公共配置文件信息和电子邮件)联系 Django 应用。此时，Django allauth 创建一个用户，并让他通过常规的 Django allauth 用户创建工作流。

由于之前的 Django allauth 基本配置(此社交配置基于该配置)强制进行电子邮件验证，因此无论脸书认证工作流如何，用户在通过 Django allauth 验证其电子邮件帐户之前，将无法登录应用。一旦用户通过 Django allauth 发送的验证链接确认其电子邮件，用户将被标记为已验证，并可以继续登录应用-请注意，此电子邮件验证过程不是特定的，也不是社交认证所必需的，您可以禁用它。如果您希望在脸书返回响应后立即允许自动登录。

脸书认证和电子邮件验证完成后，用户可以随时点击“脸书”登录链接登录 Django 应用。

在幕后，Django allauth 在“社交应用令牌”和“社交帐户”模型中跟踪社交认证令牌和帐户，这两个模型都可以在 Django admin 中访问。

此外，Django allauth 还通过脸书工作流创建了一个普通的 Django 用户(例如,django.contrib.auth.models.User类),因此同一个用户能够利用 Django 的标准认证系统(例如成为超级用户或职员)。但是请注意，这种类型的用户依赖于脸书授权令牌——并且没有密码——因此认证必须始终通过/accounts/login/中的社交脸书认证链接来完成，Django admin 不为这种类型的用户工作，因为它需要输入密码。

请记住，除了多个特定于脸书的配置 Django allauth 选项超出了本讨论的范围之外，还有其他社交认证概念(例如，令牌撤销、回叫 URL)需要您自己探索和配置——假设它们不是特定于 Django 的——以便为最终用户提供简化的社交认证流程。

Note

前面的程序是作为脸书‘测试应用’完成的——参见图 10-18 。对于 Django 应用的实时版本，您必须在同一个脸书应用的主(即非测试)通道上执行相同的过程。

与 Django·阿劳斯一起建立谷歌

要在 Django allauth 设置 Google social authentication，你需要一个 Google 帐户在他们的网站上创建一个应用。头转向 https://console.developers.google.com/ 。如果你以前创建了谷歌项目，你将登陆一个默认项目。虽然您可以在任何 Google 项目上创建社交认证工作流，但我建议您为此创建一个新项目。

在顶部菜单栏上——在“Google APIs”徽标的右侧——有一个带有默认项目名称的菜单:单击它，会出现一个弹出窗口，其中包含项目列表。在最后一个弹出窗口中，搜索框旁边是一个名为“创建项目”的“+”(加号)按钮。点击“创建项目”按钮，您将被带到图 10-23 所示的页面。介绍一个项目名称，然后单击“创建”按钮。

图 10-23。

Google create project page

点击“创建按钮”后，您将进入项目主页，如图 10-24 所示。确保您处于刚刚创建的项目中，验证顶部菜单栏中选定项目的名称——位于“Google APIs”徽标的右侧。如果不是正确的项目，单击 project 并从弹出的项目列表中选择合适的项目。

图 10-24。

Google project main page

在图 10-24 的左侧菜单中，点击“凭证”选项。接下来，在页面中央，点击“添加凭证”按钮，并从下拉菜单中选择“OAuth 客户端 ID”选项，如图 10-25 所示。

图 10-25。

Google project Oauth client ID option

点击“OAuth 客户端 ID”选项后，您将进入“创建客户端 ID”页面，如图 10-26 所示。您应该选择“Web 应用”选项；但是，请注意页面顶部的警告，指示“要创建 OAuth 客户端 ID，您必须首先在同意屏幕上设置产品名称”。让我们先来看看这个同意屏幕，点击图 10-26 中的“配置同意屏幕”按钮，进入图 10-27 中的页面。

图 10-27。

Google project OAuth consent screen

图 10-26。

Google project create client ID page

图 10-27 中的同意屏幕用于定制当最终用户从一个应用(在我们的例子中是 Django 应用)寻求授权时，Google 如何接待最终用户。填写必填的“向用户显示的产品名称”字段，并保存更改。一旦保存同意屏幕，您将被带回到图 10-26 中的屏幕，在那里您可以选择“网络应用”选项。

在“Web 应用”页面中，“名称”字段被赋予默认的“Web 客户端 1”值，您可以相应地进行调整。将“授权 JavaScript origins”选项设置为 Django 应用的域(如http://localhost)，并将“授权重定向 URIs”选项设置为 Django allauth url /accounts/google/login/callback/，这是 Google 在成功认证后联系应用的地方——注意，最后一个值必须使用完全限定的域(如http://localhost/accounts/google/login/callback/)。

在“Web 应用”页面中输入必要的值后，单击“创建”按钮，您将看到如图 10-28 所示的弹出窗口，其中显示了应用客户端 ID 和客户端密码——如果您关闭该弹出窗口，稍后您可以在左侧的主“凭证”菜单中访问相同的值。

图 10-28。

Google project Client ID and Client Secret

接下来，转到 Django admin，在“社交应用”模型创建/编辑页面(如图 10-15 所示)中，通过从提供商列表中选择“Google”来创建一个 Google 应用，在“name”框中引入一个友好名称，在“Client ID”框中引入 Google“Client ID”值，并在“Secret key”框中引入 Google“Client Secret”值

接下来，打开 Django 项目的settings.py文件，用清单 10-22 中所示的 Google 配置参数更新SOCIALACCOUNT_PROVIDERS变量。

SOCIALACCOUNT_PROVIDERS = { 'google':
                             { 'SCOPE': ['email'],
                               'AUTH_PARAMS': { 'access_type': 'online' }
                             }
                          }
Listing 10-22.Google social provider configuration for django-allauth in settings.py

清单 10-22 中的设置是运行 Google 认证最基本的一组值，但是你可以在 Django allauth 文档中查阅许多其他选项。接下来，启动 Django 应用并访问图 10-21 中的/accounts/login/页面，尝试登录 Google。点击“谷歌”注册链接，你将被重定向到谷歌授权页面，如图 10-29 所示。

图 10-29。

Google social authorization page

如图 10-29 所示，用户被告知他将在确认后分享他是谁以及他的电子邮件。如果用户点击“Accept ”, Google 会用一个令牌和用户信息(即公开的个人资料信息和电子邮件)联系 Django 应用。此时，Django allauth 创建了一个用户，这样他每次只需点击“Google”登录链接就可以登录 Django 应用。

因为谷歌本身需要有效的电子邮件才能工作，这意味着通过谷歌认证的用户使用的是有效的电子邮件，因此 Django allauth 跳过了电子邮件验证过程，并自动将用户标记为已验证——不像脸书认证，用户可以继续使用脸书的陈旧和潜在无效的电子邮件。

在幕后，Django allauth 在“社交应用令牌”和“社交帐户”模型中跟踪社交认证令牌和帐户，这两个模型都可以在 Django admin 中访问。

此外，Django allauth 还通过 Google workflow 创建了一个普通的 Django 用户(例如,django.contrib.auth.models.User类),因此同一个用户能够利用 Django 的标准认证系统(例如成为超级用户或职员)。然而，请注意，这种类型的用户依赖于 Google 授权令牌——并且没有密码——因此认证必须始终通过/accounts/login/中的社交 Google 认证链接来完成，Django admin 不为这种类型的用户工作，因为它需要输入密码。

与 Django allauth 一起创建 Twitter

要在 Django allauth 中设置 Twitter 社交认证，您需要一个 Twitter 帐户来在他们的网站上创建一个应用。前往 https://apps.twitter.com/app/new ，你会看到一个如图 10-30 所示的屏幕，创建一个 Twitter 应用。

图 10-30。

Twitter create app page

填写新 Twitter 应用所需的详细信息，确保“回调 URL”字段设置为http://localhost:8000/accounts/twitter/login/callback/，这是 Twitter 在成功认证后联系 Django 应用的地方。创建应用，您将被重定向到 Twitter 应用的主页。接下来，单击“密钥和访问令牌”选项卡，您将看到如图 10-31 所示的屏幕。

图 10-31。

Twitter app Key and Access Tokens page

接下来，转到 Django admin，在“社交应用”模型创建/编辑页面——如图 10-15 所示——从提供者列表中选择“Twitter ”,创建一个 Twitter 应用，在“name”框中引入一个友好名称，在“Client Id”框中引入 Twitter“Consumer Key(API Key)”值，在“Secret key”框中引入 Twitter“Consumer Secret”值。

Django allauth 不支持任何 Twitter 配置选项作为 settings.py 中的SOCIALACCOUNT_PROVIDERS变量的一部分，所以您可以跳过这个配置步骤。

接下来，启动您的 Django 应用并访问图 10-21 中的/accounts/login/页面，尝试 Twitter 登录。点击“Twitter”登录链接，您将被重定向到 Twitter 授权页面，如图 10-32 所示。

图 10-32。

Twitter social authorization page

正如你在图 10-32 中看到的，用户被告知他将在确认后分享推文和其他信息。如果用户点击“授权应用”，Twitter 会用一个令牌和用户的信息(即公开的个人资料信息)联系 Django 应用。此时，用户被重定向回网站，Django allauth 向用户索要电子邮件以完成帐户创建过程，如图 10-33 所示。

图 10-33。

Django allauth email request after Twitter social authorization

请注意，图 10-33 中的最后一个电子邮件请求是必要的，因为 Twitter 不提供带有社交认证的电子邮件——尽管很难相信，但这是已知的 Twitter 社交认证限制。

因为基本 Django allauth 配置强制执行电子邮件验证，以避免垃圾邮件，所以用户会收到一封验证电子邮件，在邮件中他必须单击一个链接才能完成激活。

一旦用户通过点击验证电子邮件链接确认了他的电子邮件，他就可以在任何时候通过点击“Twitter”登录链接来登录 Django 应用。在幕后，Django allauth 在“社交应用令牌”和“社交帐户”模型中跟踪社交认证令牌和帐户，这两个模型都可以在 Django admin 中访问。

此外，Django allauth 还使用 Twitter 工作流创建了一个普通用户(例如,django.contrib.auth.models.User类),因此该用户能够利用 Django 的标准认证系统(例如成为超级用户或职员)。但是请注意，这种类型的用户依赖 Twitter 授权令牌——并且没有密码——因此认证必须始终通过/accounts/login/中的社交 Twitter 认证链接来完成，Django admin 不为这种类型的用户工作，因为它需要输入密码。

Footnotes 1

https://docs.djangoproject.com/en/1.11/topics/auth/passwords/#included-validators

https://docs.djangoproject.com/en/1.11/ref/contrib/auth/#module-django.contrib.auth.backends

http://django-allauth.readthedocs.io/en/latest/providers.html

十一、Django Admin

Django admin 是一个用户友好的应用，用于管理链接到 Django 项目的关系数据库的内容。尽管 Django admin 在设置方面几乎毫不费力——如第一章所述——但在这一章中你将学到多种配置选项来创建更强大的 Django admin 显示和功能。

在本章中，您将首先学习如何在 Django 管理中注册 Django 模型。接下来，您将学习如何在 Django admin 中显示记录，并使用排序、行内编辑、分页、搜索和操作按钮等技术。此外，您将学习如何定制 Django 管理表单和关系，以便使用 Django 管理轻松地创建、更新和删除模型记录。

接下来，您将学习如何通过配置字段和定制模板定制 Django 管理页面，以及如何添加定制数据和覆盖 Django 管理类方法和字段来创建最灵活的 Django 管理页面。最后，您将学习如何配置和实施 Django 管理权限，以及如何创建多个 Django 管理站点实例。

在 Django 管理中设置 Django 模型

尽管 Django admin 为 Django 项目的数据库提供了一个优秀的管理工具，但是仅仅创建和安装 Django 模型还不足以在 Django admin 中访问它们的数据。

为了访问 Django 管理中的 Django 模型记录，您必须在admin.py文件中注册和配置 Django 模型。当你创建一个应用时，一个admin.py文件会自动放在 Django 应用中，与models.py和views.py文件放在一起。

虽然从技术上讲，你可以使用一个admin.py来注册和配置所有的 Django 模型——就像你可以使用一个models.py来定义所有的 Django 模型——但是推荐的做法是每个 Django 应用使用自己的admin.py文件来管理在models.py中定义的相应模型。

在 admin.py 文件中为 Django admin 注册 Django 模型有三种方法，所有这些都在清单 11-1 中进行了说明。

from django.contrib import admin
from coffeehouse.stores.models import Store

# Option 1 - Basic
admin.site.register(Store)

# Option 2 - Allows customizing Django admin behavior
class StoreAdmin(admin.ModelAdmin):
      pass

admin.site.register(Store, StoreAdmin)

# Option 3 – Decorator
@admin.register(Store)
class StoreAdmin(admin.ModelAdmin):
      pass

Listing 11-1.Register Django models in admin.py file

清单 11-1 中的第一个选项提供了基本的 Django 模型注册，包括声明一个 Django 模型类作为admin.site.register方法的输入。如果您不需要为模型定制默认的 Django 管理行为，这个选项就足够了。

清单 11-1 中的第二个选项利用了一个 Django 管理类，该类从admin.ModelAdmin类继承了它的行为。在这种情况下，你可以看到类是空的，但是可以定制 Django 管理行为，我将在本章中描述。一旦 Django admin 类被声明，它必须使用选项一中的相同的admin.site.register方法注册并与 Django 模型关联，其中第一个参数是 Django 模型，第二个参数是 Django admin 类。

清单 11-1 中的第三个选项利用了 Django admin @admin.register装饰器。选项三和选项二之间的语法差异在于，注册和关联发生在用@admin.register修饰 Django admin 类时，其中修饰者将 Django 模型作为其参数。

值得一提的是，虽然选项二和选项三在功能上是相同的，但是使用@admin.register装饰器——选项三——有一个限制，即您不能在它的__init__()方法中引用 Django admin 类(例如，super(StoreAdmin, self).__init__(*args, **kwargs)),这在 Python 2 和某些设计中是一个问题；如果您处于这种情况，那么您必须使用选项二用admin.site.register方法注册一个模型。

现在您已经知道如何在 Django 管理中注册 Django 模型，我将描述通过 Django 管理类定制 Django 管理行为的各种选项。为了更容易地查找定制选项，我将选项分为两个主要部分:“读取记录选项”和“创建、更新、删除记录选项”，以涵盖 Django admin 中可用的 CRUD 操作选项的整个范围，此外还包括在每个主要部分下分组功能的子部分。

Django 管理读取记录选项

当你在 Django admin 的主页上点击一个 Django 模型时，你会被带到一个页面，显示这个特定模型的记录列表。图 11-1 和 11-2 展示了Store型号的记录列表页面。

图 11-2。

Django admin record list page with model str definition

图 11-1。

Django admin record list page with no model str definition

如图 11-1 和 11-2 所示，每个 Django 模型记录都用一个字符串显示。默认情况下，这个字符串由 Django 模型的__str__()方法定义生成，如第七章所述。如果 Django 模型中缺少__str__方法，那么 Django 管理员会将类似图 11-1 的记录显示为‘Store object’；否则，它将返回由__str__方法为每条记录生成的结果——在图 11-2 中，这是每条Store记录的名称、城市和州属性。

记录显示:列表显示，格式 html，空值显示

虽然图 11-1 和 11-2 中呈现的基本显示行为是有帮助的，但是对于具有不表达的或复杂的__str__()方法的模型来说可能是非常有限的。Django admin 类可以用list_display选项进行配置，将记录列表与模型的各种字段分开，从而更容易查看和排序记录。清单 11-2 展示了一个带有 list_display 选项的 Django 管理类。

from django.contrib import admin
from coffeehouse.stores.models import Store

class StoreAdmin(admin.ModelAdmin):
      list_display = ['name','address','city','state']

admin.site.register(Store, StoreAdmin)

Listing 11-2.Django admin list_display option

正如您在清单 11-2 中看到的，Django admin StoreAdmin类用一个值列表定义了list_display选项。该列表对应于 Django 模型字段，在本例中，这些字段来自Store模型。图 11-3 和 11-4 显示了通过添加list_display选项修改后的记录列表布局。

图 11-4。

Django admin record list page with model list_display sorted

图 11-3。

Django admin record list page with list_display Tip

如果你想在 Django 管理中继续显示 Django 模型通过其__str__方法生成的值，可以将其添加到list_display选项中(例如list_display = ['name','__str__'])。

在图 11-3 中，你可以看到一个更加清晰的记录列表布局，其中 list_display 中声明的每个字段都有自己的列。此外，如果你点击任何代表模型字段的列标题，记录会自动按照该属性排序，这个过程如图 11-4 所示，它极大地提高了记录的可发现性。

除了支持包含 Django 模型字段之外，list_display选项还支持其他变体来生成更复杂的列表布局。例如，如果数据库记录是不同的(例如，混合的大写和小写文本)，您可以生成一个可调用的方法来操作记录，并以统一的方式(例如，全部大写)在 Django admin 中显示它们。此外，您还可以创建一个 callable，从数据库中没有明确显示的记录字段(例如，属于电子邮件记录的域名)生成一个复合值，这使得 Django admin 中记录列表的可视化更加强大。清单 11-3 使用几种方法变体展示了这些可调用的例子。

from django.contrib import admin
from coffeehouse.stores.models import Store

# Option 1
# admin.py
def upper_case_city_state(obj):
    return ("%s %s" % (obj.city, obj.state)).upper()
upper_case_city_state.short_description = 'City/State'

class StoreAdmin(admin.ModelAdmin):
      list_display = ['name','address',upper_case_city_state]

# Option 2
# admin.py
class StoreAdmin(admin.ModelAdmin):
    list_display = ['name','address','upper_case_city_state']
    def upper_case_city_state(self, obj):
        return ("%s %s" % (obj.city, obj.state)).upper()
    upper_case_city_state.short_description = 'City/State'

# Option 3
# models.py
from django.db import models

class Store(models.Model):
    name = models.CharField(max_length=30)
    email = models.EmailField()
    def email_domain(self):
        return self.email.split("@")[-1]
    email_domain.short_description = 'Email domain'

# admin.py
class StoreAdmin(admin.ModelAdmin):
      list_display = ['name','email_domain']

Listing 11-3.Django admin list_display option with callables

在清单 11-3 中，你可以看到三个可赎回的变体，它们都可以作为list_display期权。清单 11-3 中的选项一是一个在类外声明的可调用函数，然后被用作list_display选项的一部分。选项二将 callable 声明为 Django admin 类的一部分，然后将其用作list_display选项的一部分。最后，选项三将 callable 声明为 Django 模型类的一部分，然后将其用作 Django 管理类中list_display选项的一部分。清单 11-3 中的两种方法都不是“优于”或“劣于”另一种；这些选项只是在用于实现相同结果的语法和参数上有所不同，您可以使用您喜欢的任何方法。

在某些情况下，你可能想在 Django admin 中将 HTML 作为记录列表的一部分(例如，添加粗体标签或彩色标签)。要在这些情况下包含 HTML，您必须使用format_html方法，因为 Django admin 默认情况下会对所有 HTML 输出进行转义——因为它使用 Django 模板。清单 11-4 展示了format_html方法的使用。

# models.py
from django.db import models
from django.utils.html import format_html

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30,unique=True)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    def full_address(self):
        return format_html('%s - <b>%s,%s</b>' % (self.address,self.city,self.state))

# admin.py
from django.contrib import admin
from coffeehouse.stores.models import Store

class StoreAdmin(admin.ModelAdmin):
      list_display = ['name','full_address']

Listing 11-4.Django admin list_display option with callable and format_html

当模型字段使用BooleanField或NullBooleanField数据类型时，Django admin 显示“开”或“关”图标，而不是True或False值。此外，当list_display中某个字段的值为None时，为空字符串，对于list_display中某个字段为空可迭代的情况(如 list)，Django 显示破折号-，如图 11-5 所示。

图 11-5。

Django admin default display for empty values

可以用图 11-6 所示的empty_value_display选项覆盖最后一个行为。您可以配置empty_value_display选项，使其在所有 Django 管理模型、特定的 Django 管理类或单个 Django 管理字段上生效，如清单 11-5 所示。

图 11-6。

Django admin override display for empty values with empty_value_display

# Option 1 - Globally set empty values to ???
# settings.py
from django.contrib import admin
admin.site.empty_value_display = '???'

# Option 2 - Set all fields in a class to 'Unknown Item field'
# admin.py to show "Unknown Item field" instead of '-' for NULL values in all Item fields
# NOTE: Item model in items app

class ItemAdmin(admin.ModelAdmin):
    list_display = ['menu','name','price']
    empty_value_display = 'Unknown Item field'

admin.site.register(Item, ItemAdmin)

# Option 3 - Set individual field in a class to 'No known price'
class ItemAdmin(admin.ModelAdmin):
    list_display = ['menu','name','price_view']
    def price_view(self, obj):
         return obj.price
    price_view.empty_value_display = 'No known price'

Listing 11-5.Django admin empty_value_display option global, class, or field-level configuration

记录顺序:admin_order_field 和排序

当您在list_display中使用定制字段(即，实际上不在数据库中的字段，而是在 Django 中计算的复合字段或帮助字段)时，这样的字段不能用于排序操作，因为排序发生在数据库级别。然而，如果list_display中的一个元素与一个数据库字段相关联，那么可以用admin_order_field选项创建一个关联用于排序目的。清单 11-6 说明了这一过程。

# models.py
from django.db import models
from django.utils.html import format_html

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30,unique=True)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    def full_address(self):
        return format_html('%s - <b>%s,%s</b>' % (self.address,self.city,self.state))
    full_address.admin_order_field = 'city'

# admin.py
from django.contrib import admin
from coffeehouse.stores.models import Store

class StoreAdmin(admin.ModelAdmin):
      list_display = ['name','full_address']

Listing 11-6.Django admin with admin_order_field option

正如您在清单 11-6 中看到的，当试图通过复合full_address字段在 Django admin 中执行排序操作时，admin_order_field声明告诉 Django 按照city对模型记录进行排序。注意，也可以给admin_order_field值添加一个前缀来指定降序(例如full_address.admin_order_field = '-city')，就像在标准模型排序操作中一样。

默认情况下，记录列表值按其数据库pk(主键)字段(通常是 id 字段)排序，如图 11-3 所示(即记录pk 1在底部，记录pk 4在顶部)。如果您单击任何标题列，排序顺序就会改变，如图 11-4 所示。

要设置默认的排序行为——不需要点击标题列——您可以使用 Django admin class ordering选项或 Django model meta ordering选项，您将在第七章中了解到。如果在任一类中没有指定排序选项，则进行pk排序。如果在 Django 模型元选项中指定了ordering选项，那么这种排序行为是通用的，如果 Django 模型和 Django 管理类都有ordering选项，那么 Django 管理类定义优先。

ordering选项接受一个字段值列表来指定记录列表的默认顺序。默认情况下，ordering行为是升序(例如，Z 值第一个@bottom，A 值 top@last)，但是可以通过在字段值前添加一个-(减号)将此行为改为降序(例如，A 值第一个@bottom，Z 值 top@last)。例如，默认情况下，要生成如图 11-4 所示的记录列表，您可以使用ordering = ['name']，而要生成如图 11-4 所示的反向记录列表(即住宅区在顶部，公司在底部)，您可以使用ordering = ['-name']。

记录链接和内联编辑:list_display_links 和 list_editable

如果您查看一些过去的数字，您会注意到记录列表中的每一项都有一个生成的链接。例如，在图 11-2 中，您可以看到每条'商店'记录都是一个链接，将您带到一个可以编辑'商店'值的页面，同样，在图 11-4 中，您可以看到'商店'名称字段是一个链接，将您带到一个可以编辑'商店'值的页面，在图 11-6 中，您可以看到每条'

这是一个默认行为，允许您在每个记录上向下钻取，但是您可以通过list_display_links选项定制这个行为，以不生成链接或者包含更多的链接。清单 11-7 说明了list_display_links选项的两种变型，并显示了 11-7 和 11-8 各自的接口。

图 11-8。

Django admin multiple links in records list due to list_display_links

图 11-7。

Django admin no links in records list due to list_display_links

# Sample 1)
# admin.py
from django.contrib import admin
from coffeehouse.stores.models import Store

class StoreAdmin(admin.ModelAdmin):
      list_display = ['name','address','city','state']
      list_display_links = None

admin.site.register(Store, StoreAdmin)

# Sample 2)
# admin.py
from django.contrib import admin
from coffeehouse.items.models import Item

class ItemAdmin(admin.ModelAdmin):
    list_display = ['menu','name','price_view']
    list_display_links = ['menu','name']

admin.site.register(Item, ItemAdmin)

Listing 11-7.Django admin with list_display_links option

清单 11-7 中的第一个示例演示了如何用list_display_links = None设置StoreAdmin类，从而得到图 11-7 中所示的缺少链接的页面。清单 11-7 中的第二个示例显示了带有list_display_links = ['menu','name']的ItemAdmin类，该类告诉 Django 在menu和name字段值上生成链接，并产生图 11-8 中所示的包含多个链接的页面。

如果您需要编辑多个记录，那么单击记录列表上的单个链接来编辑记录的需要会变得令人厌烦。为了简化记录的编辑，list_editable选项允许 Django 在每个记录值上生成内联表单，有效地允许批量编辑记录，而无需离开记录列表屏幕。清单 11-8 说明了 list_editable 选项的使用和图 11-9 各自的界面。

Note

从技术上讲，list_editable 是 Django admin 的更新选项，但是由于更新是在设计用来读取记录的页面上内联完成的，所以包含在这里。

图 11-9。

Django admin editable fields due to list_editable

# admin.py
from django.contrib import admin
from coffeehouse.stores.models import Store

class StoreAdmin(admin.ModelAdmin):
      list_display = ['name','address','city','state']
      list_editable = ['address','city','state']

admin.site.register(Store, StoreAdmin)

Listing 11-8.Django admin with list_editable option

在清单 11-8 中，您可以看到list_editable = ['address','city','state']选项，它告诉 Django 管理员允许编辑记录列表中的address、city.和state值。在图 11-9 中，你可以看到记录列表中的每一个字段值是如何被转换成可编辑的形式，并且在页面的底部，Django 管理员生成一个'保存'按钮来保存编辑时所做的更改。

值得一提的是，list_editable选项中声明的任何字段值也必须声明为list_display选项的一部分，因为不可能编辑未显示的字段。此外，list_editable选项中声明的任何字段值都不能是list_display_option的一部分，因为字段不可能既是表单又是链接。

记录分页:list_per_page，list_max_show_all，分页器

当 Django admin 中的记录列表变得太大时，它们会被自动分割成不同的页面。默认情况下，Django admin 会为每 100 条记录生成额外的页面。您可以使用 Django 管理类list_per_page选项来控制这个设置。清单 11-9 说明了 list_per_page 选项的使用，图 11-10 显示了由清单 11-9 中的配置生成的相应记录列表。

图 11-10。

Django admin list_per_page option limit to 5

# admin.py
from django.contrib import admin
from coffeehouse.items.models import Item

class ItemAdmin(admin.ModelAdmin):
    list_display = ['menu','name','price']
    list_per_page = 5

admin.site.register(Item, ItemAdmin)

Listing 11-9.Django admin with list_per_page option

正如您在图 11-10 中看到的，由于清单 11-9 中所示的list_per_page = 5选项，九条记录的显示被分成两页。除了图 11-10 左下方的页面图标，请注意这些图标的右侧是一个“显示全部”链接。“显示全部”链接用于生成一个记录列表，在一个页面上显示所有记录。但是请注意，因为这个额外的数据库操作成本很高，所以默认情况下，只有当记录列表不超过 200 项时，才会显示“显示全部”链接。

您可以使用list_max_show_all选项控制“显示全部”链接的显示。如果记录列表总数小于或等于list_max_show_all值，则显示“显示全部”链接，如果记录列表总数大于此数，则不生成“显示全部”链接。例如，如果您对列表 11-9 声明list_max_show_all = 8选项，那么在图 11-10 中不会出现“显示全部”链接，因为记录列表总数是 9。

Django admin 使用django.core.paginator.Paginator类来生成分页序列，但是也可以通过 paginator 选项提供一个定制的分页器类。注意，如果自定义分页器类没有从django.core.paginator.Paginator继承它的行为，那么你也必须为ModelAdmin.get_paginator()方法提供一个实现。

记录搜索:搜索字段、列表过滤器、显示完整结果计数、保留过滤器

Django admin 也支持搜索功能。Django 管理类search_fields选项通过搜索框增加了文本模型字段的搜索功能——关于 Django 模型文本数据类型的列表，参见表 7-1 。清单 11-10 展示了一个带有 search_fields 选项的 Django 管理类，图 11-11 展示了一个搜索框是如何被添加到记录列表的顶部的。

图 11-11。

Django admin search box due to search_fields option

from django.contrib import admin
from coffeehouse.stores.models import Store

class StoreAdmin(admin.ModelAdmin):
      search_fields = ['city','state']

admin.site.register(Store, StoreAdmin)

Listing 11-10.Django admin search_fields option

在清单 11-10 中，城市和州字段被添加到search_fields选项中，它告诉 Django 管理员在这两个字段中执行搜索。请注意，由于 Django 执行这种类型的搜索查询的方式，向search_fields选项添加太多字段会导致搜索结果变慢。表 11-1 显示了不同的search_fields选项和为给定搜索项生成的 SQL。

表 11-1。

Django search_fields options and generated SQL for search term

| 搜索字段选项 | 搜索术语 | 生成的 SQL 条件 | | --- | --- | --- | | search_fields = ['city '，' state'] | 圣迭戈 | 其中(城市我喜欢“%San%”或州我喜欢“%San%”)和(城市我喜欢“%Diego%”或州我喜欢“%Diego%”) | | search _ fields =['^city','^state'] | 圣迭戈 | 其中(城市 ILIKE 'San% '或州 ILIKE 'San% ')和(城市 ILIKE 'Diego% '或州 ILIKE 'Diego% ') | | search _ fields =[' =城市'，' =州'] | 圣迭戈 | 其中(市 ILIKE 'San '或州 ILIKE 'San ')和(市 ILIKE 'Diego '或州 ILIKE 'Diego ') | | *search_fields = ['@city '，' @state'] | 圣迭戈 | (全文搜索)其中(城市 I like“% San %”或州 I like“% San %”)和(城市 I like“% Diego %”或州 I like“% Diego %”) |

Full-text search option only supported for MySQL database

如表 11-1 所示，search_fields选项通过将提供的搜索字符串拆分成单词来构建查询，并执行不区分大小写的搜索(即SQL ILIKE)，其中每个单词必须至少出现在一个 search _ fields 中。此外，注意在表 11-1 中，可以用不同的前缀声明search_fields值来改变搜索查询。

默认情况下，如果您只是向search_fields,提供模型字段名，Django 会生成一个查询，在每个单词的开头和结尾使用 SQL 通配符%，这可能是一个代价非常高的操作，因为它会搜索字段记录中的所有文本。如果您在search_field前面加上一个^——如表 11-1 所示——Django 会生成一个查询，在每个单词的末尾有一个 SQL 通配符%，这使得搜索操作更加有效，因为它仅限于以单词模式开头的文本。如果您给 search_field 加上前缀=——如表 11-1 所示——Django 会生成一个没有 SQL 通配符%的精确匹配查询，这使得搜索操作最有效，因为它仅限于单词模式的精确匹配。最后，如果您使用的是 MySQL 数据库，也可以给search_fields添加前缀@来实现全文搜索。

Power Searches, Non-Text Searches, and Other Back Ends For Django Admin Searches

搜索引擎提供了各种强大的搜索语法来定制搜索查询，但是 Django admin search_fields选项不支持这种语法。例如，在搜索引擎中，可以引用搜索词"San Diego"来对两个单词进行精确搜索，但是如果你尝试用 Django admin 搜索，Django 会尝试分别搜索文字引号:"San"和"Diego"。要调整默认的 search_fields 行为，您必须使用表 11-1 或ModelAdmin.get_search_results()中的选项。

Django admin 类的默认搜索行为可以通过接受请求的ModelAdmin.get_search_results()方法、应用当前过滤器的 queryset 和用户提供的搜索词定制为任何需求。通过这种方式，您可以生成非文本搜索(例如，在整数上)或依靠其他第三方工具(例如，Solr、Haystack)来生成搜索结果。

list_filter选项提供了对模型字段值的快速访问，并且像预建的搜索链接一样工作。与search_fields选项不同，list_filter选项在它可以处理的数据类型方面更加灵活，并且不仅仅接受文本模型字段(例如，它还支持布尔字段、日期字段等)。).清单 11-11 展示了一个带有list_filter选项的 Django 管理类，图 11-12 展示了在记录列表右侧生成的过滤器列表。

图 11-12。

Django admin list filters due to search_fields option

from django.contrib import admin
from coffeehouse.items.models import Item

class ItemAdmin(admin.ModelAdmin):
    list_display = ['menu','name','price']
    list_filter = ['menu','price']

admin.site.register(Item, ItemAdmin)

Listing 11-11.Django admin list_filter option

在清单 11-11 中，list_filter 选项是用菜单和价格字段声明的，它告诉 Django 用这两个字段创建过滤器。正如您在图 11-12 中所看到的，记录列表的右侧是一个带有各种过滤器的列，其中包含了menu和price字段值的所有值。如果您点击任何过滤器链接，Django admin 会在记录列表中显示与过滤器匹配的记录，这个过程如图 11-13 、 11-14 和 11-15 所示。

图 11-15。

Django admin list with dual filter

图 11-14。

Django admin list with single filter

图 11-13。

Django admin list with single filter

在图 11-15 中可以看到的 Django 管理过滤器的一个有趣的方面是，您可以应用多个过滤器，这使得更容易深入到匹配非常具体的标准的记录。

此外，如果您查看图 11-13、11-14 和 11-15，您可以看到过滤器是如何反映为 URL 查询字符串的。例如，在图 11-13 中，?menu__id__exact=2字符串被附加到 URL 上，它告诉 Django admin 显示一个记录列表，带有一个2的菜单id；在图 11-15 中，?menu__id__exact=3&price=3.99字符串告诉 Django admin 显示一个菜单 id 为3和价格值为3.99的记录列表。该 URL 参数语法基于用于进行标准 Django 模型查询的相同语法——在第八章中描述——这有助于“动态”生成更复杂的过滤器，而无需修改或添加底层 Django 管理类的选项。

当您对记录列表应用一个或多个过滤器，并且过滤后的结果多于 99 条记录时，Django 会将初始显示限制为 99 条记录，并且还会添加分页，但此外还会显示与过滤器匹配的对象的完整计数(例如，99 条结果(总共 153 条))。这个额外的计数需要一个额外的查询，这对于大量的记录来说会减慢速度。要禁止生成适用于过滤器使用的额外计数，您可以将show_full_result_count选项设置为False。

应用一个或多个过滤器的另一个特点是，当您创建、编辑或删除一个记录并完成操作时，Django 会将您带回过滤列表。虽然这可能是一个期望的行为，但是可以通过preserve_filters选项覆盖这个行为，这样 Django 管理员就可以将您返回到原始记录列表。如果您在 Django admin 类中设置了preserve_filters = False选项，并创建、编辑或删除了一个记录，Django admin 会将您带回到没有过滤器的原始记录列表。

记录日期:日期层次结构

日期和时间在 Django admin UI 中显示为底层 Python datetime值的字符串表示，正如您所期望的那样。但是有一个针对DateField和DateTimeField模型数据类型的特殊选项，它像一个专门的过滤器一样工作。如果您在 Django 管理类上使用date_hierarchy选项，并为其分配一个为DateField或DateTimeField的字段(例如date_hierarchy = 'created'，其中timestamp是字段的名称)，Django 会在记录列表的顶部生成一个智能日期过滤器，如图 11-16 、 11-17 和 11-18 所示。

图 11-18。

Django date filter single day with date_hierarchy

图 11-17。

Django date filter by day with date_hierarchy

图 11-16。

Django date filter by month with date_hierarchy

正如您在图 11-16 、 11-17 和 11-18 中看到的，智能行为来自于这样一个事实，即在加载记录列表时，Django 会生成一个与date_hierarchy字段的值相对应的可用月份或日期的唯一列表。如果您单击这个过滤器列表的任何选项，Django 就会生成一个唯一的记录列表，该列表与过滤器列表中的月或日的值相匹配。

记录动作:顶部动作，底部动作，动作

除了可以点击 Django 管理记录列表中的项目来编辑或删除它之外，在记录列表的顶部还有一个以单词“Action”开头的下拉菜单，你可以在前面的图中看到。默认情况下,“操作”下拉菜单提供“删除选定选项”项，通过选中每条记录左侧的复选框来同时删除多条记录。

如果您希望从记录列表顶部移除“操作”菜单，您可以使用actions_on_top选项并将其设置为False。此外，如果您希望将“动作”菜单添加到记录列表的底部，您可以使用图 11-19 所示的actions_on_bottom = True选项——注意，记录列表页面的底部和顶部都可以有“动作”菜单。

图 11-19。

Django admin list with Action menu on bottom due to actions_on_bottom

与“动作”菜单相关的另一个选项是actions_selection_counter，它在“动作”菜单的右侧显示所选记录的数量，也可以在图 11-19 中看到。如果您设置了actions_selection_counter = False，那么 Django 管理员会忽略与“动作”菜单相关的所选记录的数量。

尽管“Action”菜单仅限于一个操作——删除记录——但是可以通过 Django admin 类中的actions选项定义一个操作列表。¹

记录关系

在前面的模型章节中描述的 Django 模型关系——一对一、一对多和多对多——在 Django 管理类和 Django 管理的上下文中具有某些行为，这些行为值得在下面的小节中分别描述。

显示:列表显示(续)

当你有一个一对多的关系并声明相关的ForeignKey字段作为list_display选项的一部分时，Django admin 使用相关模型的__str__表示。图 11-5 显示了最后一个行为，其中有一列Item记录，其中Item模型用models.ForeignKey(Menu)定义了menu字段，因此该字段的输出是Menu模型__str__方法。

list_display选项不能直接接受ManyToManyField字段，因为它需要为表中的每一行执行单独的 SQL 语句；然而，通过 Django 管理类中的自定义方法将ManyToManyField集成到list_display中是可能的，这个过程在清单 11-12 和图 11-20 中有所说明。

图 11-20。

Django admin list_display option with ManyToManyField field

# models.py
from django.db import models

class Amenity(models.Model):
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)

class Store(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=30)
    city = models.CharField(max_length=30)
    state = models.CharField(max_length=2)
    email = models.EmailField()
    amenities = models.ManyToManyField(Amenity,blank=True)

# admin.py
from django.contrib import admin
from coffeehouse.stores.models import Store

class StoreAdmin(admin.ModelAdmin):
    list_display = ['name','address','city','state','list_of_amenities']
    def list_of_amenities(self, obj):
        return ("%s" % ','.join([amenity.name for amenity in obj.amenities.all()]))
    list_of_amenities.short_description = 'Store amenities'

admin.site.register(Store, StoreAdmin)

Listing 11-12.Django admin list_display option with ManyToManyField field

在清单 11-12 中，您可以看到Store模型有一个带有Amenity模型的ManyToManyField字段。为了通过list_display显示 Django admin 中的ManyToManyField字段的值，您可以看到有必要创建一个定制方法来对这些记录进行额外的查询。图 11-20 显示了该ManyToManyField字段的 Django 管理记录列表。请注意，这种设计会给数据库带来沉重的负担，因为它需要对每条记录进行额外的查询。

订单:管理订单字段(续)

admin_order_field选项还支持对相关模型中的字段进行排序。例如，在清单 11-13 中，您可以看到admin_order_field选项被应用于一个字段，该字段是具有ForeignKey字段关系的模型的一部分。

# models.py
class Menu(models.Model):
    name = models.CharField(max_length=30)
    creator = models.CharField(max_length=100,default='Coffeehouse Chef')
    def __str__(self):
        return u"%s" % (self.name)

class Item(models.Model):
    menu = models.ForeignKey(Menu)
    name = models.CharField(max_length=30)

# admin.py
from django.contrib import admin
from coffeehouse.stores.models import Store

class ItemAdmin(admin.ModelAdmin):
    list_display = ['menu','name','menu_creator']
    def menu_creator(self, obj):
        return obj.menu.creator
    menu_creator.admin_order_field = 'menu__creator'

admin.site.register(Item, ItemAdmin)

Listing 11-13.Django admin admin_order_field option with ForeignKey field

关于清单 11-13 值得注意的最重要的事情是指定字段menu__creator的双下划线，它告诉 Django 管理员访问相关模型中的字段——注意这个双下划线是在第八章中描述的 Django 模型关系查询中用于执行查询的相同语法。

搜索:search_fields 和 list_filter(续)，管理。RelatedOnlyFieldListFilter，list_select_related

另外两个支持相同双下划线语法(也称为“跟随符号”)的 Django 管理类选项是search_fields和list_filter。这意味着您可以为相关模型(例如search_fields = ['menu__creator'])启用搜索并生成过滤器。

仅适用于模型关系的list_filter选项的变体是admin.RelatedOnlyFieldListFilter。当属于某个关系的模型记录可以跨越单个关系时，可能会导致创建不必要的筛选器。

举个例子，我们来看一个Store和Amenity车型的关系；您可以为Store记录列表上的Amenity值生成 Django 管理过滤器，但是如果Amenity型号记录是通用的并且在Store型号之外使用(例如，Employees的Amenity值)，您将在商店记录列表中看到不适用的过滤器值。使用admin.RelatedOnlyFieldListFilter可以防止这种情况，这个过程在清单 11-14 和图 11-21 和 11-22 中进行了说明。

图 11-22。

Django admin list_filter option with RelatedOnlyFieldListFilter

图 11-21。

Django admin list_filter option with no RelatedOnlyFieldListFilterDjango

# admin.py
class StoreAdmin(admin.ModelAdmin):
    list_display = ['name','address','city','state','list_of_amenities']
    list_filter = [['amenities',admin.RelatedOnlyFieldListFilter]]
    def list_of_amenities(self, obj):
        return ("%s" % ','.join([amenity.name for amenity in obj.amenities.all()]))
    list_of_amenities.short_description = 'Store amenities'
Listing 11-14.Django admin list_filter option with admin.RelatedOnlyFieldListFilter

在清单 11-14 中，注意生成过滤器的字段——在本例中是amenities——是如何与admin.RelatedOnlyFieldListFilter一起被包装在它自己的列表中的。为了理解使用和不使用admin.RelatedOnlyFieldListFilter的区别，请看图 11-21 和 11-22 。在图 11-21 中，注意列表中的最后一个过滤器是“按摩椅”——一个Amenity记录——但是主列表中没有Store记录有这个舒适性。要从Store记录列表中删除这个不适用的过滤器，您可以使用admin.RelatedOnlyFieldListFilter并从图 11-22 中获得结果，图中仅显示与Store记录相关的Amenity过滤器。

最后，另一个适用于具有模型关系的 Django 管理类的选项是list_select_related。list_select_related选项的功能就像在涉及关系的查询中使用的list_select_related选项，以减少涉及关系的数据库查询的数量(例如，它创建单个复杂的查询，而不是以后需要为每个关系发出多个查询)。list_select_related选项可以接受布尔值或列表值。默认情况下，list_select_related选项接收一个False值(即不使用)。在底层，list_select_related选项使用相同的select_related()模型方法来检索相关记录，如第八章所述。

如果list_select_related = True那么select_related()总是被使用。为了对list_select_related进行更细粒度的控制，您可以指定一个列表，注意空列表会阻止 Django 调用select_related()，任何其他列表值都会作为参数直接传递给select_related()。

Django admin 创建、更新、删除记录选项

除了 Django admin read record 选项，主要用于修改 Django admin 中每个模型的主页(即每个模型的记录列表)，还有其他 Django admin 页面用于创建、更新和删除 Django 模型记录，这些页面也支持一系列选项。

当你点击显示模型记录的每个 Django 管理页面右上方的“添加”按钮时，你会被带到一个类似表格的页面，在这里你可以为一条新记录提供值，如图 11-23 所示；当你点击 Django 管理记录列表中的一条记录时，你也会被带到一个类似表格的页面，在这里你可以编辑或删除该记录的字段值，如图 11-24 所示。

图 11-23。

Django 管理页面创建模型记录

图 11-24。

Django 管理页面编辑或删除模型记录 Tip

如图 11-23 和 11-24 所示的娱乐场所界面更加友好，参见图 11-37 和 11-38 中的filter_horizontal和filter_vertical选项。

在接下来的小节中，我将描述 Django admin 中用于创建、更新和删除记录的各种选项，值得注意的是，这三个操作都在同一个页面上。

记录表单:字段、只读字段、排除、字段集、表单字段覆盖、表单、预填充字段

默认情况下，Django 管理员为您正在处理的 Django 模型中的所有字段生成一个表单。例如，在图 11-23 和 11-24 中，您可以看到 Django 管理表单中的六个字段，它们对应于Store Django 模型的六个字段定义。在幕后，由于 Django admin 使用填充了模型记录的表单，Django admin 表单的操作和选项几乎与第九章中描述的模型表单相同。

第一个可以改变 Django 管理表单字段数量的选项是fields选项。fields选项允许您改变表单字段出现的顺序，或者创建一个带有模型字段子集的表单。清单 11-15 展示了fields在 Django 管理类中的用法，图 11-25 展示了清单 11-15 生成的 UI。

图 11-25。

Django admin fields option for Django admin forms

class StoreAdmin(admin.ModelAdmin):
      fields = ['address','city','state','email']

admin.site.register(Store, StoreAdmin)

Listing 11-15.Django admin fields option

for Django admin forms

在清单 11-15 中，您可以看到fields选项包含四个字段，而原始支持Store Django 模型包含六个字段；在图 11-25 中，你可以确认 Django 管理表单仅仅由四个字段生成。

Django 管理表单的同一个fields选项的另一个变体是将多个表单字段组合到同一个 UI 行中。这很容易通过将字段嵌套在它们自己的元组中来实现。例如，如果定义了fields = ['address',('city','state'),'email']，city和state表单字段在表单的同一行生成，如图 11-26 所示。

图 11-26。

Django admin fields option with wrapped fields for Django admin forms Tip

list_editable 选项创建一个内嵌表单来编辑记录，而不需要进入如图 11-25 和 11-26 所示的专用表单页面。参见上一节“记录链接和内嵌编辑”。

虽然fields选项很有帮助，但在其他情况下，可能需要显示一个表单域，但不允许它被更改，因为完全忽略一个域可能会导致混乱。要禁止编辑表单域，您可以使用readonly_fields选项。清单 11-16 展示了readonly_fields选项的使用，图 11-27 展示了它的 UI 布局。

图 11-27。

Django admin readonly_fields option for Django admin forms

class StoreAdmin(admin.ModelAdmin):
      readonly_fields = ['name','amenities']

admin.site.register(Store, StoreAdmin)

Listing 11-16.Django admin readonly_fields option

for Django admin forms

在清单 11-16 中，您可以看到readonly_fields选项使name和amenities字段变为只读。因为没有使用 fields 选项，所以所有的模型字段都用于生成表单。在图 11-27 中，你可以看到name和amenities字段是如何显示为文本而不是输入表单字段，使它们不可编辑。

仅使用readonly_fields选项的副作用是这些字段定义被放置在表单的底部，如图 11-27 所示。如果您想保持与原始 Django 模型相同的表单字段顺序，那么您需要使用fields选项明确定义表单字段，这样表单字段顺序遵循fields选项，并且readonly_field中的任何字段都显示为只读，考虑到在fields选项中设置的字段位置。

除了支持模型字段名称之外，readonly_fields选项还支持可调用的方法来进一步添加定制行为。清单 11-17 展示了带有可调用的readonly_fields选项的使用，以及图 11-28 的 UI 布局。

图 11-28。

Django admin readonly_fields option for Django admin forms

from django.utils.safestring import mark_safe

class StoreAdmin(admin.ModelAdmin):
    fields = ['name','address',('city','state'),'email','custom_amenities_display']
    readonly_fields = ['name','custom_amenities_display']
    def custom_amenities_display(self, obj):
        return mark_safe("Amenities can only be modified by special request, please contact the store manager at %s to create a request" % (obj.email,obj.email))
    custom_amenities_display.short_description = "Amenities"

admin.site.register(Store, StoreAdmin)

Listing 11-17.Django admin readonly_fields option with callable for Django admin forms

在清单 11-17 中，您可以看到readonly_fields选项使用了custom_amenities_display可调用函数来创建一个定制字段。在底部的图 11-28 中，你可以看到这个新的定制字段——代替了原来的amenities字段——它显示了比图 11-27 更友好的消息，并且也是不可编辑的。

Django 管理类中表单的exclude选项是对fields选项的补充。而fields选项要求它显式地创建包含在 Django 管理表单中的字段列表，而exclude提供了相反的行为，要求它显式地列出不属于 Django 管理表单的字段。例如，对于具有字段 a、b、c 的 Django 模型，Django 管理类 fields = ('a '，' b ')选项等同于 exclude = ('c ')选项(即，两个选项生成相同的 Django 管理表单)。

Django 管理类的fieldsets选项提供了对用于在 Django 管理中创建和编辑记录的页面布局的更大控制。不像fields选项可以改变表单字段的顺序，甚至可以在同一行嵌套表单字段——如图 11-26 所示——fieldsets选项与字段选项一起工作，将一个页面分成多个集合。清单 11-18 说明了fieldsets选项的使用，图 11-29 和 11-30 相应的布局。

图 11-30。

Django admin fieldsets option for Django admin forms (collapsed)

图 11-29。

Django admin fieldsets option for Django admin forms

from django.utils.safestring import mark_safe

class StoreAdmin(admin.ModelAdmin):
    fieldsets = [
        ['Store general information', {
            'fields': ['name', 'email']
        }],
        ['Store location options', {
            'classes': ['collapse'],
            'fields': ['address',('city', 'state')],
        }],
    ]

admin.site.register(Store, StoreAdmin)

Listing 11-18.Django admin fieldsets option

for Django admin forms

在清单 11-18 中，你可以看到fieldsets选项接受由两个列表组成的列表值，其中每个列表代表 Django 管理页面的一部分，如图 11-29 和 11-30 所示。每个内部列表都由第一个参数和第二个参数组成，第一个参数表示部分的标题或头，第二个参数是一个字典。最后一个字典本身包含分配给一个字段的键的值——其功能就像前面描述的fields选项——和一个classes键，该键通过 CSS 类为该部分提供某些行为。在这种情况下，您可以看到清单 11-18 中的第二个部分表示'classes': ['collapse']，它告诉 Django 使该部分可折叠，在图 11-29 和 11-30 中，您可以欣赏这种折叠和未折叠的行为。

除了在fieldsets的classes键中使用的collapse选项，另一个有用的 CSS 类选项是wide，它在字段之间增加了更多的水平空间。注意，向classes键添加任意数量的 CSS 类都是有效的，可以是 Django admin 中包含的 CSS 类(即collapse和wide)，甚至是自定义的 CSS 类。

formfield_overrides选项提供了一种方法来覆盖与 Django 管理表单中的 Django 模型字段相关联的默认表单小部件。默认情况下，所有 Django 模型字段都有一个指定的小部件分配给它们，目的是生成一个表单——这个主题在第九章中讨论，具体见表 9-1 。但是，如果您觉得给定模型字段的默认小部件对 Django admin 来说不够用，您可以使用清单 11-19 中所示的formfield_overrides选项。

from django.contrib import admin
from coffeehouse.items.models import Menu

class MenuAdmin(admin.ModelAdmin):
    formfield_overrides = {
        models.CharField: {'widget': forms.Textarea}
    }

admin.site.register(Menu, MenuAdmin)

Listing 11-19.Django admin formfield_overrides option

for Django admin forms

清单 11-19 中的formfield_overrides选项告诉 Django 管理员为所有使用 CharField的模型字段使用forms.Textarea小部件——它生成一个标准的 HTML 标签。在图<a href="#Fig32"> 11-32 </a>中，您可以看到应用清单<a href="#Par108"> 11-19 </a>的<code>formfield_overrides</code>选项的效果，而在图<a href="#Fig31"> 11-31 </a>中，您可以看到用于<code>CharField</code>字段的默认小部件，它是一个标准的 HTML <input/>标签。

图 11-32。

Django admin custom CharField field display in Django admin form using formfield_overrides

图 11-31。

Django admin default CharField field display in Django admin form

虽然前面所有的选项都允许您调整 Django admin 中使用的表单的一部分，但是有时有必要为 Django admin 从头创建一个表单，而不是调整 Django 模型生成的底层表单(例如，如果您需要对 Django admin 表单进行定制验证)。要为 Django 管理类指定定制表单，可以使用form选项。

最后，与 Django 管理表单相关的另一个选项是prepopulated_fields，它特定于需要 slug 字段值的模型。如果您不熟悉术语“slug ”,最简单地说，slug 字段值是字符串的机器友好表示，例如，大写字母被转换为小写字母，空格等特殊字符被转换为破折号。通过prepopulated_fields选项，您可以告诉 Django，当用户为 Django 管理表单中的给定字段键入值时，它会自动用第一个字段的 slug 表示填充表单中的另一个字段。

例如，对于prepopulated_fields = {'address': ['city','state']}选项，如果用户在城市表单字段中键入值圣地亚哥，在州中键入 CA，Django 用值san-diego-ca填充address表单字段。值得一提的是，该功能是通过集成到 Django admin 中的 JavaScript 实现的，并且prepopulated_fields选项不接受DateTimeField、ForeignKey或ManyToManyField字段作为支持模型数据类型。

动作、链接和位置:保存在顶部、另存为(克隆记录)、另存为继续和查看现场

在创建、更新和删除 Django 模型记录的每个表单页面的底部都有在页面上执行操作的按钮:“删除”、“保存并添加另一个”、“保存并继续编辑”和“保存”，所有这些都如图 11-33 所示。如果一个表单太大，不向下滚动就很难找到这些动作按钮，所以为了解决这个问题，Django 管理类支持save_on_top选项，它在页面顶部创建相同的动作按钮，如图 11-34 所示。请注意，要生成图 11-34 中的布局，您需要使用save_on_top = True。

图 11-34。

Django admin save_on_top option on form page

图 11-33。

Django admin standard action button on form page

有时候，需要从 Django admin 中预先存在的记录生成一个相同或几乎相同的记录。因为在 Django admin 中将值从一个表单复制粘贴到另一个表单是一个耗时且容易出错的过程，所以 Django admin 类还支持save_as选项来克隆预先存在的模型记录。如果在 Django 管理类上设置了save_as = True选项，Django 会用“另存为新的”按钮替换“保存并添加另一个”按钮，如图 11-35 所示。

图 11-35。

Django admin save_as (Clone) option on form page

如果你点击图 11-35 所示的“另存为新的”按钮，Django 会保存一个相同的记录——有效地克隆你在屏幕上看到的记录——使用不同的id值来区分两者。请注意，如果底层 Django 模型禁止这种操作(例如，字段必须是惟一的)，则操作不会发生，并且会抛出一个错误来指出原因。

当您使用save_as = True选项并执行克隆记录的动作时(即点击“另存为新的”按钮)，Django 管理员会让您保持新克隆记录的形式，以防您想进一步更改它。您可以使用save_as_continue = False选项，告诉 Django 管理员在克隆记录后将您重定向到主模型列表页面。

Django 模型类支持一个名为get_absolute_url()的实例方法，该方法使得通过 Django 模型的字段解析记录的公共 URL 成为可能(例如，URL/store/1/、/store/2/、/store/3/符合一个模式，其中每个数字代表一个商店id值，在这种情况下，Store模型的get_absolute_url()方法将返回/store/<store_record_id>。在 Django admin 中，get_absolute_url()方法被直接绑定到一个链接，该链接有助于在公共 URL 目的地查看记录，图 11-36 在右上角显示了这个链接。

图 11-36。

Django admin 'View on site' button due to get_absolute_url() Django model method

在图 11-36 中，右上角的“查看站点”按钮基于 Django 模型的get_absolute_url()方法以及在最后一个方法中定义的当前记录的值生成一个链接。通过这种方式，只需单击一下，您就可以在 Django admin 的公共 URL 目的地看到您正在编辑的记录。如果您想禁用这个按钮，您可以将view_on_site = False选项添加到 Django admin 类中。注意，如果底层 Django 模型类没有定义get_absolute_url()方法，那么无论view_on_site值是多少，都不会显示按钮。

关系:filter_horizontal、filter_vertical、radio_fields、raw_id_fields、inlines

与创建、更新和删除操作相关的 Django 模型关系任务在 Django 管理类的上下文中也有某些行为，值得单独描述。

当您在 Django 模型上使用一个ManyToManyField字段并在 Django 管理中访问它时，Django 会生成 HTML ManyToManyField字段的值——如图 11-23 和 11-24 底部所示。然而，因为这种类型的选择方法对于大型列表来说很麻烦，Django admin 提供了filter_horizontal和filter_vertical选项来生成单独的面板，使得值选择更容易。图 11-37 为filter_horizontal选项布局示意图，图 11-38 为filter_vertical选项布局示意图。

图 11-38。

Django admin filter_vertical option for ManyToManyField

图 11-37。

Django admin filter_horizontal option for ManyToManyField

在图 11-37 和 11-38 中，你可以看到有两个面板可以选择和取消选择给定ManyToManyField的值，唯一的区别是filter_horizontal水平堆叠面板-在图 11-37 中-而filter_vertical垂直堆叠面板-在图 11-38 中。

假设ManyToManyField字段被命名为amenities，为了实现图 11-37 中的布局，您将声明filter_horizontal = ['amenities']，为了实现图 11-38 中的布局，您将声明filter_vertical = ['amenities']。

当您在 Django 模型字段中使用ForeignKey模型数据类型或choices选项，并在 Django 管理中访问它时，Django 还会生成 HTML ForeignKey字段的值——如图 11-39 顶部所示。

图 11-39。

Django admin default select list for ForeignKey or choices option

Django admin 类可以用radio_fields选项改变这个默认布局，生成一个带有 HTML 单选按钮的布局。清单 11-20 展示了 Django 管理类中radio_fields选项的两种选择，以及图 11-40 和 11-41 的 UI 布局。

图 11-41。

Django admin vertical radio_fields option for ForeignKey or choices option

图 11-40。

Django admin horizontal radio_fields option for ForeignKey or choices option

from django.contrib import admin
from coffeehouse.items.models import Item

# Option 1 (Horizontal)

class ItemAdmin(admin.ModelAdmin):
    radio_fields = {"menu": admin.HORIZONTAL}

admin.site.register(Item, ItemAdmin)

# Option 2 (Vertical)

class ItemAdmin(admin.ModelAdmin):
    radio_fields = {"menu": admin.VERTICAL}

admin.site.register(Item, ItemAdmin)

Listing 11-20.Django admin radio_fields option

for ForeignKey field

在清单 11-20 中，你可以看到选项一用{"menu": admin.HORIZONTAL}字典定义了radio_fields值，其中menu代表ForeignKey字段或带有choices选项的字段，而admin.HORIZONTAL是单选字段的方向——该选项生成了如图 11-40 所示的布局。清单 11-20 中的选项二以类似的方式定义了radio_fields，除了它使用admin.VERTICAL值来告诉 Django admin 为 radio 字段生成一个垂直布局，如图 11-41 所示。

对于ForeignKey或ManyToManyField字段的另一个 Django 管理选项是raw_id_fields选项，顾名思义，它依赖于原始的id字段值来分配一个ForeignKey值或ManyToManyField值。图 11-42 展示了一个raw_id_fields选项在 Django 管理中的样子。

图 11-42。

Django admin raw_id_fields option for ForeignKey or ManyToManyField option

如图 11-42 所示，Django admin 生成一个基本文本框，您可以在其中分配id值，旁边的放大镜按钮可以帮助您搜索和选择值。假设ForeignKey或ManyToManyField字段被命名为menu，要实现图 11-42 中的布局，您需要声明raw_id_fields = ["menu"]。请注意，对于ForeignKey字段，可接受的值是单个id，对于ManyToManyField字段，您还可以引入一个由逗号分隔的 id 列表(即 CSV)。

最后，我们来看 Django 管理类inlines选项，它是为反向模型关系设计的。当您在 Django admin 中创建或编辑带有关系的模型时，如果这是在带有关系字段定义的模型(即ForeignKey或ManyToManyField)上完成的，Django admin 会显示相关的模型内联值，或者添加一个“+”按钮来添加新的模型值，如图 11-37–用于ForeignKey menu值–和图 11-39–用于ManyToMany amenities值所示。然而，当您试图编辑或创建逆向模型关系(即没有关系字段的模型)的值时，Django admin 仅显示模型本身，如图 11-31 所示。可以使用inlines选项编辑或创建反向模型关系的相关模型值。

inlines选项首先要求您创建一个 Django admin TabularInline或StackedInline类，这两个类都是InlineModelAdmin类的子类，后者是用于创建标准 Django admin 类的标准admin.ModelAdmin类的更专门化版本。一旦有了TabularInline或StackedInline类，就可以将它声明为inlines选项值的一部分。

清单 11-21 展示了两个 Django 管理示例，它们在具有一对多和多对多关系的模型上使用了TabularInline和StackedInline类。

# admin.py (ForeignKey)
from django.contrib import admin
from coffeehouse.items.models import Item, Menu

class ItemInline(admin.TabularInline):
    model = Item

class MenuAdmin(admin.ModelAdmin):
    list_display = ['name']
    inlines = [
        ItemInline,
    ]

admin.site.register(Menu, MenuAdmin)

# admin.py (ManyToManyField)
from django.contrib import admin
from coffeehouse.stores.models import Store, Amenity

class StoreInline(admin.StackedInline):
    model = Store.amenities.through

class AmenityAdmin(admin.ModelAdmin):
    inlines = [
        StoreInline,
    ]

admin.site.register(Amenity, AmenityAdmin)

Listing 11-21.Django admin inlines option

for ForeignKey and ManyToManyField field

清单 11-21 中的第一个例子展示了ItemInline类，它继承了内置TabularInline类的行为。因为最后一个类被设计用来表示 Django admin 中的一个模型，所以它也用Item模型类声明了model字段。接下来，MenuAdmin类是为Menu模型类设计的标准 Django 管理类，但是请注意它使用了inlines选项和ItemInline类。由于这最后一个配置，当您在 Django admin 中编辑或创建Menu模型记录时，所有与给定Menu模型记录相关的Item模型记录都显示在内联中，如图 11-43 所示。

图 11-43。

Django admin inlines option with TabularInline for ForeignKey

如图 11-43 所示，除了用于编辑或创建Menu记录的标准 Django 管理表单，还有一个显示给定Menu记录的所有Item模型记录的表单集；在这种情况下，表单集包含属于Drinks Menu记录的Item记录。还要注意图 11-43 中表单集中每个表单的表单字段都被内联为选项卡，这是由TabularInline类提供的行为。

清单 11-21 的第二部分展示了从内置StackedInline类继承其行为的StoreInline类。因为最后一个类被设计用来表示 Django admin 中的一个模型，它还用Store.amenities.through模型类声明了model字段，这个额外的模型语法——amenities.through——是必要的，因为Store到Amenity模型是多对多的关系。注意through关键字是多对多关系查询的标准，在前面的 Django 模型章节中有描述。

接下来，AmenityAdmin类是一个为Item模型类设计的标准 Django 管理类，但是请注意，它对StoreInline类使用了inlines选项。由于最后一个配置，当您在 Django admin 中编辑或创建一个Amenity模型记录时，所有与给定Amenity模型记录相关的Store模型记录都显示在内联界面上，如图 11-44 所示。

图 11-44。

Django admin inlines option with StackedInline for ManyToManyField

如图 11-44 所示，除了用于编辑或创建Amenity记录的标准 Django 管理表单，还有一个显示给定Amenity记录的所有Store模型记录的表单集；在这种情况下，表单集包含具有Amenity Laptop locks记录的Store记录。还要注意图 11-43 中表单集中每个表单的表单字段都是内嵌堆栈，这是由StackedInline类提供的行为。

Tip

InlineModelAdmin类(即TabularInline或StackedInline)除了model选项之外，还支持前面介绍的标准 Django 管理类—admin.ModelAdmin—选项(如form、fields、exclude)，以及第六章介绍的标准表单集选项和第九章介绍的模型表单集选项(如formset、extra、max_num、min_num)。 ²

Django admin 自定义页面布局、数据和行为

除了前面章节中描述的 Django 管理类选项之外，还有多种方法可以定制 Django 管理页面的布局、数据和行为。您可以定制在所有 Django 管理页面上使用的某些全局值，而无需修改任何 Django 模板。但是除此之外，还可以定制 Django 管理页面使用的任何模板——如登录、注销、密码更新、显示记录和创建/更新/删除记录页面——以改变其布局(例如，修改页面中默认的蓝色 CSS 皮肤或组件位置)。

最后，还可以定制传递给 Django 管理页面的数据，以及通过将方法和字段声明为 Django 管理类的一部分来修改 Django 管理页面运行的默认行为(例如 CRUD 操作)。

Django admin 默认模板的自定义全局值

默认情况下，Django admin 被配置为 Django 项目的urls.py文件的一部分，如下面的代码片段所示:

from django.conf.urls import url
from django.contrib import admin

urlpatterns = [
    url(r'^admin/', admin.site.urls),
]

虽然django.contrib包中的admin.site.urls允许您在/admin/ url 上设置 Django 管理，但是同一个django.contrib.admin.site对象也允许您定制所有 Django 管理页面使用的某些值。

清单 11-22 展示了如何通过django.contrib.admin.site对象定制几个 Django 管理字段。

from django.conf.urls import url
from django.contrib import admin

admin.site.site_header = 'Coffeehouse admin'
admin.site.site_title = 'Coffeehouse admin'
admin.site.site_url = 'http://coffeehouse.com/'
admin.site.index_title = 'Coffeehouse administration'
admin.empty_value_display = '**Empty**'

urlpatterns = [
    url(r'^admin/', admin.site.urls),
]

Listing 11-22.Django admin django.contrib.admin.site object to customize fields

Tip

也可以在清单 11-22 的settings.py文件中定义定制的管理字段值。只需导入django.contrib.admin并声明管理字段，将它们与settings.py中的其他定制配置集中在一起。

正如您在清单 11-22 中看到的，在将admin.site.urls声明为url语句之前，在admin.site对象上有一系列声明，它们也是django.contrib包的一部分:

图 11-46。

Django admin login page with custom global values

图 11-45。

Django admin main index with custom global values

admin.site.site_header。-定义在所有 Django 管理页面上使用的标题(例如，在深蓝色标题和登录页面中)。参见图 11-45 和 11-46 。
admin.site.site_title。-定义所有 Django 管理页面使用的标题，作为 HTML 标题的一部分。参见图 11-45 和 11-46 。
admin.site.site_url。-定义作为 Django admin“查看站点”链接的一部分使用的域(例如，coffeehouse.com),以便从 Django admin 轻松访问实时站点。见图 11-45 。
admin.site.index_title。-定义 Django 管理主页的标题。见图 11-45 。
admin.empty_value_display。-定义 Django 管理模型值为空时显示的默认值。

正如您在图 11-45 和 11-46 中所看到的，通过类似清单 11-22 中的一些简单语句，您可以定制 Django 管理模板内容，而无需与模板或 HTML 交互。

值得注意的是，当记录字段包含空值时，清单 11-22 中描述的admin.empty_value_display选项适用于所有 Django 管理模型。本章前面的“记录显示”部分描述了admin.empty_value_display选项的示例，特别是图 11-5 和 11-6 ，以及清单 11-5 。

Django admin 自定义页面布局和自定义模板

虽然清单 11-22 中的django.contrib.admin.site对象选项提供了一种快速定制 Django 管理页面的方法，但是在面对更复杂的需求时，它们可能会有所不足，在这种情况下，您必须依赖定制模板。

Django 管理员使用的默认模板位于操作系统或虚拟 env Python 环境中 Django 安装的/django/contrib/admin/templates/目录下(例如<virtual_env_directory>/lib/python3.5/site-packages/django/contrib/admin/templates/)。

类似于前面章节中描述的 Django 模板定制技术(例如，Django 表单小部件、Django allauth)，您可以创建这些默认模板的副本，并将它们放在您的项目中。通过这种方式，项目中的模板优先于默认的 Django 管理模板，您可以定制项目模板来满足您的需求。

Django admin /django/contrib/admin/templates/目录包含两个模板文件夹:admin和registration。将它们复制到一个项目目录中，该目录是settings.py中TEMPLATES/DIRS变量的DIRS文件夹的一部分。

Tip

请参阅该书附带的源代码，其中包括所有 Django 管理模板的布局。

所有 Django 管理模板都从admin/base_site.html模板继承了它们的行为，而模板本身又从admin/base.html模板继承了它的行为。如果你不熟悉 Django 模板继承是如何工作的，请阅读第三章描述这个主题。

如果您打开admin/base.html模板，您可以看到每个 Django 管理页面背后的核心结构，例如 HTML <head>部分(例如 CSS 文件、meta 标签)、导航标题和消息通知块等等。因此，您可以修改admin/base.html模板来包含定制的 CSS 或 JavaScript 文件，以改变每个 Django 管理页面的“外观”。

除了admin/base.html模板，在admin和registration目录中还有许多其他模板，它们的功能在下面的列表中描述:

admin/404.html和admin/500.html。-分别为 Django admin not found 和 error 页面(即 HTTP 404 和 HTTP 500)定义布局。
admin/index.html。-定义主页面上 Django 管理索引页面的布局–如图 11-45 所示–以及显示所有型号的应用索引的布局。
admin/change_list.html。-定义用于读取记录的 Django 管理列表页面的布局，如图 11-1 到 11-22 所示。
admin/change_form.html。-定义 Django 管理表单页面的布局，这些页面用于创建、更新和删除记录，如图 11-23 到 11-44 所示。
admin/login.html。-定义 Django 管理员登录页面，如图 11-46 所示。
registration文件夹。-包含各种 Django 管理页面密码更改操作的模板，以及 Django 管理注销页面布局。

Note

此列表中未描述的admin文件夹中的其他页面(例如filter.html、object_history.html)是更细粒度的模板，包含在此列表的较大模板中，您可以根据需要进行定制。

正如您所看到的，通过创建 Django 管理模板的副本并将它们放在您的项目中，您可以通过修改其支持模板来微调每个 Django 管理页面的布局。关于 Django admin index.html、change_list.html和change_form.html模板，一个重要的模块化行为值得一提，那就是它们如何应用于单独的 Django 管理应用或模型。

默认情况下，如果您为admin/index.html、admin/change_list.html或admin/change_form.html模板提供自定义布局，这些模板将用于 Django 管理中的所有应用和模型(即全局)。然而，有时可能需要定制 Django 管理索引页面、列表页面或表格页面，仅用于某些应用(例如，stores应用)或包含单个模型(例如，Item模型)。

要为应用中的所有模型定义自定义 Django 管理模板，您可以创建一个 Django 管理模板，并将其放在模板路径admin/<app_name>/下(例如，admin/stores/change_list.html为所有stores应用模型定义一个change_list.html模板)。

要为单个模型定义一个定制的 Django 管理模板，您可以创建一个 Django 管理模板，并将其放在模板路径admin/<app_name>/<model>/下(例如，admin/items/item/change_list.html定义一个change_list.html模板，以便在items应用的Item模型上使用)。

Note

只有模板admin/index.html-admin/app_index.html、change_form.html、change_list.html、delete_confirmation.html、object_history.html,和popup_response.html可以按应用和型号进行定制。

Django 管理自定义静态资源

如果您在项目中使用定制 CSS 或 JavaScript 文件定制 Django admin admin/base.html模板，这些静态资源将在每个 Django 管理页面上生效。虽然在某些情况下这可能是一个理想的效果，但在其他情况下，可能有必要只对某些 Django 管理页面应用自定义静态资源。

Django 管理类支持Media类来定义 CSS 和 JavaScript 文件，并将它们包含在与给定 Django 管理类相关的所有页面上。在 Django 管理类上使用Media类的优点是，您不需要处理模板或 HTML 标记，Django 管理会自动加载静态资源，作为链接到管理类的每个管理页面的一部分。清单 11-23 展示了一个 Django 管理类，它使用了Media类。

from django.contrib import admin
from coffeehouse.items.models Item

class ItemAdmin(admin.ModelAdmin):
      list_per_page = 5
      class Media:
            css = {
                "screen": ("css/items/items.css",)
            }
            js = ("js/items/items.js",)

admin.site.register(Item, ItemAdmin)

Listing 11-23.Django admin class with Media class to define custom static resources

如清单 11-23 所示，Media类支持css和js字段分别声明 CSS 和 JavaScript 静态文件。在css的情况下，清单 11-23 声明了一个字典，其中键对应于 CSS 媒体类型，值是一个带有 CSS 文件的元组。对于js的情况，清单 11-23 声明了一个指向 JavaScript 文件的元组。所有声明为Media类一部分的文件都会在 Django 的静态文件目录路径中自动搜索——如第五章所述。

清单 11-23 的最终结果是，所有与ItemAdmin管理类相关联的 Django 管理页面(例如index.html、change_list.html, change_form.html)都将包含一个额外的 CSS 导入语句(例如<link href="/static/css/items/items.css" type="text/css" media="screen" rel="stylesheet" />)，以及一个额外的 JavaScript 导入语句(例如<script type="text/javascript" src="/static/js/items/items.js"></script>)。

值得指出的是，虽然您可以在 Django 管理页面中包含任何第三方 CSS 或 JavaScript 库(例如 Bootstrap、D3)，但是 Django 管理页面已经在django.jQuery名称空间下包含了流行的 jQuery 2.2 库来实现某些功能。Django admin 使用一个 jQuery 名称空间，允许您在 Django admin 页面中导入任何其他 jQuery 库版本，而不用担心冲突。如果您想将包含的 Django admin jQuery 库用于您自己的定制 JavaScript，您必须将您的 JavaScript 逻辑包装在这个名称空间中，如下面的代码片段所示:

(function($) {
    // Custom JavaScript logic leveraging the Django admin built-in jQuery libray
    $(document).ready(function() {
       $('.deletelink').on('click',function() {
            if( !confirm('Are you sure you want to delete this record ?')) {
              return false;
           }
       });
    });
})(django.jQuery); // <-- Note wrapping namespace

正如您在最后一个代码片段中看到的，通过将您的定制 JavaScript 逻辑包装在django.jQuery名称空间中，它获得了对 Django admin 内置 jQuery 库的访问权(即，定制 JavaScript 逻辑获得了对 jQuery $范围的访问权)。

Grappelli Project – an Out-Of-Box Django Admin Supplement

如果你想为 Django admin 尝试不同的“外观和感觉”,而不必编写自定义模板或支持 CSS 和 JavaScript 文件，有各种各样的 Django 应用为此而设计。

最受欢迎的应用之一是“Grappelli 项目”。Grappelli 使用“指南针”CSS 创作框架来包含额外的 Django 管理功能，如:自动完成、内嵌可排序的“拖放”和对 jQuery 插件的支持，等等。

Django 管理自定义数据和行为，带有管理类字段和方法

虽然 Django 管理模板的修改允许您生成任何类型的 Django 管理页面布局，但对于需要在 Django 管理页面中包含自定义数据(例如，添加来自另一个模型的数据以供参考)或覆盖 Django 管理页面的默认 CRUD 行为(例如，为删除操作执行自定义审计跟踪)的情况，它仍然存在不足。

Django 管理类，就像你在本章中从清单 11-1 开始编写的那些类，依赖于二十多个字段——所有这些都是你在本章前面的章节中作为 Django 管理读取选项和创建/更新/删除选项探索过的——和三十多个方法 ⁴ 来定义 Django 管理页面的默认数据和行为。

与您如何定制 Django 基于类的视图所使用的默认行为和数据非常相似——如第九章所述——Django 管理类也可以定义它们自己的定制字段和方法来覆盖它们的默认数据和行为。

这一章的大部分内容已经涵盖了所有用于定制 Django 管理页面行为的 Django 管理类字段，所以我不再赘述。然而，我将提供最常见的 Django 管理类方法的例子，以说明如何在 Django 管理页面中添加定制数据和覆盖其他默认行为。

清单 11-24 展示了一个 Django admin 类，它使用了changelist_view()方法的自定义实现——在底层 Django admin change_list.html模板中添加了要访问的自定义数据——以及delete_view()方法的自定义实现——在对 Django admin 类执行删除操作时执行自定义逻辑。

from coffeehouse.stores.models import Store

class StoreAdmin(admin.ModelAdmin):
    search_fields = ['city','state']
    def changelist_view(self, request, extra_context=None):
        # Add extra context data to pass to change list template
        extra_context = extra_context or {}
        extra_context['my_store_data'] = {'onsale':['Item 1','Item 2']}
        # Execute default logic from parent class changelist_view()
        return super(StoreAdmin, self).changelist_view(
            request, extra_context=extra_context
        )
    def delete_view(self, request, object_id, extra_context=None):
        # Add custom audit logic here
        #
        # Execute default logic from parent class delete_view()
        return super(StoreAdmin, self).delete_view(
            request, object_id, extra_context=extra_context
        )

admin.site.register(Store, StoreAdmin)

Listing 11-24.Django admin class with custom 
changelist_view() and delete_view() methods

正如您在清单 11-24 中所看到的，changelist_view()和delete_view()方法都是用您之前学习的 Django admin search_fields选项内联声明的。在这种情况下，每当您在 Django 管理中访问Store模型的列表视图页面时，清单 11-24 中的changelist_view()方法就会被触发(例如，如图 11-10 所示)。注意,changelist_view()方法向extra_context变量添加了一个自定义值，然后作为响应的一部分返回，在这种情况下，它是一个硬编码的值，但是您同样可以添加任何类型的数据，比如模型查询或第三方 API 调用，以传递给 Django 管理页面。由于这最后一个工作流，Store模型的列表视图页面(即change_list.html模板)可以访问定制数据以显示为部分页面。

清单 11-24 中的delete_view()方法在您删除 Django admin 中的Store模型时被触发。在这种情况下，清单 11-24 中的delete_view()方法只是通过调用父类的delete_view()方法来触发删除记录的默认操作，但是您可以看到，无论何时在 Django admin 中的Store模型上执行删除操作，都可以执行定制逻辑(例如，创建审计跟踪)。

正如我已经提到的，Django 管理类依赖三十多种方法来实现它们的默认行为，您可以定制所有这些方法来满足您的需求。考虑到这些方法可以生成大量的自定义变量，您可以使用清单 11-24 中的示例作为指南，并参考上一页的脚注，了解您可以在 Django admin 类中自定义的其他方法。

Django 管理 CRUD 权限

默认情况下，Django admin 允许拥有超级用户和职员权限的用户访问——如果您从未听说过 Django 超级用户、Django 职员或 Django 权限这些术语，请参阅前面描述 Django 用户管理的章节。

Django 超级用户，顾名思义，意味着它是一个拥有超级权限的用户。通过扩展，这意味着超级用户可以访问 Django admin 中的任何页面，以及创建、读取、更新和删除 Django admin 中任何类型的模型记录的权限。因为 Django 超级用户代表了一个“要么全有，要么全无”的命题，所以 Django admin 也被设计为允许访问 Django staff 用户。

任何标记为 staff 的 Django 用户都可以访问 Django admin，但除此之外没有其他权限，除非明确授予权限，如图 11-47 所示。

图 11-47。

Django admin main page for staff user with no permissions

正如你在图 11-47 中看到的，Django 主管理页面是空的。虽然当您在项目的admin.py文件中没有注册的模型时，空的 Django 管理主页的场景也会出现，但是这种情况代表了没有显式模型权限的 staff 用户的场景。

为了让员工用户能够访问 Django 管理页面，必须通过模型权限的方式给予他们明确的权限，因为 Django 管理页面是基于 CRUD 模型操作的(例如，创建模型记录的 Django 管理页面，删除模型记录的 Django 管理页面)。

默认情况下，所有 Django 模型都被赋予了add、change,和delete权限，您可以将这些权限分配给 staff 用户。因此，每个模型权限代表一个 Django 管理页面的访问权限。

例如，如果一个 staff 用户被授予了一个模型的delete权限，这意味着他还被授予了在 Django admin 中删除该模型记录的权限。类似地，如果一个 staff 用户被授予了一个模型的add权限，这意味着他被授予了在 Django admin 中访问该模型的 create record 页面的权限。最后，如果一个职员用户被授予了一个模型的change权限，这意味着他被授予了 Django admin 中该模型的编辑记录页面的访问权。

Note

在给定的模型上授予用户delete权限也需要授予change权限来完成 Django admin 中的删除操作。这是因为 Django 管理记录更改页面上提供了 Django 管理删除操作。

从这种行为可以推断，通过使用 staff 用户和模型权限，您可以允许对 Django admin 的不同部分进行非常细粒度的访问，而不是“全有或全无”的 Django admin 超级用户行为。

不过，Django admin staff 用户还有一个重要的缺失行为:允许对 Django admin 中的模型记录进行只读访问的能力。因为 Django 模型默认拥有add、change和delete权限(即 CUD[创建、更新、删除]行为)，所以read权限被认为是隐含了change的存在(即如果您能够更改记录，那么您就能够读取它)。因此，要在 Django admin 中获得独立的只读权限，您必须添加一个定制的模型读取权限(即 CRUD 中缺少的 R)。

前一章更详细地描述了定制模型权限，但是我将在清单 11-25 中通过添加一个只读权限来描述 Django admin 上下文的这个过程。

# models.py
from django.db import models

class Menu(models.Model):
    name = models.CharField(max_length=30)
    creator = models.CharField(max_length=100,default='Coffeehouse Chef')

class Item(models.Model):
    menu = models.ForeignKey(Menu, on_delete=models.CASCADE)
    name = models.CharField(max_length=30)
    description = models.CharField(max_length=100)
    class Meta:

        permissions = (

            ('read_item','Can read item'),

        )

# admin.py
from django.contrib import admin

from coffeehouse.items.models import Item

class ItemAdmin(admin.ModelAdmin):
      list_per_page = 5
      list_display = ['menu','name','menu_creator']
      def get_readonly_fields(self, request, obj=None):

        if not request.user.is_superuser and request.user.has_perm('items.read_item'):

            return [f.name for f in self.model._meta.fields]

        return super(ItemAdmin, self).get_readonly_fields(

            request, obj=obj

        )

admin.site.register(Item, ItemAdmin)

Listing 11-25.Django model with custom read permission and Django admin class enforcing read permission

清单 11-25 中突出显示的第一步是带有自定义权限的Item模型，该自定义权限名为read_item，友好名称为'Can read item'。在您通过相应的迁移运行清单 11-25 中的Item模型之后，Item模型将获得一个定制的read_item权限。接下来，创建一个 staff 用户，并为其分配Item模型的read_item和内置change权限。一旦 staff 用户被授予这些权限，您必须强制 Django admin 类对Item模型只允许具有这些权限的用户进行读访问。

当用户被授予模型的change权限时，Django 管理员授予用户访问 Django 管理表单页面的权限，该页面用于更新给定模型的记录，如图 11-23 至 11-44 所示。但是因为您想将更新功能限制为只读，所以您必须将这个页面的表单字段设置为只读，这就是清单 11-25 的第二部分中的get_readonly_fields()方法的目的。

通过用自定义的get_readonly_fields()方法定义一个管理类，您可以告诉 Django 管理员在什么情况下您想要将 Django 管理页面的表单字段设置为只读。在这种情况下，您可以看到清单 11-25 中的get_readonly_fields()方法的逻辑使用is_superuser()和has_perm()方法来确定调用方是否不是超级用户(即员工)以及用户是否拥有对Item模型的read_item权限。如果最后一条规则成立，那么get_readonly_fields()方法将所有模型表单字段设置为只读，这就是get_readonly_fields()方法的全部目的。如果最后一个规则为假，那么get_readonly_fields()方法返回其默认行为，调用父类的默认get_readonly_fields()方法。

正如您在这个简短的练习中看到的，通过将自定义 Django 管理类方法与标准和自定义 Django 模型权限结合使用，在 Django 管理中没有限制或允许 CRUD 操作。

多个 Django 管理站点

通过这一章，你已经了解到 Django 管理站点是使用django.contrib.admin.site.urls在/admin/ url 下激活的。此外，Django 管理站点还要求将 Django 管理类的定义放在 Django 项目的 app admin.py文件中，并使用清单 11-1 (例如django.contrib.admin.site.register(Store,StoreAdmin))中描述的技术之一进行注册

虽然这是几乎所有 Django 管理站点安装的标准做法，但是当您想要或需要设置多个 Django 管理站点时，这个过程可能会有所不同。这当然引发了一个问题'为什么你想要或者需要多个 Django 管理站点？'

多个 Django 管理站点非常有用，因为它们允许您为不同类型的用户或组划分访问位置。例如，您可以设计一个 Django 管理站点，让员工跨不同的模型执行 CRUD 操作，同时设计一个完全不同的 Django 管理站点，让提供者跨另一组模型执行更有限的 CRUD 操作。

如果您维护一个 Django 管理站点，那么为多种类型的用户和模型创建一个解决方案会非常困难，因为您只有强制 CRUD 操作访问的用户权限，如前一节所述。对于多个 Django 管理站点，您可以根据自己的需求在一个或两个管理站点中注册模型。

创建多个 Django 管理站点的第一步是创建多个django.contrib.admin.AdminSite类的实例，如清单 11-26 所示

# urls.py (Main directory)
from django.conf.urls import include, url
from django.views.generic import TemplateView

from django.contrib import admin
admin.site.site_header = 'Coffeehouse general admin'

from coffeehouse.admin import employeeadmin, provideradmin

urlpatterns = [
url(r'^$',TemplateView.as_view(template_name='homepage.html'),name="homepage"),
url(r'^admin/', admin.site.urls),

url(r'^employeeadmin/', employeeadmin.urls),

url(r'^provideradmin/', provideradmin.urls),

]

# admin.py (Main directory)

from django.contrib.admin import AdminSite

class EmployeeAdminSite(AdminSite):

    site_header = 'Coffeehouse Employee admin'

employeeadmin = EmployeeAdminSite(name='employeeadmin')

class ProviderAdminSite(AdminSite):

    site_header = 'Coffeehouse Provider admin'

provideradmin = ProviderAdminSite(name='provideradmin')

Listing 11-26.Django admin multiple sites accessible on different urls

首先，注意清单 11-26 用urls.py中的django.contrib.admin类声明了标准 Django admin，包括一个定制的site_header值，用于在标准/admin/ url 上挂载 Django admin。接下来，两个自定义 Django 管理实例被配置在它们自己的 URL 上——/employeeadmin/和/provideradmin/——使用一个对应于自定义django.contrib.admin.AdminSite类的urls引用。

定制 Django 管理站点类EmployeeAdminSite和ProviderAdminSite都是在项目顶层目录中它们自己的admin.py文件中定义的(即，在主urls.py文件旁边)。注意每个自定义 Django 管理站点类是如何从django.contrib.admin.AdminSite类继承其行为的。接下来，观察清单 11-26 中的AdminSite类的每个实例如何定义site_header字段，以便为每个 Django 管理站点实例定义一个自定义头，就像对标准 Django 管理站点所做的那样。

此时，如果你访问自定义 Django 管理员的/employeeadmin/和/provideradmin/URL，你将访问如图 11-47 所示的 Django 管理员主页。在这两种情况下，您都会看到一个空的 Django 管理页面，因为每个定制的 Django 管理站点仍然没有注册任何模型。

要向一个定制的 Django 管理站点注册 Django 管理类，您可以使用清单 11-1 中描述的任何技术。不同之处在于，您必须向特定 Django 管理站点的实例(例如employeeadmin、provideradmin)注册 Django 管理类，而不是默认的django.contrib.admin类，如清单 11-27 所示。

# admin.py (stores app)
from django.contrib import admin
from coffeehouse.stores.models import Store,Amenity

class StoreAdmin(admin.ModelAdmin):
    search_fields = ['city','state']

# Default model registration on main Django admin
admin.site.register(Store, StoreAdmin)

# Model registration on custom Django admin named provideradmin

from coffeehouse.admin import provideradmin

provideradmin.register(Store, StoreAdmin)

# admin.py (items app)
from django.contrib import admin
from coffeehouse.items.models import Menu

class MenuAdmin(admin.ModelAdmin):
    list_display = ['name','creator']

# Default model registration on main Django admin
admin.site.register(Menu, MenuAdmin)

# Model registration on custom Django admin named provideradmin

from coffeehouse.admin import employeeadmin

employeeadmin.register(Menu, MenuAdmin)

Listing 11-27.Django admin class registration on multiple Django admin sites

注意在清单 11-27 中，除了通过admin.site.register完成的默认 Django 管理类注册之外，Store类注册到自定义provideradmin Django 管理类，Menu类注册到自定义employeeeadmin Django 管理类，这两个都是清单 11-26 中声明的自定义 Django 管理类。

正如您在清单 11-27 中看到的，在多个 Django 管理站点上注册同一个 Django 管理类是完全有效的，这个过程允许您有选择地访问不同 Django 管理站点下的某些模型。

Caution

多个 Django 管理站点不排除用户权限、认证或 url 可见性。默认情况下，所有 Django 用户都可以使用相同的凭证，并在多个 Django 管理站点上被分配相同的权限。这意味着由您决定在所有 Django 管理站点上实施有效的模型权限，限制每个 Django 管理站点的模型注册，以及避免容易猜测的 Django 管理 URL 以避免意外访问。

Footnotes 1

https://docs.djangoproject.com/en/1.11/ref/contrib/admin/actions/

https://docs.djangoproject.com/en/1.11/ref/contrib/admin/#inlinemodeladmin-options

http://grappelliproject.com/

https://docs.djangoproject.com/en/1.11/ref/contrib/admin/#adminsite-methods

十二、Django 的 REST 服务

自 2000 年首次出现以来，表述性状态转移(REST)服务或简单的 RESTful 服务已经成为 web 开发中最流行的技术之一。关于 REST 服务有一个很长的背景故事，我不会在这里深入讨论，REST 服务在 web 开发中的吸引力和爆炸性增长仅仅是因为它们如何以一种简单和可重用的方式解决一个常见的问题。

在这一章中，您将了解到可用 Django 创建 REST 服务的选项，包括普通 Python/Django REST 服务和特定于框架的 REST 服务。此外，您将了解如何使用普通的 Python/Django 包创建 REST 服务，以及它们何时优于使用特定于框架的 REST 服务包。此外，您还将学习如何创建和使用用 Django REST 框架创建的 REST 服务的一些最重要的特性，以及将基本的安全性集成到 Django REST 框架服务中。

Django 的 REST 服务

REST 服务通过端点或互联网 URL 提供对数据的访问，不假设谁使用它(例如，物联网设备、移动电话或桌面浏览器)；这意味着访问 REST 服务不需要任何设备或环境，您需要的只是互联网接入。

最重要的是，因为 REST 服务是在互联网 URL 上操作的，所以它们提供了一个非常直观的访问方案。例如，REST 服务 URL /products/可以表示“获取所有产品数据”，而 URL /products/10/20/可以表示获取价格在 10 到 20 之间的产品的所有数据，而 URL /products/drinks/可以获取饮料类别中的所有产品数据。

最后一种方法的强大之处在于，访问解决复杂数据查询的 REST 服务变体没有陡峭的学习曲线(例如，语言语法、复杂的业务逻辑)。由于这些特性和多功能性，REST 服务在许多领域和应用中都是可重用的数据骨干。例如，实际上整个 web API(应用编程接口)世界都是围绕 REST web 服务运行的，因为根据定义，API 必须为客户访问其功能提供一种设备/环境中立的方式。事实上，您访问的大多数网站很有可能以这样或那样的方式使用 REST 服务，这种做法允许网站运营商重用相同的数据，然后在桌面浏览器、物联网设备、移动应用、RSS 提要或任何其他目标(如加速移动页面(AMP))上为用户格式化数据。 ²

简要概述了 REST 服务之后，让我们从在 Django 中创建 REST 服务的最简单的选项开始。

设计为 REST 服务的标准视图方法

您实际上可以在 Django 中创建一个 REST 服务，只需要 Django 包和 Python 的核心包，而不需要安装任何第三方包。清单 12-1 展示了一个标准的 Django url 和视图方法，它被设计成 REST 服务的功能。

# urls.py (In stores app)
from coffeehouse.stores import views as stores_views

urlpatterns = [
    url(r'^rest/$',stores_views.rest_store,name="rest_index"),
]

# views.py (In stores app)
from django.http import HttpResponse
from coffeehouse.stores.models import Store
import json

def rest_store(request):
    store_list = Store.objects.all()
    store_names = [{"name":store.name} for store in store_list]
    return HttpResponse(json.dumps(store_names), content_type='application/json')

# Sample output
# [{"name": "Corporate"}, {"name": "Downtown"}, {"name": "Uptown"}, {"name": "Midtown"}]

Listing 12-1.Standard view method designed as REST service

清单 12-1 中的 url 语句定义了对rest目录下的stores应用的访问模式(即最终的 url /stores/rest/)。这最后一个 url 语句连接到rest_store视图方法——也在清单 12-1 中——该方法进行查询以从数据库中获取所有Store记录，然后创建一个列表理解以从结果查询中生成一个商店名称列表，最后使用 Django 的HttpResponse使用 Python 的json包返回一个带有商店名称的 JSON 响应。清单 12-1 中的设计是您可以在 Django 中创建的最简单的 REST 服务之一，并且有一些要点:

序列化。-请注意,Store查询并不直接用于响应，而是首先创建一个列表理解。这样做是为了将数据序列化为适当的格式。由于 Django 查询的构建方式，结果可能无法自然序列化，因此使用列表理解来确保数据是标准的 Python 字典，可以用 json 包转换成 JSON。在接下来的边栏中，我将提供更多的细节来说明为什么序列化是使用 REST 服务的一个重要部分。
响应处理。-注意使用 Django 的低级HttpResponse方法与 Django 更常用的render()方法来生成响应。虽然可以使用 Django 的render()方法，并进一步将数据传递给模板来格式化响应，但对于大多数 REST 服务来说，这是不必要的，因为响应往往是原始数据(例如 JSON、XML)，并且可以在没有支持模板的情况下生成。此外，注意清单 12-1 中的HttpResponse使用了content_type参数，该参数添加了 HTTP Content-Type application/json头，告诉请求方响应是 JSON。HTTP Content-Type 响应值很重要，因为它避免了消费者必须猜测如何处理 REST 服务响应(例如，另一个 Content-Type 选项可以是带有 XML 响应的 REST 服务的application/xml)。Django 视图方法的 HTTP 响应处理将在第二章中详细讨论。
(否)查询参数。-为了简单起见，清单 12-1 中的 view 方法没有参数，所以它提供了一个非常严格的输出(即所有存储都是 JSON 格式)。

Error: Is Not JSON/XML Serializable

在 Django 中创建 REST 服务时，最容易遇到的错误之一是“不是 JSON/XML 可序列化的”错误。这意味着 Django 不能将源数据序列化(即表示/转换)成所选择的格式——JSON 或 XML。当源数据由可能产生不确定或不明确的序列化结果的对象或数据类型组成时，会发生此错误。

比如你有一个Store带关系的模型类，Django 应该如何序列化这些关系？类似地，如果您有一个 Python datetime实例，Django 应该如何将值序列化为 DD/MM/YYYY、DD-MM-YYYY 或其他值？在任何情况下，Django 从不试图猜测序列化表示，所以除非源数据是自然可序列化的——如清单 12-1 所示——你必须显式指定一个序列化方案——我将在下面解释——否则你会得到“不是 JSON/XML 可序列化的”错误。

现在您已经对 Django 中的一个简单的 REST 服务有了一个简单的了解，让我们重新编写清单 12-1 中的 REST 服务，以利用参数，这样它就可以返回不同的数据结果和数据格式。

# urls.py (In stores app)
from coffeehouse.stores import views as stores_views

urlpatterns = [
    url(r'^rest/$',stores_views.rest_store,name="rest_index"),
    url(r'^(?P<store_id>\d+)/rest/$',stores_views.rest_store,name="rest_detail"),

]

# views.py (In stores app)
from django.http import HttpResponse
from coffeehouse.stores.models import Store

from django.core import serializers

def rest_store(request,store_id=None):
    store_list = Store.objects.all()
    if store_id:

        store_list = store_list.filter(id=store_id)
    if 'type' in request.GET and request.GET['type'] == 'xml':
        serialized_stores = serializers.serialize('xml',store_list)

        return HttpResponse(serialized_stores, content_type='application/xml')
    else:
        serialized_stores = serializers.serialize('json',store_list)

        return HttpResponse(serialized_stores, content_type='application/json')

Listing 12-2.Standard view method as REST service with parameters and different output formats

清单 12-2 中的第一个不同之处是一个额外的 url 语句，它接受带有store_id参数的请求(例如，/stores/1/rest/，/stores/2/rest/)。在这种情况下，新的 url 由相同的rest_store()视图方法处理，以处理来自清单 12-1 (即/stores/rest/)的商店索引

接下来，清单 12-2 中的视图方法是清单 12-1 中视图方法的修改版本，它接受一个store_id参数。这个修改允许 REST 服务处理所有商店(例如，/stores/rest/)或单个商店(例如，/stores/1/rest/的商店号1)的 url 请求。如果你不熟悉如何用参数设置 Django urls，请参阅第二章，其中描述了 url 参数。

一旦进入 view 方法，就会执行一个查询，从数据库中获取所有的Store记录。如果该方法接收到一个store_id值，将对查询应用一个额外的过滤器，以将结果限制在给定的store_id内。由于 Django 查询的工作方式，最后一个查询逻辑非常有效——如果您不熟悉 Django 查询的行为，请参见第八章“理解查询集”一节。

接下来，对request进行检查，看它是否具有带有xml值的type参数。如果一个请求匹配最后一个规则(例如/stores/rest/?type=xml，那么为 REST 服务生成一个 XML 响应；如果它不符合最后一条规则，那么将为 REST 服务生成一个 JSON 响应(默认)。

虽然清单 12-2 中的例子也使用了HttpResponse和content_type参数，就像清单 12-1 一样，但是请注意，数据是用 Django 的django.core.serializers包准备的，该包旨在使数据序列化更容易——不像清单 12-1 中的 REST 服务需要用清单理解预处理查询数据，然后使用 Python 的json包来完成这个过程。

清单 12-2 中django.core.serializers的使用非常简单。使用了serialize()方法，该方法期望将序列化类型作为其第一个参数(例如，'xml'或'json')，将要序列化的数据作为第二个参数(例如，表示查询的store_list引用)。在django.core.serializers package后面有更多的功能(例如过滤器)，为了简单起见，我不在这里探究，但是图 12-1 和 12-2 显示了来自清单 12-2 中 REST 服务的两个示例结果。

图 12-2。

XML output from Django REST service

图 12-1。

JSON output from Django REST serviceXML output from Django REST service

正如您在图 12-1 和 12-2 中看到的，Django 能够序列化一个查询，并以 JSON 或 XML 的形式将其结果输出为 REST 服务响应，只需清单 12-2 中的几行代码。清单 12-2 中的这几行代码可能会带您在 Django 中构建自己的 REST 服务，但是如果您从未做过 REST 服务或计划将 REST 服务作为应用或网站的核心，您应该停下来分析一下您的需求。

因为 REST 服务以一种简单且可重用的方式解决了一个常见的问题，所以它们容易受到范围蔓延的影响，这是一个变化似乎永无止境且功能总是“没有完全完成”的特征。看到这个最初的 Django REST 服务示例后，问自己以下问题:

您是否需要支持多个 Django 模型类型的 REST 服务？(例如，商店、饮料、员工)。
您需要将 JSON/XML 响应定制为不直接映射到 Django 模型记录的东西吗？(例如，使用自定义模式，过滤某些属性)。
是否需要为用户提供一个友好的界面，描述一个 REST 服务做什么，接受什么参数？
您是否需要支持某种身份验证机制，以便 REST 服务不公开可用？
您是否需要 REST 服务来支持不仅仅是显示数据或读取操作？(例如，更新和删除操作)？

如果你对前面的大部分问题回答是肯定的，那么你的 REST 服务已经超出了基本的范围。虽然您可以继续构建清单 12-2 中的例子——使用一个标准的 Django 视图方法和额外的 Python 包——来支持前面所有的场景，但是在 Django 中支持这些更复杂的 REST 服务特性是许多人以前走过的路，甚至有专门的框架来支持这个目的。

Django REST 框架 ³

Django REST 框架现在是它的第三个版本。与我刚才描述的从普通 Python/Django 包编写自己的 REST 服务相比，Django REST 框架提供了以下优势:

web 可浏览界面。-为所有 REST 服务提供用户友好的描述页面(例如，输入参数、选项)。类似于 Django admin 提供了一个几乎不费力的界面来查看 Django 项目的数据库，Django REST 框架为最终用户提供了一个几乎不费力的界面来发现 Django 项目的 REST 服务。
集成认证机制。-为了限制对 REST 服务的访问并节省集成认证逻辑的时间，Django REST 框架与 OAuth2、HTTP 签名、HTTP 摘要认证、JSON Web Token 认证和 HAWK (HTTP Holder-Of-Key 认证方案)等认证机制紧密集成。
更加灵活和复杂的序列化程序。-为了避免重新发明轮子和不断处理“不可序列化”的错误，Django REST 框架有自己的序列化器，用于处理复杂的数据关系。

这些只是使用 Django REST 框架的一些核心好处。如您所知，如果您计划创建多个 REST 服务，那么与使用普通 Python/Django 包处理部署 REST 服务所必需的搭建代码相比，花时间学习 Django REST 框架是非常值得的。

决哥打字框架

Django Tastypie 框架是作为 Django REST 框架的替代方案出现的。虽然 Django Tastypie 框架是 0.14 版本，但是不要让 1.0 之前的版本号欺骗了你:Django Tastypie 框架从 2010 年就开始开发了。虽然 Django Tastypie 框架和 Django REST 框架可能产生相同的结果，但是 Django Tastypie 框架有以下不同之处:

Tastypie 提供了更多的默认行为，使得配置和设置 REST 服务比使用 Django REST 框架更简单。

Tastypie 仍然是第二个最常用的 Django REST 包⁵——尽管它获得了 Django REST 框架一半的下载量——所以它仍然是许多 Django 项目的一个有吸引力的选择。

Tastypie 最初是由 Django haystack 的相同创建者开发的，Django haystack 仍然是最受欢迎的 Django 搜索包⁶——所以 Tastypie 在一些非常坚实的 Python/Django 基础上运行。

尽管 Django Tastypie 框架不像 Django REST 框架那样主流，但是如果您觉得用后者创建 REST 服务有些力不从心，您总是可以尝试前者以获得更快的 REST 解决方案，而不是用普通的 Python/Django 包从头开始构建您的 REST 服务。

Django REST 框架概念和介绍

Django REST 框架以标准 Python 包的形式发布。所以要开始，你需要用命令:pip install djangorestframework安装 Django REST 框架。

一旦安装了 Django REST 框架包，将它添加到 Django 项目的settings.py文件中的INSTALLED_APPS列表变量中，文件名为rest_framework。一旦完成，您就可以开始使用 Django REST 框架了。接下来，让我们使用 Django REST 框架来浏览 REST 服务的核心概念和创建过程。

序列化程序和视图

序列化器是 Django REST 框架的主要构建块之一，用于定义数据记录的表示，通常基于 Django 模型。如前一节 Django REST 服务选项介绍中所述，Python 记录可以有不明确的数据表示(例如，带有datetime值的记录可以表示为 DD/MM/YYYY、DD-MM-YYYY 或 MM-YYYY ),序列化程序消除了如何表示记录的任何不确定性。清单 12-3 展示了一个使用其serializers包之一的 Django REST 框架序列化程序。

# coffeehouse.stores.serializers.py file
from rest_framework import serializers

class StoreSerializer(serializers.Serializer):
    name = serializers.CharField(max_length=200)
    email = serializers.EmailField()

Listing 12-3.Serializer class based on Django REST framework

正如你在清单 12-3 中看到的，Django REST 框架序列化器是一个标准的 Python 类，在这种情况下，它从 Django REST 框架的serializers.Serializer类继承了它的行为。接下来，在 serializer 类中有一组字段，它们使用来自同一个 Django REST 框架的serializers包的数据类型。请注意这个 Django REST 框架序列化程序类和 Django 模型类或 Django 表单类之间的相似结构(即，它们从父类继承它们的行为，并使用不同的字段来表示不同的数据类型，如字符和电子邮件字段)。

清单 12-3 中的例子是最简单的 Django REST 框架序列化类之一，因为它只有两个字段，并且从最基本的serializers.Serializer类继承了它的行为。但是就像 Django 模型和表单一样，随着 Django REST 框架的发展，您会发现自己使用了更高级的数据类型，并且使用比serializers.Serializer更复杂的基类创建了序列化器。我将很快描述一个更高级的串行化器。接下来让我们在 Django REST 框架的上下文中探索一个视图。

序列化程序类本身什么也不做，必须与完成大部分 REST 服务逻辑(即处理传入请求、查询数据库中的数据)的视图集成，然后使用序列化程序来转换数据。在本章的第一节中，您了解了如何将一个常规的 Django 视图方法转换成 REST 服务。虽然完全可以在常规的 Django 视图方法中使用 Django REST 框架序列化程序类——如清单 12-3 所示——但是 Django REST 框架还提供了一个额外的视图语法——如清单 12-4 所示——以使构建 REST 服务变得更加容易。

from coffeehouse.stores.models import Store
from coffeehouse.stores.serializers import StoreSerializer

from rest_framework.decorators import api_view
from rest_framework.response import Response

@api_view(['GET','POST','DELETE'])
def rest_store(request):
    if request.method == 'GET':
        stores = Store.objects.all()
        serializer = StoreSerializer(stores, many=True)
        return Response(serializer.data)
    elif request.method == 'POST':
        ... #logic for HTTP POST  operation
    elif request.method == 'DELETE':
        ... #logic for HTTP DELETE operation

Listing 12-4.Django view method decorated with Django REST framework

首先注意清单 12-4 中的方法是一个常规的 Django 视图方法，但是它使用了 Django REST 框架中的@api_view装饰器。@api_view的参数指示支持哪些 HTTP REST 方法——参见第二章或第六章了解 Django 或维基百科 REST 条目中 HTTP 方法主题的详细信息， ⁷ 因为 HTTP 方法是一个通用的 REST 概念，而不是 Django/REST 主题。接下来，在视图方法内部，执行一系列条件来处理构成 REST 服务的不同 HTTP 请求方法。

如果在 view 方法上发出 GET 请求，就会发出一个查询来获取所有的Store模型记录。然而，注意在清单 12-4 的例子中，它使用清单 12-3 中的StoreSerializer来转换 Django queryset。此外，return语句使用 Django REST 框架Response方法，而不是 Django 的标准HttpResponse或render方法。

更重要的是，注意清单 12-4 中的请求和响应逻辑都没有任何 REST 输出格式(例如 JSON、XML)。通过利用 Django REST 框架，您不再需要处理检测或处理输出格式的底层细节——这由 REST 框架直接负责，并且基于您如何向 REST 服务发出请求，我将很快对此进行描述。

接下来，清单 12-4 中的rest_store()视图方法必须被配置成可以通过 url 访问。添加到应用的urls.py文件中的一行类似于url(r'^rest/$',stores_views.rest_store,name="rest_index")的代码解决了这个问题。一旦你这样做了，如果你访问这个 URL，你会看到如图 12-3 所示的结果。

图 12-3。

Django REST framework main service response Caution

如果你得到的是错误'TemplateDoesNotExist at /stores/rest/ rest_framework/api.html'而不是图 12-3 中的页面，这意味着你没有将 REST 框架添加到你的项目的INSTALLED_APPS中，如本节开始所述(例如INSTALLED_APPS = ['rest_framework'])。

正如你在图 12-3 中看到的，REST 框架服务响应与 Django 的基本HttpResponse响应相比，信息非常丰富，非常漂亮，而 Django 的基本HttpResponse响应是由本章开始部分创建的 Django REST 服务生成的。

例如，您可以看到 REST 服务提供的不同选项，并通过几次点击来调用它的各种操作。还要注意，由于清单 12-3 中的StoreSerializer定义，REST 服务的输出只有带有两个字段的Store对象。接下来，让我们修改序列化程序类来输出完整的Store记录。清单 12-5 展示了一个基于清单 12-3 的更新后的序列化器类。

from rest_framework import serializers

from coffeehouse.stores.models import Store

class StoreSerializer(serializers.ModelSerializer):
    class Meta:
        model = Store
        fields = '__all__'

Listing 12-5.Serializer class using Django model based on Django REST framework

为了序列化基于 Django Store模型的完整Store记录，清单 12-5 利用 Django REST 框架ModelSerializer类来简化序列化器语法。更重要的是，注意清单 12-5 中的 REST 框架StoreSerializer类如何使用与 Django 模型表单相同的语法，这些表单也是基于 Django 模型的。

在这种情况下，StoreSerializer类使用一个Meta类，其中model选项设置为Store以指定要序列化的 Django 模型，而fields选项设置为__all__以指示所有模型字段都应该序列化——注意,fields选项同样可以声明一个有限的模型字段名称列表，就像在模型表单中所做的那样。

有了清单 12-5 中的这个更加专门化的父序列化器ModelSerializer类——与清单 12-3 中的通用Serializer类相比——使用 Django REST 框架序列化用于 REST 服务的 Django 模型类就是这么简单。

但是，尽管这些 Django REST 框架序列化特性非常强大，而且清单 12-4 中使用的 Django REST 框架视图语法非常有用——减少了底层逻辑并提供了一个用户友好的界面——但是在视图方法中仍然有许多脚手架代码可以进一步削减。

为了进一步简化 REST 服务的构造，Django REST 框架可以利用基于类的视图。

基于类的视图

第二章介绍了 Django 基于类的视图的概念，第八章用基于类的视图扩展了这个主题，这些视图使用 Django 模型来执行 CRUD 操作。因为在 Django 中已经介绍了基于类的视图的原理，所以我假设您对这个主题有一个最低的熟悉程度；如果没有，那么回到其他章节学习基础知识。

清单 12-6 展示了一个基于 REST 框架类的基于类的视图，它简化了早期的标准视图方法——在清单 12-4 中——用 REST 框架中的@api_view修饰。

from coffeehouse.stores.models import Store
from coffeehouse.stores.serializers import StoreSerializer

from rest_framework.views import APIView
from rest_framework.response import Response

class StoreList(APIView):

    def get(self, request, format=None):
        stores = Store.objects.all()
        serializer = StoreSerializer(stores, many=True)
        return Response(serializer.data)

    def post(self, request, format=None):
        ...
        #logic for HTTP POST operation

    def delete(self, request, format=None):
        ...
        #logic for HTTP DELETE operation

Listing 12-6.Django REST framework class-based views

注意清单 12-6 中的类是如何从 Django REST 框架APIView类继承其行为的。这使得该类可以包含代表每个 REST 服务的 HTTP 方法(即 GET、POST、DELETE)的各种方法，类似于处理多个 HTTP 方法(如表单处理)的标准 Django 基于类的视图。

正如您所看到的，与清单 12-4 中的常规 Django 视图方法相比，清单 12-6 产生了更具可读性的 REST 服务逻辑，后者要求您手动检查请求并执行条件语句。清单 12-6 中的get方法内部的逻辑使用了与清单 12-4 中相同的 Django REST 框架语法，所以没有什么新的东西。

同样，您必须将一个常规的 Django 视图方法连接到一个 url，您还必须关联一个 Django REST 框架的基于类的视图，以便在某个 url 上可以访问它。清单 12-7 展示了一个urls.py文件，它具有从清单 12-6 中访问 REST 服务基于类的视图的语法。

from django.conf.urls import url
from coffeehouse.store import stores_views

urlpatterns = [
    url(r'^$',stores_views.index,name="index"),
    url(r'^rest/$',stores_views.StoreList.as_view(),name="rest_index"),    ]

Listing 12-7.Django URL definition linked to Django REST framework class-based views

在清单 12-7 中，您可以看到urls.py文件使用as_view()方法声明了r'^rest/$' url 模式被映射到 Django REST 框架StoreList类，这是所有基于 Django 类的视图将它们链接到 url 的主要方式。以这种方式，如果在/stores/rest/ url 上发出 HTTP GET 请求，则由基于类的视图的get()方法处理，如果在同一/stores/rest/上发出 HTTP POST 请求，则由基于类的视图的post()方法处理。

值得一提的是，点击清单 12-6 中由 REST 框架基于类的视图支持的 url 也会产生如图 12-3 所示的相同界面，这是由清单 12-4 中的标准视图方法产生的。

现在，尽管 REST 框架基于类的视图有助于简化 REST 服务逻辑，但基于类的视图仍然需要您编写每个方法背后的所有逻辑。例如，在清单 12-6 中的get()方法中，执行一个查询来获取所有Store记录，然后序列化数据，最后返回一个响应。对于清单 12-6 中的post()方法，您同样需要用提供的数据插入/更新一个Store记录，而对于delete()方法，您需要用提供的数据删除一个Store记录。

一旦您用 Django REST 框架编写了几个基于类的视图，您就会意识到每种类型的视图方法背后都有一个固定的模式(例如，读取一个记录，序列化它，并返回一个响应)。除此之外，您还将认识到 REST 方法(例如 GET、POST 和 DELETE)和它们在 Django 模型上执行的操作(例如创建-读取-更新-删除(CRUD)操作)之间的密切关系。

为了避免为与 REST 服务相关联的不同 Django 对象不断编写相同的 CRUD 操作和样板逻辑，遵循 Django 的 DRY(不要重复自己)原则和 Django 的基于类的模型视图原则的 Django REST 框架提供了另一种构造:mixins。

混合和通用的基于类的视图

mixin 用于封装和重用相同的逻辑，并且能够在基于类的视图中使用它。例如，不是编写清单 12-6 中的相同逻辑——获取所有记录，序列化它们，并生成一个响应——针对不同的 REST 服务(例如，Item、Drink,或Store服务)反复进行；可以使用mixins.ListModelMixin类，快速达到同样的效果。

我不会在这里更详细地介绍 mixin 类，主要是因为 mixin 类不像其他 Django REST 框架选项那样被广泛使用，更不用说 Django mixins 已经在第九章使用模型的基于类的视图中描述过了。

对于大多数 Django framework REST 服务，要么使用基于类的视图——以获得对逻辑的完全控制——要么使用基于 mixins 的更简洁的方法，称为“混合通用类视图”。清单 12-8 基于清单 12-6 中基于类的视图展示了一个等价的混合通用类视图。

from coffeehouse.stores.models import Store
from coffeehouse.stores.serializers import StoreSerializer

from rest_framework import generics

class StoreList(generics.ListCreateAPIView):
    queryset = Store.objects.all()
    serializer_class = StoreSerializer

Listing 12-8.Django mixed-in generic class views in Django REST framework

注意清单 12-8 甚至比之前相同 REST 服务的迭代更加简洁。在这种情况下，通用类名ListCreateAPIView表明了该类产生了什么——基于指定获取所有Store记录的queryset选项和指向清单 12-5 中的StoreSerializer类的serializer选项，生成一个列表的 REST 视图。

就像以前一样，即使您现在有一个由几行代码组成的 REST 服务，Django REST 框架也可以通过使用视图集和路由器来进一步扩展 Django 的 DRY 原则。

查看集合和路由器

清单 12-8 中的通用类视图对于仅仅三行代码来说已经非常强大了，但是它只是一个显示Store记录列表的类。假设您现在需要创建一个 REST 服务来显示特定的Store记录，创建另一个 REST 服务来更新Store记录，创建另一个 REST 服务来删除Store记录。在这种情况下，您将需要再创建三个通用类视图和三个 URL 映射来推出这个基本的 CRUD 功能。但是您可以依赖 Django REST 框架视图集，而不是为每种情况创建单独的视图类。

Django REST 框架视图集，顾名思义，就是一组视图。要创建 Django REST 框架视图集，您需要做的就是创建一个类，该类继承了 Django REST 框架中用于此目的的一个类的行为。清单 12-9 展示了用ModelViewSet类创建的视图集。

from coffeehouse.stores.models import Store
from coffeehouse.stores.serializers import StoreSerializer

from rest_framework import viewsets

class StoreViewSet(viewsets.ModelViewSet):
    queryset = Store.objects.all()
    serializer_class = StoreSerializer

Listing 12-9.Django viewset class in Django REST framework

清单 12-9 和清单 12-8 中的 REST 服务类一样短，但是除了类名的变化，父类ModelViewSet继承的类给了这个 REST 服务一个全新的维度。单独使用这个类，REST 服务会自动显示一个Store记录列表，以及创建、读取、更新或删除单个Store记录。

因为一个视图集生成多个视图，所以仍然需要将每个视图配置到一个 url，在这种情况下，最简单的方法是使用 Django REST 框架路由器。路由器对于视图集就像 url 语句对于基于类的视图一样:一种连接端点的方式。清单 12-10 展示了用 Django REST 框架路由器设置的urls.py文件。

from django.conf.urls import include, url
from coffeehouse.stores import views as stores_views

from rest_framework import routers

router = routers.DefaultRouter()
router.register(r'stores', stores_views.StoreViewSet)

urlpatterns = [
    url(r'^rest/', include(router.urls,namespace="rest")),
    ]

Listing 12-10.Django URL definition with Django REST framework router for view set

Caution

视图集和路由器的组合会自动创建敏感的 REST 端点(例如，删除和更新)，默认情况下，任何人都可以访问这些端点。参见下一节 REST 框架安全性来限制这些服务端点。

清单 12-10 中的第一步是用routers.DefaultRouter()初始化一个路由器，然后用它注册不同的视图集。正如您在清单 12-10 中看到的，router注册过程使用了接受两个参数的router.register方法:第一个参数表示 REST url 前缀——在本例中为stores——第二个参数指定视图集——在本例中为清单 12-9 中的StoreViewSet类。

接下来，你可以看到router是使用 Django 的标准url和include方法赋值的。在这种情况下，路由器实例被分配在r'^rest/' url 下，这意味着Store视图集的最终根 url 变成了/rest/stores/，如图 12-4 所示。

图 12-4。

Django REST framework view set main page

如图 12-4 所示，REST 框架呈现了一个默认的 Api 根页面。您可以进一步导航到 Api 根页面下的其他 URL(即/stores/rest/)来执行与视图集相关联的其他 CRUD 操作(例如，对/stores/rest/stores/的 HTTP GET 请求以获取所有Store记录的列表，对/stores/rest/stores/1/的 HTTP GET 请求以获取带有id=1,的Store记录，或者对/stores/rest/stores/2/的 HTTP DELETE 请求以删除带有id=3的Store记录)。

通过对视图集和路由器的描述，我们总结了用 Django REST 框架建立 REST 服务所需的基本概念。现在您已经熟悉了基础知识，在下一节中，您将学习如何保护用 Django REST 框架构建的 REST 服务。

Django REST 框架安全性

虽然 Django REST 框架为创建允许访问应用数据的 REST 服务节省了大量时间，但是您需要小心不要无意中允许访问数据或功能。对 Django REST 框架使用错误的类或配置参数会使您的应用面临安全风险，尽管 Django REST 框架从根本上来说是安全的。

设置 REST 框架服务权限

默认情况下，所有 REST 框架服务都对任何人开放，只要他们知道或发现一个 REST 服务端点(即 url)。虽然这种默认行为很方便，但它也可能是一个严重的安全威胁，特别是当您创建带有敏感操作(例如，更新或删除操作)或视图集的 REST 框架服务时——比如清单 12-9 中的视图集——它们会自动创建支持敏感操作的端点。

默认的 REST 框架权限可以通过setting.py文件中的REST_FRAMEWORK变量，通过DEFAULT_PERMISSION_CLASSES选项来配置。开箱即用，REST 框架将该选项设置为使用rest_framework.permissions.AllowAny类，如下面的代码片段所示:

REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.AllowAny',
    )
}

这意味着除非您在 Django 项目的settings.py文件中定义了一个DEFAULT_PERMISSION_CLASSES选项，否则所有的 REST 框架服务都是对公众开放的。为了禁止公众访问 REST 服务，您可以更改 REST 框架的默认权限策略。

清单 12-11 展示了设置为rest_framework.permissions.IsAuthenticated类的DEFAULT_PERMISSION_CLASSES选项，它强制规定只有通过 Django 的内置用户系统登录的用户——在第十章中描述——才被允许访问 REST 框架服务。

REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated',
    )
}
Listing 12-11.Django REST framework set to restrict all services to authenticated users

除了rest_framework.permissions.IsAuthenticated类，REST 框架还支持表 12-1 中的类成为DEFAULT_PERMISSION_CLASSES选项的一部分。

表 12-1。

Django REST framework permission classes

| REST 框架权限类 | 描述 | | --- | --- | | rest _ framework . permissions . allow any | (默认)允许任何人访问。 | | rest _ framework . permissions . is 已验证 | 允许通过 Django 的内置用户系统访问登录的用户。 | | rest _ framework . permissions . isadminuser | 基于 Django 的内置用户系统，允许访问 Django 管理员用户。 | | rest _ framework . permissions . isauthenticedorreadonly | 允许任何人(无论是否登录)进行读取访问，但需要登录才能执行非读取操作。 | | rest _ framework . permissions . djangodelpermissions | 允许登录用户访问，但也要求所述用户具有必要的添加/更改/删除模型权限，REST 服务可以在这些权限上操作。 | | rest _ framework . permissions . djangodelpermissionsoranonreadonly | 就像 DjangoModelPermissions 类一样，但是允许任何人(无论是否登录)进行读取访问。 | | rest _ framework . permissions . djangobjectpermissions | 类似于 DjangoModelPermissions 类，除了它在 REST 服务操作的模型上处理每个对象的权限。 |

如表 12-1 所示，REST 框架提供了各种类来设置项目中所有 REST 服务的默认访问权限。例如，如果您允许公共读取访问项目的 REST 服务，但是想要限制更敏感的 REST 服务操作，那么表 12-1 中的IsAuthenticatedOrReadOnly和DjangoModelPermissionsOrAnonReadOnly类是DEFAULT_PERMISSION_CLASSES选项的很好的替代。

尽管如此，通过依赖于DEFAULT_PERMISSION_CLASSES选项，您给了项目中的每个 REST 服务相同的访问权限。如果想为一两个服务提供更灵活或更严格的权限策略呢？REST 框架还支持在单个 REST 服务上指定更细粒度的权限，使用表 12-1 中的相同类。

清单 12-12 展示了清单 12-4 中 REST 服务的一个修改版本，它使用@permission_classes decorator 来指定一个不同于全局DEFAULT_PERMISSION_CLASSES选项的权限策略。

from coffeehouse.stores.models import Store
from coffeehouse.stores.serializers import StoreSerializer

from rest_framework.decorators import api_view, permission_classes

from rest_framework.permissions import IsAuthenticated

from rest_framework.response import Response

@api_view(['GET','POST','DELETE'])

@permission_classes((IsAuthenticated, ))

def rest_store(request):
    if request.method == 'GET':
        stores = Store.objects.all()
        serializer = StoreSerializer(stores, many=True)
        return Response(serializer.data)

Listing 12-12.Django view method decorated with Django REST framework and @permission_classes decorator

在清单 12-12 中可以看到，标准视图方法除了用@api_view修饰外，还用@permission_classes修饰。在这种情况下，@permission_classes装饰器被设置为IsAuthenticated类值，确保这个 REST 服务权限策略优先于DEFAULT_PERMISSION_CLASSES选项中的默认服务权限。

清单 12-13 展示了清单 12-9 中 REST 服务的一个修改版本，它使用 permission_classes 字段来指定一个不同于全局DEFAULT_PERMISSION_CLASSES选项的权限策略。

from coffeehouse.stores.models import Store
from coffeehouse.stores.serializers import StoreSerializer

from rest_framework.permissions import IsAuthenticated

from rest_framework import viewsets

class StoreViewSet(viewsets.ModelViewSet):
    permission_classes = (IsAuthenticated,)

    queryset = Store.objects.all()
    serializer_class = StoreSerializer

Listing 12-13.Django viewset class in Django REST framework and permission_classes field

正如您在清单 12-13 中看到的，REST 框架视图集方法利用了permission_classes字段。在这种情况下，permission_classes字段用IsAuthenticated类值设置，确保这个 REST 服务权限策略优先于DEFAULT_PERMISSION_CLASSES选项中的默认服务权限。

设置 REST 框架登录页面

默认情况下，如果用户试图通过浏览器访问 REST 框架，并且没有必要的权限，那么用户会看到一个警告页面，如图 12-5 所示。

图 12-5。

Django REST framework access denied page

尽管图 12-5 代表了一个标准的拒绝访问页面，但它有一个明显的遗漏:这是一个没有链接让用户登录的死胡同。如果用户到达图 12-5 中的页面，他需要手动进入应用或 Django 管理中的 Django 登录页面，提供他的凭证，然后返回 REST 服务来访问它。

最后一个工作流给用户造成了不必要的负担，这就是为什么 REST 框架提供了一种集成登录页面的简单方法——包括所有页面上的登录/注销链接——它直接绑定到 Django admin 的相同认证后端。

清单 12-14 展示了 Django 项目的 main urls.py，它声明了 REST 框架的 URL 以自动激活其内置的登录页面和链接。

from django.conf.urls import include, url
urlpatterns = [
    url(r'^rest-auth/', include('rest_framework.urls',namespace='rest_framework')),
]
Listing 12-14.Django REST framework url declaration

to enable log in

在清单 12-14 中，你可以看到rest_framework.urls配置了 Django 的标准include()语句和namespace参数，此外还配置了rest-auth/ url，最后一个可以更改为你选择的任何 url 模式。

通过添加到 Django 项目的主urls.py文件中，所有 REST 框架页面都在右上角生成了一个登录链接，该链接将用户带到 url 配置的登录路径下的一个可访问的登录页面(例如，如果是url(r'^rest-auth/')，则登录页面在/rest-auth/login/可用)。

Enhanced Rest Framework User Interface Options

尽管 REST 框架提供的内置用户界面(UI)提供了比呈现原始数据 REST 服务输出更好的选择，如图 12-3 到 12-5 所示，如图 12-1 和 12-2 所示，但与更现代的 UI web 布局相比，REST 框架 UI 仍然相当初级。

REST 框架 UI 有多种替代方式，它们是专门为使用 REST 框架而设计的。一些比较成熟的项目包括 Django REST Swagger⁸和 DRF Docs。 ⁹

Footnotes 1

https://en.wikipedia.org/wiki/Representational_state_transfer

https://www.ampproject.org/

http://www.django-rest-framework.org/

http://tastypieapi.org/

https://djangopackages.org/grids/g/rest/

https://djangopackages.org/grids/g/search/

https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods

http://marcgibbons.github.io/django-rest-swagger/

http://drfdocs.com/

posted @ 2024-08-13 14:27 绝不原创的飞龙阅读(104) 评论(0) 收藏举报

刷新页面返回顶部

龙哥盟

掠夺·扩张·投机·博弈

Django-入门指南-全-

Django 入门指南（全）

一、Django 框架介绍

Django 框架设计原则

不重复自己(干)的原则

显性比隐性好

松散耦合架构

安装 Django

安装 Python(先决条件)

更新或安装 pip 软件包管理器(先决条件)

安装 virtualenv(可选先决条件)

安装 Django

从 Git 安装 Django

启动 Django 项目

为 Django 项目建立数据库

安装 Python 数据库包

测试 Django 数据库连接并构建 Django 基表

设置内容:了解 URL、模板和应用

创建和配置 Django Urls

创建和配置 Django 模板

创建和配置 Django 应用

设置 Django 管理站点

配置并安装 Django 管理站点应用

配置并安装 Django 管理站点文档应用

二、Django Url 和视图

Url 正则表达式

优先规则:粒度 URL 优先，广义 URL 最后

精确 Url 模式:放弃广泛匹配

常见 Url 模式

Url 参数、额外选项和查询字符串

Url 整合和模块化

Url 命名和名称空间

查看方法请求

查看方法响应

HTTP 状态和内容类型标头的响应选项

常见 HTTP 状态的内置响应快捷方式和模板:404(未找到)、500(内部服务器错误)、400(错误请求)和 403(禁止)

内联和流式内容的内置响应快捷方式

请求看起来不对劲

Ups，我们找不到那个页面

方法不允许使用

Ups，这是我们的失误，抱歉！

Django 内联响应

视图方法中间件

内置中间件类

中间件结构和执行过程

查看方法中的中间件 Flash 消息

添加即时消息

访问即时消息

基于类的视图

内置的基于类的视图

基于类的视图结构和执行

三、Django 模板

Django 模板语法

自动转义:HTML 和安全方面的错误

Django 模板配置

模板搜索路径

无效的模板变量

调试输出

自动退出

文件字符集

自动访问定制模板标签/过滤器模块

模板加载器

创建可重复使用的模板

内置上下文处理器

Django 调试上下文处理器(django . template . context _ processors . debug)

Django 请求上下文处理器(django . template . context _ processors . request)

Django 授权上下文处理器(django . contrib . auth . context _ processors . auth)

Django 消息上下文处理器(django . contrib . messages . context _ processors . messages)

其他内置的 Django 上下文处理器:i18n、媒体、静态、tz 和 CSRF 上下文处理器

Django i18n 上下文处理器(django . template . context _ processors . i18n)

Django 媒体上下文处理器(django . template . context _ processors . media)

Django 静态上下文处理器(django . template . context _ processors . static)

Django tz 上下文处理器(django . template . context _ processors . tz)

Django CSRF 上下文处理器(django . template . context _ processors . csrf)

自定义上下文处理器

内置 Django 过滤器

日期

字符串、列表和数字