Skip to content

9. 分层架构与数据访问

前面的示例把数据保存在内存中。真实的应用会把数据存放在数据库中,并按层来组织(参见引言中的示意图):

  • Web 层(视图、表单、模板):读取请求,调用业务层,选择模板;
  • 业务层:业务规则;
  • DAO 层(Data Access Object,数据访问对象):数据库查询。

每一层只了解它下面的那一层,并且尽可能少地了解其细节:Web 层不知道查询,业务层不知道 HTML。这种分离使每一层都更易于理解、测试和演进。示例 28 把这一做法应用于人员列表的管理:它是案例研究中医生和客户管理的缩小版。

在 [Python] 中,数据库访问分为多个层次:

  • [Python] 的 DB-API 2.0 标准(PEP 249)为所有 SGBD 定义了统一的接口:打开连接、获取游标、执行 SQL 命令、读取行。每种 SGBD 都有自己的驱动:对于 [MySQL] (以及 [MariaDB]),[Django] 推荐 [mysqlclient],这是一个用 C 编写的库,由示例文件 [requirements.txt] 安装;
  • [Django] 的 ORM(Object-Relational Mapper,对象关系映射器)把类(模型)映射到数据库表,并把读取到的行转换为对象。它管理连接和事务,自己生成适合各个 SGBD 的 SQL 命令,并把各驱动的错误转换为通用异常(违反唯一性约束时,无论使用哪种 SGBD,都会变成 [IntegrityError])。它遵循所谓的 Active Record 模式:每个对象都知道如何保存自己([person.save()])和删除自己([person.delete()]),每个类都有一个管理器([Person.objects]),查询由它发出。[Eloquent],即 [Laravel] 的 ORM,就是以此为模型;而 [Doctrine],即源自 [Symfony] 的 ORM,则遵循 Data Mapper 模式,由一个独立的对象来读取和保存实体。

[Django] 的 ORM 是 [Django] 的一部分,也是其关键组件之一:管理界面、身份验证应用、数据库会话和通用视图都依赖于它。它相当于 [Java] 中的 [JPA] 和 [Hibernate],[C#] 中的 [Entity Framework Core],或者 [Python] 中(与 [Flask] 搭配使用的)[SQLAlchemy]。请注意 [Django] 工作方式的一个后果:默认情况下,每个请求都会打开自己的数据库连接(在其第一条 SQL 请求时),并在结束时关闭它(在 [request_finished] 信号触发时,示例 24)。[CONN_MAX_AGE] 设置允许连接在请求之间保持打开(持久连接),而 [Django] 5.1 为 [PostgreSQL] 增加了真正的连接池。在同一台机器上打开到 [MySQL] 的连接只需要几毫秒。

此示例需要一个正在运行的 [MySQL] 8.4 或更高版本的服务器(或 [MariaDB] 10.11 或更高版本;这些是 [Django] 6.1 要求的最低版本):附录说明了如何使用 [Laragon] 安装。

9.1. 示例 28:三层架构的人员管理系统

28-layers/
├── config/
│   ├── middleware.py
│   ├── rendering.py
│   ├── settings.py
│   ├── urls.py
│   └── ...
├── database/
│   └── dbpersons.sql
├── persons/
│   ├── __init__.py
│   ├── business.py
│   ├── dao.py
│   ├── forms.py
│   ├── models.py
│   ├── urls.py
│   └── views.py
├── static/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── templates/
│   ├── forms/
│   │   └── field.html
│   ├── fragments/
│   │   └── confirmation.html
│   ├── persons/
│   │   ├── form.html
│   │   └── list.html
│   └── layout.html
└── manage.py

9.1.1. 数据库

[dbpersons] 数据库由 SQL 脚本创建。使用 [Laragon] 时,可以在 [HeidiSQL] 工具中运行它(文件菜单 / 运行 SQL 文件),也可以在示例文件夹中通过命令行运行:

mysql -u root < database/dbpersons.sql

[database/dbpersons.sql] 文件:

-- database of example 28: a single table, [persons]
-- the script is written in UTF-8
SET NAMES utf8mb4;
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;

CREATE TABLE persons (
  id INT NOT NULL AUTO_INCREMENT,
  -- the version of the row, increased at each modification (see DAO layer)
  version INT NOT NULL DEFAULT 0,
  first_name VARCHAR(30) NOT NULL,
  last_name VARCHAR(30) NOT NULL,
  age INT NOT NULL,
  PRIMARY KEY (id),
  -- two persons cannot have the same first and last names
  CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;

INSERT INTO persons (first_name, last_name, age) VALUES
  ('Marie', 'Pélissier', 42),
  ('Jacques', 'Bromard', 35),
  ('Philippe', 'Jandot', 58);
  • 第 3 行:脚本以 [UTF-8] 编写;这一点要告知服务器,使数据中的重音符号([Pélissier])保持完好;
  • 第 5 行:字符集 [utf8mb4] 接受所有字符(重音符号、表情符号等)。排序规则 [utf8mb4_unicode_ci] 比较字符串时不区分大小写和重音:对于 [MySQL],[pelissier], 和 [Pélissier] 是相等的;
  • 第 11 行:版本号,每次修改该行时递增(参见下文的“乐观锁”);
  • 第 17 行:一个具名的唯一性约束:数据库不允许两个人拥有相同的名和姓。

[Django] 也可以根据模式(schema),通过迁移自己创建表:[Python] 文件,逐步描述每张表的创建和修改。[python manage.py makemigrations] 命令通过比较模式与之前迁移所描述的状态来编写这些文件;[python manage.py migrate] 把它们应用到数据库。这是使用 [Django] 的标准工作方式。我们维护一个 SQL 脚本,它为案例研究的所有版本所共用,能准确展示数据库中包含的内容。反过来,命令 [python manage.py inspectdb] 可以为现有数据库写出模式:这是一个很好的起点,值得仔细检查。

9.1.2. 配置:config/settings.py

# config/settings.py:示例 28 的配置

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure--7xp)7k(l6nl(owyoe0r99a@hufm3z2t@a(@w+va%5uw^%fbbm"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "django.contrib.messages",
    "django.forms",
    "persons",
]

MIDDLEWARE = [
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    # 通过隐藏的 _method 字段实现 PUT 和 DELETE(见示例 21)
    "config.middleware.MethodOverride",
]

MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"

# 数据库:MySQL 数据库管理系统,位于本机(127.0.0.1),端口 3306,
# dbpersons 数据库,root 用户,无密码(Laragon 的设置)
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "NAME": "dbpersons",
        "USER": "root",
        "PASSWORD": "",
        "HOST": "127.0.0.1",
        "PORT": "3306",
        "OPTIONS": {"charset": "utf8mb4"},
    },
}

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

FORM_RENDERER = "config.rendering.BootstrapRenderer"

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]

# 日志(logging):发送给数据库的 SQL 语句会写入控制台
# (django.db.backends 日志记录器只在调试模式下才输出它们)
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {
        "django.db.backends": {"handlers": ["console"], "level": "DEBUG"},
    },
}
  • 第 21–26 行:来自示例 21 的中间件:防 CSRF 保护、闪现消息,以及对 PUT 和 DELETE 方法的模拟(文件 [config/middleware.py] 就是示例 21 中的那个);
  • 第 32–42 行:[DATABASES] 配置描述应用程序的数据库:这里只有一个,即 [default] 数据库。[ENGINE] 指的是 [Django] 用于 [MySQL] 的引擎(它使用驱动 [mysqlclient]);后面依次是数据库名、用户名和密码(在 [Laragon] 的设置下留空:如果你的服务器设置了密码,请在此填写)、主机名和端口。[OPTIONS] 把与服务器通信所用的字符集(即数据库的字符集)传给驱动;
  • 第 44–55 行:模板,其中 [APP_DIRS] 用于表单模板(示例 18)和消息上下文处理器(示例 20);
  • 第 67–74 行:设置 [LOGGING] 配置 [Python] 的日志([logging] 模块),[Django] 用它来输出自己的消息。它遵循 [logging.config] 模块的格式:目的地([handlers]:这里是控制台,通过 [StreamHandler],它写入错误输出),以及日志记录器([loggers]),由名称标识。日志记录器 [django.db.backends] 仅在调试模式下接收发送到数据库的每条 SQL 命令及其耗时:我们把它以 [DEBUG] 级别(最详细的级别)输出到控制台。[disable_existing_loggers: False] 会保留 [Django] 自己配置的日志。

无需再配置其他任何内容:三层中的模块相互导入(Web 层导入业务层,业务层导入 DAO 层),而 ORM 层在需要时会自行建立到数据库的连接。

9.1.3. Person 模型:persons/models.py

# persons/models.py:[persons] 表的一行,一个 Django 模型

from django.db import models


# 一个 Django 模型:继承自 models.Model 的类;每个作为字段(models.XxxField)
# 的类属性对应表的一列
class Person(models.Model):
    # 主键,由数据库生成(AUTO_INCREMENT)
    id = models.AutoField(primary_key=True)
    # 该行的版本,每次修改时递增(见 DAO 层)
    version = models.IntegerField(default=0)
    # VARCHAR(30) 和 INT 列
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)
    age = models.IntegerField()

    # Meta:关于模型本身的信息
    class Meta:
        # 表的名称(默认:persons_person,即 应用_模型)
        db_table = "persons"
        # 该表已经存在(脚本 database/dbpersons.sql):Django 不会创建它
        managed = False
        # 查询未指定顺序时,行的顺序
        ordering = ["last_name", "first_name"]

    # 表示该对象的文本(在控制台、消息等处)
    def __str__(self):
        return f"{self.first_name} {self.last_name}"

该文件名为 [models.py]:[Django] 会在这里查找在 [INSTALLED_APPS] 中声明的应用程序的模型。

  • 第 8 行:模型是一个继承自 [models.Model] 的类;
  • 第 10 行:主键,由数据库生成([AutoField]:对应 [AUTO_INCREMENT] ,即 [MySQL] 的自增列)。如果没有声明,[Django] 会自动添加它(一个 [id] 字段,类型由设置 [DEFAULT_AUTO_FIELD] 选定);我们在这里显式写出以求清晰。在对象被插入之前,它等于 [None] ;
  • 第 12 行:行版本。[Django] 的 ORM 没有内置的乐观锁:它由 DAO 层编写(见下文);
  • 第 14–16 行:列。模型中每个属于字段的类属性([models.XxxField])对应一个同名的列;列的类型由字段类型推断得出([CharField]:[VARCHAR],长度为 [max_length];[IntegerField]:[INT])。与表单中一样(示例 08),字段被声明为类的属性,但它们并不是同一种字段:[django.db.models] 中的字段描述列,而 [django.forms] 中的字段描述表单字段;
  • 第 19–25 行:内部类 [Meta] 提供关于模型本身的信息。[db_table]:表名(否则 [Django] 会取应用名加上模型名,即 [persons_person])。[managed = False]:该表已经存在,[Django] 不管理它:[makemigrations] 不会为它生成任何创建或修改的迁移。[ordering]:查询未指定排序时行的顺序;
  • 第 28–29 行:方法 [__str__] (示例 12)返回表示该对象的文本:[str(p)],或 f-string 中的 [{p}] ,返回 [Marie Pélissier]。

模型是一个普通的类,可以为其添加方法和属性。而 ORM 会根据读取到的行填充其属性,并根据属性生成 SQL 命令。

9.1.4. DAO 层:persons/dao.py

# persons/dao.py:DAO 层,查询,不含业务规则

from django.db.models import F

from .models import Person


# SELECT ... FROM persons ORDER BY last_name, first_name。objects:模型的管理器,
# 所有查询都从它出发;all() 返回一个 QuerySet,这个查询只有在读取其结果时才
# 执行(这里是由 list 读取)
def list_all() -> list[Person]:
    return list(Person.objects.all())


# SELECT ... FROM persons WHERE id = ?;若该人员不存在则为 None
def read(id: int) -> Person | None:
    return Person.objects.filter(id=id).first()


# 与 [except_id] 不同、名和姓相同的人员。filter:WHERE
# 条件;exclude:WHERE NOT 条件
def namesake(first_name: str, last_name: str, except_id: int = 0) -> Person | None:
    return Person.objects.filter(first_name=first_name, last_name=last_name).exclude(id=except_id).first()


# INSERT INTO persons ...:create 构建对象并保存它
def insert(first_name: str, last_name: str, age: int) -> Person:
    return Person.objects.create(first_name=first_name, last_name=last_name, age=age)


# UPDATE persons SET ..., version = version + 1 WHERE id = ? AND version = ?:只有当
# 该行的版本自读取以来没有变化时才会修改它(乐观
# 锁)。F("version") 在 SQL 语句中指代列本身。update
# 返回被修改的行数:若版本已变化则为 0
def update(id: int, version: int, first_name: str, last_name: str, age: int) -> bool:
    rows = Person.objects.filter(id=id, version=version).update(
        first_name=first_name, last_name=last_name, age=age, version=F("version") + 1)
    return rows == 1


# DELETE FROM persons WHERE id = ?
def delete(person: Person) -> None:
    person.delete()

DAO 层只包含查询,不包含业务规则。每个函数都以 [Person.objects] 开头,它是模型管理器,所有查询都从它发出。

  • 第 11–12 行:[all()] 返回一个 [QuerySet]:一个只描述查询而不执行它的对象。只有在需要查询结果时(这里是 [list] 遍历结果时),查询才会发送到数据库:我们称 [QuerySet] 是惰性的。因此可以在执行之前逐步完善它([filter]、[exclude]、[order_by]……),每个方法都返回一个新的 [QuerySet]。排序依据 [Meta.ordering];
  • 第 16–17 行:[filter(id=id)] 添加条件 [WHERE id = ...];[first()] 执行查询,限制为一行([LIMIT 1]),并返回第一个对象,或者 [None]。([Person.objects.get(id=id)] 也会返回该对象,但如果它不存在,就会抛出异常 [Person.DoesNotExist] ,而快捷函数 [get_object_or_404](示例 03)则会返回 404 错误);
  • 第 22–23 行:[filter] 中的多个条件通过 [AND] 组合;[exclude] 添加一个 [NOT] 条件。命名参数指向字段([first_name=...]);后缀指定比较方式:[age__gte=18] ([>=])、[last_name__startswith="P"]、[last_name__iexact=...] (不区分大小写)……这些值与 SQL 语句分开传送给数据库,绝不会被复制到 SQL 语句的文本中,因此不可能发生 SQL 注入;
  • 第 27–28 行:[create] 构造对象并保存它([INSERT]);插入之后,ORM 会把数据库生成的 ID 存入该对象。这等价于 [p = Person(first_name=..., ...)] 再接 [p.save()];
  • 第 35–38 行:更新,带乐观锁。[update] 用一条 [QuerySet] 指定的所有行,通过一条 [UPDATE] 命令一次性更新,并返回被更新的行数。过滤器有两个条件:ID 和读取到的版本。如果在此期间另一个查询修改了该行,导致其版本发生变化,[UPDATE] 就不会修改任何行,函数返回 [False]。这就是乐观锁的原理:不锁定任何东西,但会检测到并发修改。表达式 [F("version") + 1] 在 SQL 语句中引用列本身([version = version + 1]):计算由数据库执行,而不是在 [Python] 中根据先前读取的值进行;
  • 第 42–43 行:删除:[delete()] 针对该对象所对应的行发出 [DELETE] 。

与 [Doctrine] 不同,[Django] 的 ORM 没有一个管理器来把每个读取到的对象与其原始状态比较,从而只保存被修改的列:[save()] 会重写对象的所有列(或其参数 [update_fields] 所指定的列)。这更简单,也更可预测;[update] 则允许你精确地写出所需的语句。

9.1.5. 业务层:persons/business.py

# persons/business.py:业务层,只含业务规则。
# 每个写操作都是一个事务:若函数正常结束则提交(COMMIT),
# 若有异常抛出则取消(ROLLBACK)

from dataclasses import dataclass

from django.db import IntegrityError, transaction

from . import dao
from .models import Person

NAMESAKE = "A person already has these first and last names."
MODIFIED = "This record has been modified meanwhile: reload it."
UNKNOWN = "This person does not exist (anymore)."


# 某条业务规则拒绝该操作;消息是给用户看的
class BusinessError(Exception):
    pass


# 一个人员的数据,由 Web 层传入
@dataclass(frozen=True)
class PersonData:
    first_name: str
    last_name: str
    age: int


def list_all() -> list[Person]:
    return dao.list_all()


def read(id: int) -> Person:
    person = dao.read(id)
    if person is None:
        raise BusinessError(UNKNOWN)
    return person


# with transaction.atomic():该代码块在事务中执行。数据库的唯一性
# 约束(两个同时进行的添加)会抛出 IntegrityError,它会变成
# 业务错误
def add(data: PersonData) -> Person:
    try:
        with transaction.atomic():
            # 规则 1:不允许有两个名和姓相同的人员
            if dao.namesake(data.first_name, data.last_name):
                raise BusinessError(NAMESAKE)
            return dao.insert(data.first_name, data.last_name, data.age)
    except IntegrityError as e:
        raise BusinessError(NAMESAKE) from e


def update(id: int, version: int, data: PersonData) -> Person:
    try:
        with transaction.atomic():
            person = read(id)
            # 规则 2:期间被他人修改过的记录不会被修改
            if person.version != version:
                raise BusinessError(MODIFIED)
            if dao.namesake(data.first_name, data.last_name, id):
                raise BusinessError(NAMESAKE)
            # 若另一个请求在我们读取之后修改了该行,
            # 则 UPDATE ... WHERE version = ... 不会修改任何内容
            if not dao.update(id, version, data.first_name, data.last_name, data.age):
                raise BusinessError(MODIFIED)
            return read(id)
    except IntegrityError as e:
        raise BusinessError(NAMESAKE) from e


def delete(id: int) -> Person:
    with transaction.atomic():
        person = read(id)
        dao.delete(person)
        return person
  • 第 12–14 行:业务规则的消息;
  • 第 18–19 行:业务层专用的异常类:业务规则拒绝了该操作,异常消息是给用户看的。它继承自 [Exception] ,没有添加任何内容;只有它的名称才重要;
  • 第 23–27 行:一个人的数据,由 Web 层传递给业务层:一个简单的对象,与 [Django] 无关;
  • 第 34–38 行:不存在的人属于业务错误;
  • 第 44–52 行:规则 1:不允许两个人有相同的名和姓。该规则在写入数据库之前验证,如果不满足,就抛出 [BusinessError] 异常 。但这种验证并不充分:两个同时发出的请求可能都验证到没有同名者,然后都继续插入记录。此时数据库的唯一性约束会拒绝第二个 [INSERT],ORM 引发 [IntegrityError],它会被转换为同样的 [BusinessError]。数据库是最后一道防线。[raise ... from e] 把原始异常与新异常关联起来:日志会同时显示两者;
  • 第 55–70 行:规则 2:不要修改在此期间已被他人修改过的记录。更新表单(在隐藏字段中)携带所读取记录的版本;如果它与当前版本不同,就说明该记录在显示之后已经发生了变化。还有一种情况:并发修改发生在第 58 行的读取与第 66 行的保存之间:这由 DAO 层的乐观锁检测。随后该函数会重新读取该人员的记录,以返回新的版本;
  • 第 73–77 行:删除操作把该人员设置为“已删除”,以便显示确认消息。

每个写入数据的操作都在一个事务中执行:[transaction.atomic()],通过 [with] 使用(上下文管理器,示例 20),在代码块开始时开启一个事务([BEGIN]);如果代码块正常结束(即使是通过 [return] 结束),事务就会提交([COMMIT]);如果代码块内发生异常,事务就会回滚([ROLLBACK]):代码块内所做的任何更改都不会保留,异常则继续沿其路径传播。[transaction.atomic] 也可以用作整个函数的装饰器([@transaction.atomic])。因此,业务层决定事务的范围:一个业务操作对应一个事务。在 [atomic] 块之外,ORM 以“自动提交”模式工作:每条 SQL 命令都会立即提交。[IntegrityError] 在 [with] 块之外捕获:在块内部,出错之后事务就无法再使用了。其他异常(例如数据库故障或编程错误)不属于业务错误:它们会继续被向上传递处理。

9.1.6. Web 层

数据输入由一个表单描述(示例 19):

# persons/forms.py:人员的表单(见示例 18 和 19)

from django import forms

from .business import PersonData


class PersonForm(forms.Form):
    first_name = forms.CharField(label="First name", max_length=30, error_messages={
        "required": "The first name is required.", "max_length": "30 characters at most."})
    last_name = forms.CharField(label="Last name", max_length=30, error_messages={
        "required": "The last name is required.", "max_length": "30 characters at most."})
    age = forms.IntegerField(label="Age", min_value=0, max_value=150, error_messages={
        "required": "The age is required.",
        "invalid": "The age must be an integer.",
        "min_value": "The age must be between 0 and 150.",
        "max_value": "The age must be between 0 and 150."})

    # edit=True:编辑表单,多一个字段
    def __init__(self, *args, edit=False, **kwargs):
        super().__init__(*args, **kwargs)
        for field in self.fields.values():
            field.widget.attrs["class"] = "form-control"
        # 版本:一个隐藏字段,仅出现在编辑表单中
        if edit:
            self.fields["version"] = forms.IntegerField(widget=forms.HiddenInput)

    # 经过验证的数据,供业务层使用;CharField 已经去掉了输入开头和结尾的
    # 空格(strip 选项,默认为 true)
    def data_for_business(self) -> PersonData:
        d = self.cleaned_data
        return PersonData(d["first_name"], d["last_name"], d["age"])
  • 第 9–17 行:字段及其约束,消息为英文;
  • 第 20–26 行:构造函数的一个附加参数 [edit],按名称指定([PersonForm(request.POST, edit=True)]):写在 [*args] 之后的参数只能按名称传递。更新表单在一个隐藏字段中多接收一个字段“version”:[self.fields] 是一个字典,可以向其中添加字段;
  • 第 30–32 行:经过验证的数据,采用业务层所期望的格式。

[Django] 也可以根据模型生成表单([forms.ModelForm] 类):其字段及约束由列推导而来,其 [save()] 方法保存对象。这种做法非常常见。但是,这样一来,表单会在业务层验证其规则之前就修改模型。单独的表单能让各层保持分离:Web 层只把经过验证的数据传递给业务层。

# persons/views.py:Web 层;它只了解业务层

from django.contrib import messages
from django.shortcuts import redirect, render
from django.urls import reverse
from django.views.decorators.http import require_GET, require_http_methods

from . import business
from .business import BusinessError
from .forms import PersonForm


@require_GET
def home(request):
    return redirect("persons_list")


@require_GET
def list_persons(request):
    return render(request, "persons/list.html", {"persons": business.list_all()})


# GET:空表单;POST:发送的表单
@require_http_methods(["GET", "POST"])
def add(request):
    title = "Add a person"
    action = reverse("persons_add")
    if request.method == "GET":
        return form_page(request, title, PersonForm(), action)
    form = PersonForm(request.POST)
    if not form.is_valid():
        return form_page(request, title, form, action, status=422)
    try:
        p = business.add(form.data_for_business())
    except BusinessError as e:
        # 某条业务规则拒绝:表单连同输入再次显示,
        # 消息显示在页面底部
        return form_page(request, title, form, action, error=str(e))
    messages.success(request, f"{p} has been added.")
    return redirect("persons_list")


# GET:编辑表单,已预先填充
@require_GET
def edit(request, id):
    try:
        p = business.read(id)
    except BusinessError as e:
        messages.error(request, str(e))
        return redirect("persons_list")
    form = PersonForm(edit=True, initial={
        "first_name": p.first_name, "last_name": p.last_name, "age": p.age, "version": p.version})
    return form_page(request, "Edit a person", form,
                     reverse("persons_person", args=[id]), method="PUT")


# PUT:发送的编辑表单;DELETE:删除
@require_http_methods(["PUT", "DELETE"])
def person(request, id):
    if request.method == "DELETE":
        try:
            p = business.delete(id)
            messages.success(request, f"{p} has been deleted.")
        except BusinessError as e:
            # 没有表单需要再次显示:错误也会以闪现消息的形式传递
            messages.error(request, str(e))
        return redirect("persons_list")
    title = "Edit a person"
    action = reverse("persons_person", args=[id])
    form = PersonForm(request.POST, edit=True)
    if not form.is_valid():
        return form_page(request, title, form, action, method="PUT", status=422)
    try:
        p = business.update(id, form.cleaned_data["version"], form.data_for_business())
    except BusinessError as e:
        return form_page(request, title, form, action, method="PUT", error=str(e))
    messages.success(request, f"{p} has been edited.")
    return redirect("persons_list")


# 表单页面;业务错误:422 状态码,与无效表单一样
# (见示例 19)
def form_page(request, title, form, action, method=None, error=None, status=200):
    return render(request, "persons/form.html", {
        "title": title, "form": form, "action": action, "method": method,
        "error": error}, status=422 if error else status)
  • 第 8 行:业务层,Web 层所知道的唯一一层;
  • 第 25–40 行:添加操作,分三步:表单验证(输入错误,示例 19);调用业务层(业务规则);然后是 PRG 模式,并附带成功闪现消息(示例 20)。[BusinessError] 会重新显示表单,连同输入的数据和异常消息([str(e)]),模板会把该消息显示在页面底部。这样,输入错误和业务逻辑错误以相同的方式处理;
  • 第 44–54 行:编辑表单,用检索到的人员预填(参数 [initial],示例 18)。如果该人员不存在,则重定向到列表,并显示闪现错误消息([messages.error])。表单使用 PUT 方法提交(隐藏字段 [_method],示例 21),提交到 URL [/persons/<id>]([reverse],路由参数放在 [args] 中);
  • 第 58–78 行:[/persons/<id>] 的视图,处理 PUT 方法(更新,与添加操作遵循相同的模式)和 DELETE 方法(删除,由防 CSRF 令牌保护,示例 21)。对于删除,没有表单可供重新显示:任何错误同样通过闪现消息传达;
  • 第 83–86 行:表单页面。业务错误与无效表单一样,以状态码 422 返回。

Web 层既不包含 SQL,也不包含任何业务规则:它把请求转换为对业务层的调用,把结果转换为页面。路由([persons/urls.py]):[/persons] (列表)、[/persons/add]、[/persons/<id>/edit],以及 [/persons/<id>] (PUT 和 DELETE)。

模板:

<!doctype html>
{% load static %}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Persons</title>
  <link rel="stylesheet" href="{% static 'bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-3" style="max-width: 44rem">
    {# 闪现消息;tags:其级别(success、error) #}
    {% for message in messages %}
      <div class="alert {% if message.tags == 'error' %}alert-danger{% else %}alert-success{% endif %}" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {% block page_bottom %}{% endblock %}
  </div>
  {% include "fragments/confirmation.html" %}
  <script src="{% static 'js/app.js' %}"></script>
</body>
</html>
  • 第 14–16 行:页面顶部的闪现消息(示例 20)。它们的标签([message.tags]:[success]、[error])决定它们的颜色;
  • 第 20 行:页脚块,页面在其中显示错误(示例 19);
  • 第 22–23 行:确认窗口及其脚本(示例 21)。
{% extends "layout.html" %}

{% block content %}
  <div class="d-flex justify-content-between align-items-center mb-2">
    <h1 class="h3 mb-0">Persons</h1>
    <a class="btn btn-primary btn-sm" href="{% url 'persons_add' %}">Add</a>
  </div>
  <table class="table align-middle">
    <thead><tr><th>First name</th><th>Last name</th><th>Age</th><th></th></tr></thead>
    <tbody>
      {% for p in persons %}
        <tr>
          <td>{{ p.first_name }}</td>
          <td>{{ p.last_name }}</td>
          <td>{{ p.age }}</td>
          <td class="text-end">
            <a class="btn btn-sm btn-outline-primary" href="{% url 'persons_edit' p.id %}">Edit</a>
            <form method="post" class="d-inline" action="{% url 'persons_person' p.id %}"
                  data-confirmation="Delete {{ p.first_name }} {{ p.last_name }}?">
              {% csrf_token %}
              <input type="hidden" name="_method" value="DELETE">
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      {% empty %}
        <tr><td colspan="4">No persons.</td></tr>
      {% endfor %}
    </tbody>
  </table>
{% endblock %}

列表包含示例 21 中的链接和按钮,以及它的确认窗口(文件 [fragments/confirmation.html] 和 [static/js/app.js] 就是示例 21 中的文件)。属性 [p.first_name], [p.last_name]……是由 ORM 读取的 [Person] 对象的属性。块 [{% empty %}] (示例 14)处理空列表。

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">{{ title }}</h1>
  <form method="post" action="{{ action }}" novalidate style="max-width: 24rem">
    {% csrf_token %}
    {# 修改通过 PUT 方法发送(见示例 21) #}
    {% if method %}<input type="hidden" name="_method" value="{{ method }}">{% endif %}
    {{ form.first_name.as_field_group }}
    {{ form.last_name.as_field_group }}
    {{ form.age.as_field_group }}
    {# 版本:一个隐藏字段,仅出现在编辑表单中 #}
    {% if form.version %}{{ form.version }}{% endif %}
    <div class="d-flex gap-2">
      <button class="btn btn-primary" type="submit">Save</button>
      <a class="btn btn-link" href="{% url 'persons_list' %}">Cancel</a>
    </div>
  </form>
{% endblock %}

{% block page_bottom %}
  {% if error %}
    <div class="error-area" role="alert">{{ error }}</div>
  {% endif %}
{% endblock %}

添加和修改共用的模板:

  • 第 8 行:隐藏字段 [_method],仅用于修改;
  • 第 13 行:隐藏的版本字段,如果表单中存在的话;
  • 第 21–25 行:业务错误,位于页面底部。

9.1.7. 执行

人员列表:

Image

填写有误的添加表单:输入错误由 Web 层检测。

Image

同名者:输入本身是正确的,但业务层拒绝了这次添加。由于比较由数据库执行,因此它既忽略大小写,也忽略重音:[marie pelissier] 与 [Marie Pélissier] 是同名者。

Image

添加成功:

Image

为了测试规则 2,我们在两个标签页中打开同一条记录。在第一个标签页中,修改年龄并保存。在第二个标签页中,它仍显示旧版本,我们也修改该记录:

Image

删除,带确认:

Image

Image

9.1.8. SQL 命令

我们在控制台中跟踪一次修改所对应的 SQL 命令(服务器已重启,数据库也已重新创建)。显示 1 号人员的修改表单:

(0.000)
                SELECT VERSION(),
                       @@sql_mode,
                       @@default_storage_engine,
                       @@sql_auto_is_null,
                       @@lower_case_table_names,
                       CONVERT_TZ('2001-01-01 01:00:00', 'UTC', 'UTC') IS NOT NULL
            ; args=None; alias=default
(0.000) SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; args=None; alias=default
(0.000) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE `persons`.`id` = 1 ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=(1,); alias=default
[27/Sep/2026 19:45:19] "GET /persons/1/edit HTTP/1.1" 200 2460

每一行显示命令的耗时(以秒计)、SQL 命令、其参数([args])以及数据库名称([alias])。前两条命令用于建立连接:[Django] 查询服务器(其版本、其设置),然后设置事务隔离级别([READ COMMITTED]:事务可以看到其他事务已提交的更改)。接下来是按主键读取,带有 [ORDER BY] (对应 [Meta.ordering])和 [LIMIT 1] (对应 [first()])。在日志中,参数被按顺序复制进去以便阅读;实际上,它们是单独发送的([args])。这里没有事务:单独的读取不需要事务。主记录以新的年龄保存:

1
2
3
4
5
6
7
(0.000) BEGIN; args=None; alias=default
(0.001) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE `persons`.`id` = 1 ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=(1,); alias=default
(0.001) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE (`persons`.`first_name` = 'Marie' AND `persons`.`last_name` = 'Pélissier' AND NOT (`persons`.`id` = 1)) ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=('Marie', 'Pélissier', 1); alias=default
(0.000) UPDATE `persons` SET `first_name` = 'Marie', `last_name` = 'Pélissier', `age` = 43, `version` = (`persons`.`version` + 1) WHERE (`persons`.`id` = 1 AND `persons`.`version` = 0); args=('Marie', 'Pélissier', 43, 1, 1, 0); alias=default
(0.000) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE `persons`.`id` = 1 ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=(1,); alias=default
(0.001) COMMIT; args=None; alias=default
[27/Sep/2026 19:45:19] "POST /persons/1 HTTP/1.1" 302 0

(连接已经打开,与上一个请求相同)。在同一个事务([BEGIN] ……[COMMIT])中,我们可以看到:读取记录、查找同名者、[UPDATE],然后是重新读取记录。[UPDATE] 会递增版本([version + 1]),并设置乐观锁条件([AND version = 0])。开发服务器把该请求记录为 POST:这是它到达时的样子,之后中间件才把它转换为 PUT。现在让我们第二次提交同一个表单,仍然使用旧版本:

1
2
3
4
5
(0.000) BEGIN; args=None; alias=default
(0.000) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE `persons`.`id` = 1 ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=(1,); alias=default
(0.000) ROLLBACK; args=None; alias=default
Unprocessable Content: /persons/1
[27/Sep/2026 19:45:19] "POST /persons/1 HTTP/1.1" 422 2562

读取到的版本与表单中的版本不一致:业务层引发了 [BusinessError],它使事务回滚([ROLLBACK]),页面显示“This record has been modified meanwhile: reload it.”。同样,添加同名者会在查找同名者之后停止,不会执行 [INSERT]。