Skip to content

3. 视图模型

视图需要浏览器发送的信息:URL 的参数([?name=martin&age=42])、表单字段、请求体,有时还有请求头。原课程把所有这些信息称为动作模型;这里我们称之为视图模型。本章展示 [Django] 视图如何获取这些信息、将其转换为正确的类型并进行验证。这个过程称为数据绑定。

[Django] 通过 [HttpRequest] 对象(示例 05)以字符串的形式提供对请求信息的访问。为了转换和验证这些信息,它有一个统一的核心工具:来自 [django.forms] 模块的表单。[Django] 表单是一个逐字段描述所期望数据的类:每个字段都能把收到的字符串转换为其数据类型(整数、日期、列表等),并验证约束条件(“必填”“0 到 150 之间的整数”等)。尽管名为表单,它们并不局限于 HTML 表单:它们也可以验证 URL 的参数或 JSON 文档。我们先手动读取参数(示例 07),然后使用表单来处理转换和验证(示例 08 至 12)。在下一章中,这些表单还将以 HTML 形式显示。

请注意术语:“模型”一词在 [Django] 中有特定含义,指 ORM 中的类(第 7 章)。本章所定义的视图模型,是视图从请求中接收到的内容。我们会把描述它的类组织到 [viewmodels.py] 文件中,绝不放入 [models.py],后者专用于 ORM。

示例 07 至 12 的运行方式与上一章的示例相同:在示例目录中打开终端,并激活虚拟环境([python manage.py runserver]);[Ctrl-C] 停止服务器。大多数示例使用示例 03 中的 [ReadableJson] 中间件,得到可读的 JSON。只有在其配置文件引入了新内容时,我们才会对其进行说明。

3.1. 示例 07:URL 参数

URL 的参数是 [?] 之后的部分:[?name=martin&age=42]。这一部分称为查询字符串。每个参数是一个 [name=value] 对;各对之间用 [&] 分隔。[parameters] 应用的视图:

# parameters/views.py:URL 的参数("查询字符串")

from django.core.exceptions import BadRequest
from django.http import HttpResponse, JsonResponse
from django.views.decorators.http import require_GET


# /parameters/action01?name=martin:request.GET 包含 URL 参数;
# get 返回参数的值,若参数不存在则返回 None
@require_GET
def action01(request):
    name = request.GET.get("name")
    return HttpResponse(f"name = [{name}], of type {type(name).__name__}")


# /parameters/action02?age=42:参数的值总是字符串
@require_GET
def action02(request):
    age = request.GET.get("age")
    return HttpResponse(f"age = [{age}], of type {type(age).__name__}")


# /parameters/action03?age=42:必需的参数,手动转换;
# 缺少该参数,或其值不是整数,都会产生 400 响应
@require_GET
def action03(request):
    text = request.GET.get("age")
    if text is None:
        # Django 会将其转换为 400 响应(Bad Request)的异常
        raise BadRequest("the [age] parameter is required")
    try:
        # int 将字符串转换为整数,或抛出 ValueError 异常
        age = int(text)
    except ValueError:
        raise BadRequest(f"[{text}] is not an integer")
    return HttpResponse(f"age = [{age}], of type {type(age).__name__}")


# /parameters/action04?page=2:参数缺失时使用默认值
@require_GET
def action04(request):
    page = request.GET.get("page", "1")
    return HttpResponse(f"page = [{page}]")


# /parameters/action05?q=django:URL 参数的名称不一定
# 与 Python 变量的名称相同
@require_GET
def action05(request):
    search = request.GET.get("q")
    return HttpResponse(f"search = [{search}]")


# /parameters/action06?name=martin&age=42:以字典形式一次获取全部参数
@require_GET
def action06(request):
    return JsonResponse(request.GET.dict())
  • 第 12 行:请求的 [GET] 属性包含 URL 的参数。它的名称容易引起误解:无论请求方法是什么它都存在,包括 URL 带有参数的 POST 请求。它是一个 [QueryDict] 对象,即一个字典,其 [get] 方法返回参数的值(已解码),如果参数不存在则返回 [None] ;
  • 第 13 行:视图显示该值及其类型:[type(name)] 返回该值的类,而 [__name__] 返回 该类的名称。从 URL 中取得的值始终是字符串([str]);
  • 第 26–36 行:一个必填参数以及手动转换,并区分两种可能的错误。运算符 [is] 用于检查是否相等;[text is None] 是检查值是否缺失的正确方式。[raise BadRequest(message)] 以 400 响应(Bad Request:请求无效)终止视图,就像 [Http404] 以 404 响应终止视图一样(示例 03)。函数 [int] 把字符串转换为整数,如果字符串不是整数,则抛出异常 [ValueError] :[try] / [except] 块捕获该异常,以返回我们自己的错误;
  • 第 42 行:[get] 的第二个参数是默认值,在参数缺失时使用。这是列表页码的典型用法。请注意,默认值是字符串 ["1"],与收到的值一样;
  • 第 50 行:不要求 [Python] 变量与 URL 参数同名。搜索引擎常使用简短的参数,例如 [q] (query);
  • 第 57 行:[dict()] 以标准 [Python] 字典的形式返回 URL 的所有参数,视图再把它转换为 JSON(示例 03)。

我们用 [curl] 测试每个视图。先是参数存在,然后是参数不存在:

curl -i "http://localhost:8000/parameters/action01?name=martin"
curl "http://localhost:8000/parameters/action01"
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

name = [martin], of type str
name = [None], of type NoneType

在终端中,URL 两侧的引号是必需的:没有引号,shell 会解释 [&] (在 [Linux] 下它表示在后台运行命令)和 [?]。值 [None] 插入 f-string 时会变成文本 [None]。包含空格或特殊字符的值必须进行 URL 编码:空格变成 [%20] (或 [+]),而 [&] 变成 [%26] (否则它会把两个参数分隔开)。浏览器会自动处理这一点;使用 [curl] 时,则必须自己写出来。[Django] 会在视图读取该值之前先对其解码:

curl "http://localhost:8000/parameters/action01?name=jean%20dupont%20%26%20sons"
name = [jean dupont & sons], of type str

存在但为空的参数([?name=])返回空字符串,而不是 [None]:视图可以区分这两种情况。年龄值,以及随后的手动转换——成功、无参数和失败的情形:

1
2
3
4
curl "http://localhost:8000/parameters/action02?age=42"
curl "http://localhost:8000/parameters/action03?age=42"
curl -i http://localhost:8000/parameters/action03
curl -i "http://localhost:8000/parameters/action03?age=abc"
age = [42], of type str
age = [42], of type int
HTTP/1.1 400 Bad Request
Content-Type: text/html

<!DOCTYPE html>
...
HTTP/1.1 400 Bad Request
Content-Type: text/html

<!DOCTYPE html>
...

视图 02 收到的值 [42] 是字符串;视图 03 转换后的值是整数。[int] 函数能容忍空格:[?age=%2042] (“42”前面有一个空格)同样返回 42。两种错误都会产生 400 响应。在调试模式下,这是 [Django] 的错误页面,其中显示了我们的消息:

Image

默认值和重命名的参数:

1
2
3
curl http://localhost:8000/parameters/action04
curl "http://localhost:8000/parameters/action04?page=3"
curl "http://localhost:8000/parameters/action05?q=django"
1
2
3
page = [1]
page = [3]
search = [django]

一次获取所有参数。参数 [name] 出现了两次:

curl "http://localhost:8000/parameters/action06?name=martin&age=42&name=durand"
1
2
3
4
{
    "name": "durand",
    "age": "42"
}

参数 [name] 在字典中只保留其最近的值。我们将在示例 10 中看到,[request.GET] 则保留了所有的值。年龄仍然是字符串(["42"],在 JSON 中带引号):因为没有要求转换。在浏览器(此处为 [Chromium])中,JSON 会按服务器格式化的样子原样显示;如果它尚未缩进,“Pretty-print”复选框可以为其添加缩进。地址栏还显示了 URL 中带重音字符的编码([é] 变成 [%C3%A9],其两个字节采用 [UTF-8] 编码):

Image

第一个示例说明了手动方式的局限:对于每个参数,都必须编写读取、转换以及处理缺失值和错误的代码。如果有十个参数,视图代码就会被这些检查淹没,而且也无法表达规则(“长度为 2 到 20 个字符的字符串”)。更好的做法是描述期望的内容,让框架来验证。这正是下一个示例的目的。

3.2. 示例 08:用类描述的视图模型

视图模型可以用一个类来描述:[Django] 表单,每个期望的参数对应一个字段。字段类型指定如何转换收到的字符串,其参数则指定必须满足的约束。[Django] 提供了大约三十种字段类型:[CharField] (字符串)、[IntegerField]、[DecimalField]、[FloatField]、[BooleanField]、[DateField]、[EmailField]、[URLField]、[ChoiceField] (列表中的一个值)、[MultipleChoiceField]、[FileField]……

3.2.1. 模型:persons/viewmodels.py

# persons/viewmodels.py:视图的模型,一个描述预期
# 参数、其类型及其约束的类

from django import forms


# 一个 Django 表单(forms.Form):每个属性都是一个字段,它知道如何将
# 接收到的值(字符串)转换为其类型,并检查其约束
class PersonModel(forms.Form):
    # 必填(这是默认值:required=True),2 到 20 个字符的字符串
    name = forms.CharField(min_length=2, max_length=20)
    # 必填,0 到 150 之间的整数
    age = forms.IntegerField(min_value=0, max_value=150)
    # 必填,仅限这三个值之一:(值, 标签) 对
    title = forms.ChoiceField(choices=[("Mr", "Mr"), ("Mme", "Mme"), ("Melle", "Melle")])
    # 可选;若提供,则必须是有效的电子邮件地址
    email = forms.EmailField(required=False)
  • 第 4 行:从 [forms] 模块导入自 [Django]。这是标准做法:字段将被命名为 [forms.CharField]、[forms.IntegerField]……;
  • 第 9 行:表单是继承自 [forms.Form] 的类;
  • 第 11–17 行:字段,写成类的属性(不是对象的属性:它们定义在类体中、所有方法之外)。[Django] 通过检查类来发现它们;它们的顺序与声明时相同。所有字段默认都是必填的([required=True]):缺失或为空的参数就是错误;
  • 第 11 行:姓名长度必须在 2 到 20 个字符之间。[CharField] 还会在验证之前去掉值两侧的空格(参数 [strip],默认值为 [True]);
  • 第 13 行:年龄是 0 到 150 之间的整数。该字段把字符串转换为整数——这就是示例 07 中视图 03 的功能,只需一行;
  • 第 15 行:称谓必须是所列三个值之一。选项是(值,标签)对:标签将在页面上显示该字段时使用(示例 18);
  • 第 17 行:电子邮件地址是可选的([required=False]);如果提供,则必须有效。

这个模型描述了期望的数据,其中不包含任何验证指令。这称为声明式风格。表单的使用分三步:用收到的数据创建表单([PersonModel(request.GET)]:一个与数据“绑定”的表单);检查其是否有效([is_valid()]),这会触发每个字段的转换和验证;然后读取转换后的值([cleaned_data],一个字典)或错误([errors],一个字典,把每个出错的字段与其消息列表关联起来)。每个字段的转换和验证相互独立:所有错误会一次性检测出来。

3.2.2. 关系:persons/binding.py

[Symfony] 有一个属性 [#[MapQueryString]],它会在调用动作之前构建并验证模型。[Django] 对函数视图没有这样的机制。但我们从示例 02 知道,装饰器可以包装视图,使其在视图之前执行动作:我们来编写一个装饰器,它根据 URL 的参数构建模型、验证模型,并把模型传给视图。

# persons/binding.py:URL 参数到模型的绑定,及其验证

from functools import wraps


# 当参数不符合模型的约束时抛出的异常;
# 它携带表单,因此也携带表单的错误
class InvalidModel(Exception):
    def __init__(self, form):
        super().__init__("invalid model")
        self.form = form


# 一个带参数的装饰器:@from_url(PersonModel) 用一个包装函数
# 替换视图,该函数在调用视图之前构建并验证模型。
# 无效的模型会抛出 InvalidModel,视图永远不会被调用
def from_url(model_class):
    def decorator(view):
        # @wraps:包装函数保留视图的名称和文档
        @wraps(view)
        def wrapper(request, *args, **kwargs):
            form = model_class(request.GET)
            if not form.is_valid():
                raise InvalidModel(form)
            # cleaned_data:转换并验证后的值,保存在字典中
            return view(request, form.cleaned_data, *args, **kwargs)
        return wrapper
    return decorator
  • 第 8–11 行:一个“自定义”异常:继承自 [Exception] 类的类,该类来自 [Python]。它的构造函数调用父类的构造函数([super().__init__(...)],传入异常消息),然后把表单存放在一个属性中:捕获该异常的代码可以在那里找到错误;
  • 第 17–28 行:一个带参数的装饰器。[@from_url(PersonModel)] 分两步执行:[from_url(PersonModel)] 返回函数 [decorator],它被应用于视图,并返回函数 [wrapper],由后者取代视图。在另一个函数内部定义的函数会保留其变量([model_class]、[view]),即使外层函数已经执行完毕:这称为闭包;
  • 第 20 行:[@wraps(view)] 来自 [functools] 模块,它使包装函数具有视图的名称和文档:[Django] 的错误消息和工具将继续引用 [action01],而不是 [wrapper];
  • 第 21 行:包装函数接收 [Django] 传给视图的内容:请求,以及事先无法知道的路由参数。[*args] 接收按位置传递的参数(放在元组中),而 [**kwargs] 接收 按名称传递的参数(放在字典中);在第 26 行调用时,[*args] 和 [**kwargs] 会把它们原样传递下去;
  • 第 22–24 行:表单与 URL 的参数绑定并进行验证;如果表单无效,包装函数会抛出异常,视图根本不会被调用——因此视图不必担心无效数据;
  • 第 26 行:否则调用视图,并多传一个参数:转换并验证后的值。

3.2.3. 视图:persons/views.py

# persons/views.py:模型是一个类的视图

from django.http import JsonResponse
from django.views.decorators.http import require_GET

from .binding import from_url
from .viewmodels import PersonModel


# /persons/action01?name=martin&age=42&title=Mr
# @from_url 根据 URL 参数构建 PersonModel,验证
# 它,并将其值传给视图(person 参数)。无效的模型会抛出
# 异常(见 config/middleware.py),视图永远不会被调用
@require_GET
@from_url(PersonModel)
def action01(request, person):
    return JsonResponse({
        "received": request.GET.dict(),
        "person": person,
        "ageType": type(person["age"]).__name__,
    })
  • 第 14–15 行:堆叠了两个装饰器;离函数最近的那个最先应用。因此 [require_GET] 包装的是 [from_url] 的包装函数:先检查 HTTP 方法,再检查参数;
  • 第 16 行:视图以字典的形式接收经过验证的模型;
  • 第 17–21 行:视图原样返回收到的参数,随后是模型和年龄的类型,以说明两者的区别。

3.2.4. 错误处理:config/middleware.py

谁来处理 [InvalidModel] 异常?如果不采取进一步措施,[Django] 会自己用 500 响应来处理它:对它来说,这只是又一个异常。我们希望得到 JSON 格式的错误响应,状态码为 400,格式由我们自己定义。这就是中间件的作用:

# config/middleware.py:示例 08 的中间件

import json

from django.http import JsonResponse

from persons.binding import InvalidModel


# 人类可读的 JSON(见示例 03)
class ReadableJson:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        if isinstance(response, JsonResponse):
            data = json.loads(response.content)
            response.content = json.dumps(data, ensure_ascii=False, indent=4)
        return response


# 无效的模型会在整个应用范围内产生一个 400 响应,其中详细列出
# 各项错误
class ValidationErrors:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    # process_exception:当异常从视图中抛出时,Django 调用此方法。它返回一个
    # 响应,用以替换 Django 的错误页面,或者返回 None,
    # 让 Django 照常处理该异常
    def process_exception(self, request, exception):
        if not isinstance(exception, InvalidModel):
            return None
        # errors:一个字典 {字段:该字段的错误消息列表}
        errors = [{"field": field, "message": message}
                  for field, messages in exception.form.errors.items()
                  for message in messages]
        return JsonResponse({"status": 400, "errors": errors}, status=400)
  • 第 11–20 行:示例 03 中的 [ReadableJson] 中间件;
  • 第 25–30 行:第二个中间件,其方法 [__call__] 只是把请求传给链中的下一个组件;
  • 第 35–42 行:[process_exception] 方法。除了 [__call__],中间件模块还可以有 [Django] 在处理过程中的特定时刻调用的方法(关于生命周期的一章会全面介绍它们)。[process_exception] 在视图抛出异常时被调用。它要么返回一个响应——取代由 [Django] 生成的错误页面——要么返回 [None],让 [Django] 照常处理该异常。在 [MIDDLEWARE] 配置中声明后,该中间件适用于应用中的所有视图:每个验证模型的视图都能从中受益,而无需编写任何一行错误处理代码;
  • 第 36 行:如果不是验证错误,中间件什么也不做;
  • 第 39–41 行:以字典形式表示的错误列表,通过带有两层循环的列表推导式计算得出:[for]——针对每个有错误的字段,再针对与该字段相关联的每条消息。[items()] 以(键,值)对的形式遍历字典;
  • 第 42 行:一个 JSON 响应,状态码为 400。它随后沿着中间件链向上传递,并经过 [ReadableJson] (文件 [config/settings.py] 的第 18–20 行)。

3.2.5. 执行

一个有效的模型:

curl -i "http://localhost:8000/persons/action01?name=martin&age=42&title=Mr"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "received": {
        "name": "martin",
        "age": "42",
        "title": "Mr"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": ""
    },
    "ageType": "int"
}

收到的参数是字符串;模型中的年龄是整数(在 JSON 中没有引号),而缺失的地址是空字符串([CharField] 或 [EmailField] 的“空”值;可选的 [IntegerField] 的空值则是 [None])。姓名两侧带空格([%20])且提供了地址的情形:

curl "http://localhost:8000/persons/action01?name=%20%20martin%20&age=42&title=Mme&email=jean.martin@example.com"
{
    "received": {
        "name": "  martin ",
        "age": "42",
        "title": "Mme",
        "email": "jean.martin@example.com"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mme",
        "email": "jean.martin@example.com"
    },
    "ageType": "int"
}

姓名两侧的空格已被字段去掉:视图收到的是清理后的值([cleaned_data])。因此,仅由空格组成的姓名会变为空,并因缺失而被拒绝。现在不带任何参数:三个必填字段缺失。

curl -i http://localhost:8000/persons/action01
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This field is required."
        },
        {
            "field": "age",
            "message": "This field is required."
        },
        {
            "field": "title",
            "message": "This field is required."
        }
    ]
}

消息是英文的。表单消息在 [Django] 的代码中以英文编写,但它们会经过其翻译机制,而且 [Django] 自带约一百种语言的翻译:如果设置 [LANGUAGE_CODE = "fr"],它们就会是法语。自示例 01 起,我们所有的示例都使用设置 [LANGUAGE_CODE = "en"]。 同时有四个无效字段:

curl "http://localhost:8000/persons/action01?name=m&age=200&title=Mlle&email=xx"
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "Ensure this value has at least 2 characters (it has 1)."
        },
        {
            "field": "age",
            "message": "Ensure this value is less than or equal to 150."
        },
        {
            "field": "title",
            "message": "Select a valid choice. Mlle is not one of the available choices."
        },
        {
            "field": "email",
            "message": "Enter a valid email address."
        }
    ]
}

所有错误会一次性报告,使用户可以一次改正所有问题。最后,年龄不是数字的情形:

curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "Ensure this value has at least 2 characters (it has 1)."
        },
        {
            "field": "age",
            "message": "Enter a whole number."
        },
        {
            "field": "title",
            "message": "Select a valid choice. Mlle is not one of the available choices."
        },
        {
            "field": "email",
            "message": "Enter a valid email address."
        }
    ]
}

同样,四个错误都被报告:年龄转换失败是 [age] 字段中的错误,与其他错误无异。这与 [Symfony] 不同,在那门课程中我们演示过,转换失败会使验证完全无法进行,因为它导致对象无法构造;而 [Django] 表单则对每个字段分别进行转换和验证。

3.3. 示例 09:由视图执行的验证

在示例 08 中,无效的模型会中断视图,由应用的中间件来响应。这对 API 很方便,因为 API 的客户端是程序,期望得到标准化的错误响应。但网页通常更倾向于带着错误消息重新显示表单:在这种情况下,视图必须自己决定如何处理无效的模型。它直接使用表单,而不使用装饰器。该示例不再有中间件:

1
2
3
4
5
6
7
8
9
09-action-validation/
├── config/
│   └── ...
├── persons/
│   ├── __init__.py
│   ├── urls.py
│   ├── viewmodels.py
│   └── views.py
└── manage.py

3.3.1. 模型:persons/viewmodels.py

# persons/viewmodels.py:人员的输入,以及它必须
# 遵守的约束,使用我们自己的错误消息

from django import forms

# error_messages:此表单的消息,用以替换 Django 的消息。键
# 是错误代码:required(字段缺失)、invalid_choice(值不在
# 列表中)、invalid(值无法转换)等
REQUIRED = {"required": "the field is required"}


class PersonInput(forms.Form):
    name = forms.CharField(min_length=2, max_length=20, error_messages=REQUIRED)
    # |:合并两个字典:为此字段多加一条消息
    age = forms.IntegerField(min_value=0, max_value=150,
                             error_messages=REQUIRED | {"invalid": "an integer is expected"})
    title = forms.ChoiceField(choices=[("Mr", "Mr"), ("Mme", "Mme"), ("Melle", "Melle")],
                              error_messages=REQUIRED | {"invalid_choice": "unknown value"})
    email = forms.EmailField(required=False)

该模型包含示例 08 中的字段,但这次使用我们自己的错误消息:

  • 第 9 行:一个字典,一次性定义,由三个必填字段共享。按照约定,用大写字母书写的模块变量是常量;
  • 第 13–18 行:字段的 [error_messages] 参数用我们的消息替换该字段的消息。每种错误类型都有一个代码:[required] (字段缺失或为空)、[invalid] (值无法转换:例如年龄为 [abc])、[invalid_choice] (值不在列表中)、[min_length]、[max_length]、[min_value]、[max_value]……字典为每个代码关联一条消息。字典中未列出的消息则使用 [Django] 自带的消息;
  • 第 16 行:运算符 [|] 合并两个字典:结果包含两者的键(如果有相同的键,则右边的优先)。因此,“age”在我们这里有两条消息。

[Django] 自带的消息并不总是合适;我们刚刚看到了如何逐字段替换它们。若要在整个应用中替换它们,我们提供翻译(参见国际化一章):多语言应用必须使用的是这些翻译,而不是 [error_messages]。

3.3.2. 视图:persons/views.py

# persons/views.py:由视图决定如何处理无效的输入

from django.http import HttpResponse
from django.utils.html import format_html, format_html_join
from django.views.decorators.http import require_GET

from .viewmodels import PersonInput


# /persons/action01?name=martin&age=42&title=Mr
@require_GET
def action01(request):
    # 输入:交给表单的 URL 参数
    person_input = PersonInput(request.GET)
    # is_valid 检查约束,并将错误存入 person_input.errors
    if not person_input.is_valid():
        # format_html_join:每个错误对应一段 HTML;插入的值会被
        # 转义(< 变成 &lt;……):输入无法注入 HTML
        items = format_html_join("", "<li>{}: {}</li>",
                                 ((field, message) for field, messages in person_input.errors.items()
                                  for message in messages))
        return HttpResponse(format_html("<p>The form contains errors:</p><ul>{}</ul>", items))
    data = person_input.cleaned_data
    return HttpResponse(format_html("<p>Welcome {} {} ({} years old)</p>",
                                    data["title"], data["name"], data["age"]))
  • 第 14 行:视图创建与 URL 的参数绑定的表单;
  • 第 16 行:[is_valid()] 转换并验证每个字段,并把出现的错误存放在 [person_input.errors] 中。它不会抛出任何异常:接下来怎么做由视图自己决定;
  • 第 19–22 行:各字段的错误分别放在一个 [<li>] 标签中。[format_html_join] 根据文本模板 [<li>{}: {}</li>],为一个值序列中的每个元素(此处是由生成器表达式产生的(字段,消息)对)生成一段 HTML:每个 [{}] 接收该对中的一个值。[format_html] 对单个片段做同样的事。这两个函数来自 [django.utils.html] 模块,具有一个重要特性:插入的值会被转义;
  • 第 23–25 行:如果成功,则显示欢迎消息以及转换后的值。

转义一个值,就是把在 HTML 中有特殊含义的字符([<]、[>]、[&]、["]、['])替换为相应的实体([&lt;]、[&gt;]……):它们将原样显示,而不会被解释。如果没有这项预防措施,用户可以输入包含 HTML 甚至 [JavaScript] 的“姓名”,这些代码会在任何查看该页面的人的浏览器中执行。这是网络上最常见的安全漏洞:脚本注入(XSS,跨站脚本)。相反,f-string 不做任何转义:[HttpResponse(f"Welcome {name}")] 就是有漏洞的。[format_html] 返回标记为“安全”的文本(一个 [SafeString] 对象):已经转义的部分在插入另一段文本时不会被再次转义([items],第 22 行)。在下一节中,[Django] 的模板会对插入页面的任何值自动执行这种转义。

一个有效的输入,随后是一个包含四个错误的输入:

Image

Image

消息是英文的:有来自 [Django] 的(姓名、地址),也有我们自己的(年龄、称谓)。第二个查询(姓名中包含 HTML 的那个)的原始响应,以及没有姓名且年龄过大的查询的响应:

1
2
3
curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mx&email=xx"
curl "http://localhost:8000/persons/action01?name=%3Cb%3Emartin%3C/b%3E&age=42&title=Mr"
curl "http://localhost:8000/persons/action01?age=200&title=Mr"
1
2
3
<p>The form contains errors:</p><ul><li>name: Ensure this value has at least 2 characters (it has 1).</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: Enter a valid email address.</li></ul>
<p>Welcome Mr &lt;b&gt;martin&lt;/b&gt; (42 years old)</p>
<p>The form contains errors:</p><ul><li>name: the field is required</li><li>age: Ensure this value is less than or equal to 150.</li></ul>

姓名 [<b>martin</b>] (在 URL 中编码为 [%3Cb%3E...] )被原样显示,没有被加粗:其标签已被中和。请注意,这次的响应是 200 状态码:视图选择渲染一个包含错误的普通页面。

3.4. 示例 10:多个参数

同一个参数可以在 URL 中多次出现:[?color=red&color=green]。浏览器对一组同名的复选框或多选列表(见下一章)发送的就是这种形式。[arrays] 应用的视图:

# arrays/views.py:在 URL 中多次出现的参数

from django import forms
from django.http import JsonResponse
from django.views.decorators.http import require_GET


# /arrays/action01?color=red&color=green:get 返回参数的最后一个值;
# 不过 request.GET 保留了所有的值
@require_GET
def action01(request):
    return JsonResponse({"color": request.GET.get("color"),
                         "raw": request.META["QUERY_STRING"]})


# /arrays/action02?color=red&color=green:getlist 返回参数的所有值,
# 放在一个列表中(若参数不存在则为空)
@require_GET
def action02(request):
    colors = request.GET.getlist("color")
    return JsonResponse({"color": colors, "count": len(colors)})


# action03 的模型:一个具有多个值的字段,其每个值都必须
# 属于该列表;必填(默认):至少一个值
class ColorsModel(forms.Form):
    color = forms.MultipleChoiceField(
        choices=[("red", "red"), ("green", "green"), ("blue", "blue")],
        error_messages={"invalid_choice": "%(value)s: unknown value"})


# /arrays/action03?color=red&color=black:一个列表,逐个元素验证
@require_GET
def action03(request):
    model = ColorsModel(request.GET)
    valid = model.is_valid()
    return JsonResponse({"colors": request.GET.getlist("color"), "valid": valid,
                         "errors": model.errors.get("color", [])})
  • 第 11–13 行:[get] 返回参数的最后一个值。作为对比,视图还返回浏览器发送的原始参数字符串;
  • 第 19–21 行:[getlist] 以列表形式返回参数的所有值;如果参数不存在,则列表为空。这正是 [QueryDict] 类的用途:它是为每个键关联一个值列表的字典,而其 [get] 方法只返回最后一个值,以适应最常见的情形;
  • 第 26–29 行:视图模型 03,一个只有单个字段的表单。[MultipleChoiceField] 接收一个值列表,并验证每个值是否都属于选项列表;由于它是必填的,因此至少需要一个值。它的 [invalid_choice] 消息包含标记 [%(value)s],[Django] 会用不正确的值替换它(这是使用 [Python] 的 [%] 运算符的格式字符串的语法)。可以在视图文件中定义类;它不需要自己的模块;
  • 第 34–38 行:表单与 URL 的参数绑定:由于其字段是多值字段,它自己读取 [color] 参数的所有值。视图返回收到的颜色、验证结果以及该字段的错误([errors.get("color", [])]:消息列表,如果该字段没有错误则为空列表)。

结果:

curl "http://localhost:8000/arrays/action01?color=red&color=green"
curl "http://localhost:8000/arrays/action02?color=red&color=green"
{
    "color": "green",
    "raw": "color=red&color=green"
}
{
    "color": [
        "red",
        "green"
    ],
    "count": 2
}

对于 HTML,只需给同一组中的复选框取相同的名称即可([Django] 的表单会替我们完成这一点;见示例 18)。这与 [PHP] 不同,[Symfony] 课程的读者对此已经遇到过:[PHP] 对重复的参数只保留最后一个值,除非其名称以方括号结尾([color[]])。[Django]与 [Flask]、[Spring MVC] 或 [ASP.NET Core] 一样,保留所有值——不需要方括号。事实上,对系统来说,方括号只是名称中的两个字符:[?color[]=red] 定义了一个名为 [color[]] 的参数,而 [getlist("color")] 看不到它。

验证:起初成功,随后因未知颜色而失败,再后来因空列表而失败:

1
2
3
curl "http://localhost:8000/arrays/action03?color=red&color=blue"
curl "http://localhost:8000/arrays/action03?color=red&color=black"
curl "http://localhost:8000/arrays/action03"
{
    "colors": [
        "red",
        "blue"
    ],
    "valid": true,
    "errors": []
}
{
    "colors": [
        "red",
        "black"
    ],
    "valid": false,
    "errors": [
        "black: unknown value"
    ]
}
{
    "colors": [],
    "valid": false,
    "errors": [
        "This field is required."
    ]
}

错误消息指出了不正确的值 [black]。

3.5. 示例 11:POST 请求的参数

前面的示例使用的是 GET 请求,其参数包含在 URL 中。POST 请求把数据放在请求体中,主要有两种形式:

  • HTML 表单的字段:请求体的语法与查询字符串相同([name=martin&age=42]),其类型(请求头 [Content-Type])为 [application/x-www-form-urlencoded] (或 [multipart/form-data],用于发送文件的表单);
  • 由程序发送的 JSON 文档(页面上的 [JavaScript] 、API 的客户端等):其类型为 [application/json]。

[post] 应用的视图:

# post/views.py:POST 请求的参数

import json

from django.core.exceptions import BadRequest
from django.http import HttpResponse, JsonResponse
from django.views.decorators.http import require_POST

from .binding import body_data, from_body
from .viewmodels import PersonModel


# HTML 表单的字段(application/x-www-form-urlencoded 正文):
# request.POST 包含请求正文的参数
@require_POST
def action01(request):
    return JsonResponse({
        "receivedType": request.headers.get("Content-Type"),
        "fields": request.POST.dict(),
        # 重复出现的字段:它的所有值(见示例 10)
        "hobbies": request.POST.getlist("hobby"),
    })


# JSON 正文:Django 不会解码它;request.body 包含原始正文(一些
# 字节),由 json.loads 反序列化
@require_POST
def action02(request):
    # content_type:正文的类型,读取自 Content-Type 头部
    if request.content_type != "application/json":
        return JsonResponse({"message": "the request body must be JSON"}, status=415)
    try:
        body = json.loads(request.body)
    except json.JSONDecodeError as e:
        raise BadRequest(f"malformed JSON: {e}")
    return JsonResponse({"receivedType": request.headers.get("Content-Type"), "body": body,
                         "name": body.get("name")})


# 单个字段,无论正文是表单还是 JSON 文档
@require_POST
def action03(request):
    name = body_data(request).get("name")
    return HttpResponse(f"name = [{name}]")


# 正文(表单或 JSON)绑定到 PersonModel 并验证(见示例 08)
@require_POST
@from_body(PersonModel)
def action04(request, person):
    return JsonResponse({"person": person, "valid": True})
  • 第 15、27、41、48 行:所有视图都只接受 POST 方法([require_POST] 装饰器);
  • 第 18 行:请求的 [Content-Type] 头;
  • 第 19–21 行:请求的 [POST] 属性在一个 [QueryDict] 中包含表单请求体的字段,与 [GET] 类似(示例 07 和 10):[get]、[getlist]、[dict]……对于任何其他类型的请求体,特别是 JSON 请求体,它都是空的;
  • 第 30 行:[content_type] 是请求体的类型,从请求头 [Content-Type] 中读取(不含其后可能跟随的字符集)。类型不是 JSON 的请求体会被拒绝,返回 415 错误(Unsupported Media Type);
  • 第 32–35 行:[Django] 不会解码 JSON 请求体:[body] 属性包含字节形式的原始请求体,由 [json.loads] 函数反序列化:JSON 文本变成字典(或列表、数字等)。格式错误的 JSON 会引发 [json.JSONDecodeError] 异常,由 [try] / [except] 块捕获;[as e] 为异常指定一个名称,以便把它的消息放入我们自己的消息中,返回 400 响应;
  • 第 41–44 行:从请求体数据(无论是表单还是 JSON 文档)中读取单个字段:这是 [body_data] 函数的工作,下文会予以说明;
  • 第 48–51 行:[from_body] 装饰器针对请求体,对应于示例 08 中的 [from_url] 装饰器:它根据表单字段或 JSON 文档构造一个 [PersonModel] (示例 08 中的表单),并对其进行验证。无效的模型会引发 [InvalidModel] 异常,示例 08 中的 [ValidationErrors] 中间件会把它转换为 400 响应。

[post/binding.py] 文件:

# post/binding.py:请求正文的数据,及其到模型的绑定

import json
from functools import wraps

from django.core.exceptions import BadRequest


# 当数据不符合模型的约束时抛出的异常
class InvalidModel(Exception):
    def __init__(self, form):
        super().__init__("invalid model")
        self.form = form


# 请求正文的数据,保存在字典中,无论正文是
# JSON 文档还是 HTML 表单的字段
def body_data(request):
    if request.content_type == "application/json":
        try:
            data = json.loads(request.body)
        except json.JSONDecodeError as e:
            raise BadRequest(f"malformed JSON: {e}")
        if not isinstance(data, dict):
            raise BadRequest("a JSON object is expected")
        return data
    return request.POST


# @from_body(PersonModel):示例 08 的 @from_url 装饰器
# 在请求正文方面的对应物
def from_body(model_class):
    def decorator(view):
        @wraps(view)
        def wrapper(request, *args, **kwargs):
            form = model_class(body_data(request))
            if not form.is_valid():
                raise InvalidModel(form)
            return view(request, form.cleaned_data, *args, **kwargs)
        return wrapper
    return decorator
  • 第 18–27 行:字典形式的请求体数据:解码后的 JSON 文档,或表单字段([request.POST])。不是对象的 JSON 文档(列表、数字)无法填充表单:这会导致 400 错误;
  • 第 32–41 行:装饰器,与示例 08 中的相同,只是数据来源不同(第 36 行)。[Django] 表单接受任何字典,而不仅仅是 [QueryDict]:这正是它也能验证 JSON 文档的原因。

对于 POST 请求,有一点值得注意:[Django] 接受它不需要任何额外条件,因为我们的示例尚未包含防 CSRF 保护的中间件(示例 18)。使用 [curl] 时,[-d] (data)选项发送请求体;此时请求变为 POST 请求,类型为 [application/x-www-form-urlencoded],除非 [-H] (header)选项指定了其他类型。[-X POST] 选项显式设置方法(这里它是可选的)。表单的字段,包括一个重复的字段:

curl -i -X POST -d "name=martin&age=42&hobby=tennis&hobby=piano" http://localhost:8000/post/action01
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/x-www-form-urlencoded",
    "fields": {
        "name": "martin",
        "age": "42",
        "hobby": "piano"
    },
    "hobbies": [
        "tennis",
        "piano"
    ]
}

一个 JSON 请求体,包含一个整数和一个数组:

curl -i -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": 42, \"hobbies\": [\"tennis\", \"piano\"]}" http://localhost:8000/post/action02
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/json",
    "body": {
        "name": "martin",
        "age": 42,
        "hobbies": [
            "tennis",
            "piano"
        ]
    },
    "name": "martin"
}

JSON 中的引号前面加了 [\] ,以防命令字符串提前结束;在 [Linux] 和 [macOS] 下,也可以用单引号括起 JSON:[-d '{"name": "martin"}']。与表单字段不同,JSON 携带数据类型:年龄已经是整数。先是非 JSON 的请求体,然后是格式错误的 JSON:

curl -i -d "name=martin" http://localhost:8000/post/action02
curl -i -H "Content-Type: application/json" -d "{name: martin}" http://localhost:8000/post/action02
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{
    "message": "the request body must be JSON"
}
HTTP/1.1 400 Bad Request
Content-Type: text/html

<!DOCTYPE html>
...

第二个响应是 [Django] 的错误页面,其中显示了我们的消息:[malformed JSON: Expecting property name enclosed in double quotes: line 1 column 2 (char 1)] (在 JSON 中,属性名必须用引号括起来)。单个字段,先是表单形式,然后是 JSON 形式,接着是以 GET 请求同一个 URL:

1
2
3
curl -d "name=jean%20dupont" http://localhost:8000/post/action03
curl -H "Content-Type: application/json" -d "{\"name\": \"martin\"}" http://localhost:8000/post/action03
curl -i http://localhost:8000/post/action03
1
2
3
4
5
name = [jean dupont]
name = [martin]
HTTP/1.1 405 Method Not Allowed
Content-Type: text/html; charset=utf-8
Allow: POST

该 URL 存在,但不支持 GET 方法:[Django] 返回 405(Method Not Allowed)响应,其 [Allow] 头列出了可接受的方法(示例 02)。最后是与请求体绑定的模型,先通过有效的表单,再通过无效的表单,最后通过 JSON 文档:

1
2
3
curl -d "name=martin&age=42&title=Mr" http://localhost:8000/post/action04
curl -d "name=m&age=abc&title=Mx" http://localhost:8000/post/action04
curl -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": \"42\", \"title\": \"Mr\"}" http://localhost:8000/post/action04
{
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": ""
    },
    "valid": true
}
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "Ensure this value has at least 2 characters (it has 1)."
        },
        {
            "field": "age",
            "message": "Enter a whole number."
        },
        {
            "field": "title",
            "message": "Select a valid choice. Mx is not one of the available choices."
        }
    ]
}
{
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": ""
    },
    "valid": true
}

最后一个请求把年龄作为字符串发送(["42"],用引号括起),而模型期望的是整数:表单会转换它,就像转换 HTML 表单的字段一样。[Django] 表单是为文本数据设计的;它也接受已经转换过的值(JSON 中的整数 42)。对类型要求更严格的 API 表单则会改用 [Django REST framework] 扩展,其序列化器能区分字符串 ["42"] 和整数 42。

3.6. 示例 12:自定义绑定与验证

标准的转换器和字段并不总是足够用。本示例展示了扩展绑定和验证的三种方式:

  • “自定义”路由转换器:URL 路径中法式格式的日期 [23-09-2026],以对象的形式提供给视图;
  • 中间件,它向视图提供的信息不是来自 URL,而是来自 HTTP 头;
  • 一个“自定义”验证器(不允许空格),以及使用表单方法转换 [dd/mm/yyyy] 日期。
12-custom-binding/
├── bindings/
│   ├── __init__.py
│   ├── binding.py
│   ├── converters.py
│   ├── urls.py
│   ├── validators.py
│   ├── viewmodels.py
│   └── views.py
├── config/
│   ├── middleware.py
│   ├── settings.py
│   ├── urls.py
│   └── ...
└── manage.py

3.6.1. 与路由参数关联的对象:bindings/converters.py

在示例 02 中,我们了解了 [Django] 的转换器:[int]、[str]、[slug]、[uuid]、[path]。应用可以编写自己的转换器。我们来为法式格式的日期编写一个转换器,用类 [DayFr] 表示:

# bindings/converters.py:URL 路径中的法式日期 "23-09-2026"

from dataclasses import dataclass
from datetime import date, datetime


@dataclass(frozen=True)
class DayFr:
    date: date

    # 路径文本 -> DayFr 对象;None:该文本不表示日期。
    # @classmethod:类的方法,以 DayFr.from_url(...) 的方式调用
    @classmethod
    def from_url(cls, text):
        try:
            # strptime 按格式读取日期;不存在的日期
            # ("31-02-2026")会抛出 ValueError
            return cls(datetime.strptime(text, "%d-%m-%Y").date())
        except ValueError:
            return None

    # DayFr 对象 -> 路径文本(构建路由的 URL 时使用)
    def __str__(self):
        return self.date.strftime("%d-%m-%Y")


# 一个路径转换器:Django 在两个方向上都会使用它
class DayFrConverter:
    # 路径的这一段必须匹配的正则表达式
    regex = r"[0-9]{2}-[0-9]{2}-[0-9]{4}"

    # 文本 -> 传给视图的值;ValueError:路由不匹配(404)
    def to_python(self, value):
        day = DayFr.from_url(value)
        if day is None:
            raise ValueError(f"[{value}] is not a date")
        return day

    # 值 -> 文本,当 reverse 构建路由的 URL 时
    def to_url(self, value):
        return str(value)
  • 第 7–9 行:一个不可变数据类,其唯一的属性是日期,即标准库 [date] 对象,来自 [datetime] 模块;
  • 第 13–20 行:一个类方法,用 [@classmethod] 标记:它在类上调用,如 [DayFr.from_url("23-09-2026")],并接收类本身作为第一个参数,按约定命名为 [cls] 。它根据路径文本创建一个 [DayFr] 对象,如果文本无效则返回 [None] 。[datetime.strptime] 按特定格式解析字符串:[%d] 表示日,[%m] 表示月,[%Y] 表示四位数的年;它返回一个 [datetime] 对象(日期和时间),其中 [.date()] 只保留日期。如果文本不符合格式,或者该日期不存在,它会引发 [ValueError] 异常 :2 月 31 日会被拒绝。[cls(...)] 创建该类的一个对象;
  • 第 23–24 行:逆操作。方法 [__str__] 指定如何把对象转换为字符串([str(day)],或用 f-string);[strftime] 按特定格式写出日期;
  • 第 28–41 行:转换器,一个有一个属性和两个方法的类,[Django] 通过它们的名称来识别(不需要父类:[Python] 只要求对象具有正确的属性——这称为“鸭子类型”);
  • 第 30 行:[regex] 是路径段必须匹配的正则表达式:[[0-9]] 表示一个数字,[{2}] 表示前面的模式重复:两位数字、一个连字符、两位数字、一个连字符、四位数字。格式不同的路径段与该路由不匹配。原始字符串中的前缀 [r] 指示 [Python] 不解释反斜杠,而反斜杠在正则表达式中很常见;
  • 第 33–37 行:[to_python] 把路径段的文本转换为传给视图的值。如果它引发 [ValueError],[Django] 就认为该路由不匹配,并尝试后面的路由;最终会出现 404 错误;
  • 第 40–41 行:[to_url] 执行相反的操作,而 [reverse] 则根据 [DayFr] 对象生成路由的 URL(示例 04)。

转换器在首次用于路由之前,必须以某个名称注册。文件 [config/urls.py] 就是这样做的:

# config/urls.py:主路由表

from django.urls import include, path, register_converter

from bindings.converters import DayFrConverter

# 一个"自制"的转换器,以名称 dayfr 注册:路由现在
# 可以写 <dayfr:day>,就像 <int:id> 一样
register_converter(DayFrConverter, "dayfr")

urlpatterns = [
    path("examples/", include("bindings.urls")),
]
  • 第 9 行:[register_converter] 以名称 [dayfr] 注册转换器:现在路由可以写成 [<dayfr:day>],就像 [<int:id>] 一样。

3.6.2. 由中间件提供的参数:config/middleware.py

若要向视图提供根据请求计算出的信息,也可以由中间件来计算(示例 03),并在请求到达视图之前把它插入请求中:

# config/middleware.py:示例 12 的中间件

from django.http import HttpResponse
from django.utils.translation import get_language_from_request

from bindings.binding import InvalidModel


# 一个为视图计算出一条信息的中间件
class DetectLanguage:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # 头部 "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr":浏览器在 LANGUAGES 设置的语言中
        # 偏好的语言(默认是
        # LANGUAGE_CODE 的语言)
        request.language = get_language_from_request(request)
        # Python 对象可以接受新属性:request.language 现在
        # 可供后续的中间件和视图使用
        return self.get_response(request)


# 无效的模型会产生一个 400 响应,其纯文本内容为第一个
# 错误的消息
class TextError:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    def process_exception(self, request, exception):
        if isinstance(exception, InvalidModel):
            # 第一个消息列表,及其第一条消息
            first = next(iter(exception.form.errors.values()))[0]
            return HttpResponse(first, status=400, content_type="text/plain; charset=utf-8")
        return None
  • 第 4 行:来自 [Django] 翻译模块的一个函数;
  • 第 14–21 行:中间件在视图之前运行,因为它的代码位于对 [self.get_response] 的调用之前;
  • 第 18 行:请求头 [Accept-Language] 按偏好顺序给出用户使用的语言:[fr-FR,fr;q=0.9,en;q=0.8] (系数 [q] 以 0 到 1 的刻度衡量偏好程度)。[get_language_from_request] 从应用支持的语言(设置 [LANGUAGES],位于文件 [config/settings.py] 的第 24–27 行)中选出用户偏好的那一种;如果没有该请求头,或者没有合适的语言,则默认使用设置 [LANGUAGE_CODE] 中指定的语言。中间件把该语言存放在请求的一个新属性 [language] 中:[Python] 对象可以随时添加属性。[Django] 自己就是这样向视图提供信息的:[request.user] (已登录的用户)、[request.session] (会话)、[request.LANGUAGE_CODE] (语言)……都是由中间件添加的;
  • 第 26–38 行:验证失败时的响应。我们希望它与示例 08 中的不同:以纯文本返回第一个错误的消息,状态码为 400。[errors.values()] 遍历各个消息列表;[iter] 返回这些列表上的迭代器,[next] 从中取出第一个;[[0]] 指该列表中的第一条消息。

中间件会对所有请求运行。只应对某些视图起作用的中间件,要自己检查请求路径([request.path]),或者在其 [process_view] 方法(见关于生命周期的一章)中检查即将被调用的视图。对于单个视图,使用装饰器更合适,例如 [from_url]。至于视图,它会在请求中找到这些信息(见“视图”)。

3.6.3. “自定义”验证器与转换:validators.py 和 viewmodels.py

验证器是一个函数,它接收字段的值(已经转换过),如果值无效,就抛出 [ValidationError] 异常:

# bindings/validators.py:"自制"的验证约束

from django.core.exceptions import ValidationError


# 一个验证器:接收字段值的函数,若值不合适
# 则抛出 ValidationError
def no_space(value):
    if " " in value:
        raise ValidationError("the field must not contain any space", code="space")
  • 第 8–10 行:[in] 运算符检查字符串中是否存在某段文本。[ValidationError] 是 [Django] 自己的字段所抛出的异常;它的参数 [code] ([space]) 允许表单用 [error_messages] 替换消息,类似于 [Django] 的代码(示例 09)。只有在值存在时才会调用验证器:值是否缺失由字段的 [required] 参数处理。

该验证器由搜索模型使用:

# bindings/viewmodels.py:搜索的模型

from datetime import datetime

from django import forms
from django.core.exceptions import ValidationError

from .validators import no_space


class SearchModel(forms.Form):
    # 一个"自制"的约束:validators,字段的验证器列表
    keyword = forms.CharField(required=False, validators=[no_space])
    # dd/mm/yyyy 格式的日期,以字符串形式接收……
    since = forms.CharField(required=False)

    # ……并由 clean_since 方法转换,Django 在字段的
    # 检查之后调用该方法:其返回值成为 cleaned_data["since"] 的值
    def clean_since(self):
        text = self.cleaned_data["since"]
        if not text:
            return None
        try:
            return datetime.strptime(text, "%d/%m/%Y").date()
        except ValueError:
            raise ValidationError(f"{text} is not a valid dd/mm/yyyy date")
  • 第 13 行:字段的 [validators] 参数是其“自定义”验证器的列表,它们在字段自身的检查之后被调用。[Django] 在 [django.core.validators] 模块中提供了预定义的验证器:[RegexValidator]、[MinValueValidator]、[URLValidator]……;
  • 第 15 行:日期以字符串形式接收。[DateField] 本可以自己完成转换(使用 [input_formats=["%d/%m/%Y"]]);我们改为手动转换,以演示另一种做法;
  • 第 19–26 行:名为 [clean_] 加字段名的方法,会在字段检查之后由 [is_valid()] 调用。它从 [self.cleaned_data] 中取得字段的值;它的返回值会取代该值,而它引发的 [ValidationError] 会成为字段错误。这里,它把字符串转换为日期:视图将收到一个有效的日期。这是为字段添加规则或自定义转换的最常见方式;对于适用于多个字段的规则,则要重写表单的 [clean] 方法(示例 19)。

3.6.4. 视图:bindings/views.py

# bindings/views.py:自定义绑定和验证

from django.http import HttpResponse
from django.urls import reverse
from django.views.decorators.http import require_GET

from .binding import from_url
from .viewmodels import SearchModel


# /examples/schedule/23-09-2026:day 参数是一个 DayFr 对象,由
# 路由的转换器构建
@require_GET
def schedule(request, day):
    # reverse 构建路由的 URL;DayFr 对象通过转换器的
    # to_url 方法变成路径文本:"23-09-2026"
    url = reverse("bindings:schedule", kwargs={"day": day})
    return HttpResponse(f"schedule for the day [{day.date.isoformat()}], of type "
                        f"{type(day.date).__name__}, URL: {url}")


# /examples/hello:一条信息,它不来自 URL,而来自头部,
# 由 DetectLanguage 中间件计算并存储在请求中
@require_GET
def hello(request):
    return HttpResponse("Hello!" if request.language == "en" else "Bonjour !")


# /examples/search?keyword=django&since=01/09/2026
@require_GET
@from_url(SearchModel)
def search(request, search):
    since = search["since"].isoformat() if search["since"] else None
    return HttpResponse(f"search for [{search['keyword']}] since [{since}]")
  • 第 14–19 行:视图接收转换器生成的 [DayFr] 对象。它以国际格式显示日期([isoformat()]:[2026-09-23]),并显示路由的 URL,该 URL 由 [reverse] (示例 04)以 [DayFr] 对象为参数生成:[Django] 使用转换器的 [to_url] 方法把它转换为文本。该 URL 是相对于站点的([/examples/...]);[request.build_absolute_uri(url)] 可以把它变成绝对 URL。括号内并排书写的两个 f-string 会被 [Python] 拼接成一个字符串;
  • 第 25–26 行:视图读取由 [DetectLanguage] 中间件计算出的信息。[a if condition else b] 是 [Python] 的条件表达式;
  • 第 30–34 行:查询模型,与 URL 的参数绑定,并由示例 08 中的装饰器进行验证(文件 [bindings/binding.py])。视图只接收有效的模型;日期已经是 [date] 或 [None] 对象。

3.6.5. 执行

与路由参数关联的对象:

1
2
3
curl "http://localhost:8000/examples/schedule/23-09-2026"
curl -i "http://localhost:8000/examples/schedule/31-02-2026"
curl -i "http://localhost:8000/examples/schedule/2026-09-23"
1
2
3
4
5
6
7
schedule for the day [2026-09-23], of type date, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
...
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
...

日期以国际格式显示,但由 [reverse] 构造的 URL 对象又回到了法式格式。2 月 31 日不存在:返回 404,因为我们的转换器拒绝了该路径段。国际格式的日期 [2026-09-23] 与正则表达式描述的模式不匹配:同样返回 404,甚至不会调用 [to_python]。在这两种情况下,[Django] 的错误页面都会列出各条路由,包括 [examples/ schedule/<dayfr:day>]。

中间件。[curl] 的 [-H] 选项设置 [Accept-Language] 请求头:

1
2
3
curl -H "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" http://localhost:8000/examples/hello
curl -H "Accept-Language: de-DE,de;q=0.9" http://localhost:8000/examples/hello
curl http://localhost:8000/examples/hello
1
2
3
Bonjour !
Hello!
Hello!

[fr-FR] 不在应用的语言列表中,但 [Django] 可以回退到通用语言 [fr]。 德语则完全不在其中,而且 [curl] 不发送 [Accept-Language] 请求头:在这两种情况下,使用的都是设置中指定的语言([LANGUAGE_CODE])。国际化一章将通过让用户选择语言来解决这个问题。

“自制”验证器与日期转换:

1
2
3
4
curl "http://localhost:8000/examples/search?keyword=django&since=01/09/2026"
curl -i "http://localhost:8000/examples/search?keyword=key%20word&since=31/02/2026"
curl "http://localhost:8000/examples/search?since=31/02/2026"
curl "http://localhost:8000/examples/search"
1
2
3
4
5
6
7
search for [django] since [2026-09-01]
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

the field must not contain any space
31/02/2026 is not a valid dd/mm/yyyy date
search for [] since [None]

第二个请求包含两个错误;中间件只返回第一个,即与关键字相关的那个。不带任何参数时,模型是有效的:它的两个字段都是可选的。

3.6.6. 结论

我们来总结一下视图获取其模型的各种方法:

来源
方法
路由参数
视图的参数,名称与之相同;由转换器转换([<int:id>]);“自定义”转换器([regex]、[to_python]、[to_url]、[register_converter])把它们与一个对象关联起来
URL 参数
[request.GET.get(...)]、[getlist]、[dict];重复的参数会保留其所有值
POST 表单中的字段
[request.POST.get(...)]、[getlist]、[dict]
JSON 请求体
[json.loads(request.body)],在验证 [request.content_type] 之后
用类描述的模型
一个 [Django] ([forms.Form])表单:对每个字段进行转换和验证([is_valid]、[cleaned_data]、[errors]);用装饰器在视图之前执行这一过程
请求头
[request.headers.get(...)],以及解析它们的函数,如 [get_language_from_request]
验证
字段参数([required]、[min_length]、[min_value]……);“自定义”验证器([validators]、[ValidationError]);方法 [clean_<field>] 和 [clean]
消息
语言 [LANGUAGE_CODE],[Django] 的翻译;字段的 [error_messages] 参数
常见错误
中间件及其 [process_exception] 方法
计算得出的信息
一个中间件组件,它把该信息添加到请求中([request.language])

而 HTML 表单所需要的不只是验证:它们必须被显示出来,带着用户的输入和错误重新显示,并且要防范伪造的请求。[Django] 表单借助模板就能完成所有这些工作。这就是下一章的主题。