验证器

编写验证器

验证器是一个可调用对象，它获取一个值，如果该值不满足某些条件，则引发 ValidationError。验证器对于在不同类型的字段之间重用验证逻辑非常有用。

例如，这是一个仅允许偶数的验证器

from django.core.exceptions import ValidationError
from django.utils.translation import gettext_lazy as _


def validate_even(value):
    if value % 2 != 0:
        raise ValidationError(
            _("%(value)s is not an even number"),
            params={"value": value},
        )

你可以通过字段的 validators 参数将此验证器添加到模型字段

from django.db import models


class MyModel(models.Model):
    even_field = models.IntegerField(validators=[validate_even])

由于在运行验证器之前，值已转换为 Python，因此你甚至可以在表单中使用相同的验证器

from django import forms


class MyForm(forms.Form):
    even_field = forms.IntegerField(validators=[validate_even])

您还可以使用带有 __call__() 方法的类来实现更复杂或可配置的验证器。例如，RegexValidator 就使用了此技术。如果在 validators 模型字段选项中使用了基于类的验证器，则应确保它可以通过添加 deconstruct() 和 __eq__() 方法来实现 迁移框架可序列化。

如何运行验证器

有关如何在表单中运行验证器的更多信息，请参阅 表单验证；有关如何在模型中运行验证器的更多信息，请参阅 验证对象。请注意，在保存模型时不会自动运行验证器，但如果您正在使用 ModelForm，它将在表单中包含的任何字段上运行您的验证器。有关模型验证如何与表单交互的信息，请参阅 ModelForm 文档。

内置验证器

django.core.validators 模块包含一组可调用的验证器，可用于模型和表单字段。它们在内部使用，但也可用于您自己的字段。它们可以与自定义 field.clean() 方法一起使用，也可以代替它们。

RegexValidator

class RegexValidator(regex=None, message=None, code=None, inverse_match=None, flags=0)
参数
  • regex – 如果不为 None，则覆盖 regex。可以是正则表达式字符串或预编译的正则表达式。
  • message – 如果不为 None，则覆盖 message。
  • code – 如果不为 None，则覆盖 code。
  • inverse_match – 如果不为 None，则覆盖 inverse_match。
  • flags – 如果不为 None，则覆盖 flags。在这种情况下，regex 必须是正则表达式字符串，否则会引发 TypeError。

一个 RegexValidator 使用 re.search() 在提供的 value 中搜索给定的正则表达式。默认情况下，如果未找到匹配项，则会引发带有 message 和 code 的 ValidationError。可以通过将 inverse_match 设置为 True 来反转其行为，在这种情况下，当找到匹配项时，会引发 ValidationError。

regex

使用 re.search() 在提供的 value 中搜索的正则表达式模式。这可以是一个字符串或使用 re.compile() 创建的预编译正则表达式。默认为空字符串，它将在每个可能的 value 中找到。

message

如果验证失败，ValidationError 使用的错误消息。默认为 "Enter a valid value"。

code

如果验证失败，ValidationError 使用的错误代码。默认为 "invalid"。

inverse_match

regex 的匹配模式。默认为 False。

flags

编译正则表达式字符串 regex 时使用的 regex 标志。如果 regex 是预编译的正则表达式，并且 flags 被覆盖，则会引发 TypeError。默认为 0。

EmailValidator

类 EmailValidator(message=None, code=None, allowlist=None)
参数
  • message – 如果不是 None，则覆盖 message。
  • code – 如果不是 None，则覆盖 code。
  • allowlist – 如果不是 None，则覆盖 allowlist。

一个 EmailValidator 确保一个值看起来像电子邮件，并且如果它不像电子邮件，则会引发一个 ValidationError，其中包含 message 和 code。长度超过 320 个字符的值始终被认为无效。

message

如果验证失败，ValidationError 使用的错误消息。默认为 "Enter a valid email address"。

code

如果验证失败，ValidationError 使用的错误代码。默认为 "invalid"。

allowlist

电子邮件域的允许列表。默认情况下，正则表达式（domain_regex 属性）用于验证 @ 符号后出现的任何内容。但是，如果该字符串出现在 allowlist 中，则会绕过此验证。如果没有提供，则默认 allowlist 为 ['localhost']。其他不包含点的域将无法通过验证，因此您需要根据需要将它们添加到 allowlist 中。

在 Django 3.2.20 中更改

在较旧版本中，长度超过 320 个字符的值可能被认为有效。

URLValidator

class URLValidator(schemes=None, regex=None, message=None, code=None)

一个 RegexValidator 子类，用于确保一个值看起来像一个 URL，如果它不像一个 URL，则会引发错误代码 'invalid'。长度超过 max_length 字符的值始终被认为是无效的。

回送地址和保留的 IP 空间被视为有效的。文字 IPv6 地址 (RFC 3986#section-3.2.2) 和 Unicode 域都受支持。

除了其父 RegexValidator 类的可选参数之外，URLValidator 还接受一个额外的可选属性

schemes

要验证的 URL/URI 方案列表。如果未提供，则默认列表为 ['http', 'https', 'ftp', 'ftps']。作为参考，IANA 网站提供了 有效 URI 方案 的完整列表。

警告

即使提供了 file 方案，以 file:/// 开头的值也不会通过验证。有效值必须包含主机。

max_length
Django 3.2.20 中的新增功能。

可以视为有效的最大值长度。默认为 2048 个字符。

在 Django 3.2.20 中更改

在较旧版本中，长度超过 2048 个字符的值可以被视为有效值。

validate_email

validate_email

一个没有进行任何自定义的 EmailValidator 实例。

validate_slug

validate_slug

一个 RegexValidator 实例，它确保一个值仅由字母、数字、下划线或连字符组成。

validate_unicode_slug

validate_unicode_slug

一个 RegexValidator 实例，它确保一个值仅由 Unicode 字母、数字、下划线或连字符组成。

validate_ipv4_address

validate_ipv4_address

一个 RegexValidator 实例，它确保一个值看起来像一个 IPv4 地址。

validate_ipv6_address

validate_ipv6_address

使用 django.utils.ipv6 检查 IPv6 地址的有效性。

validate_ipv46_address

validate_ipv46_address

同时使用 validate_ipv4_address 和 validate_ipv6_address 来确保一个值是一个有效的 IPv4 或 IPv6 地址。

validate_comma_separated_integer_list

validate_comma_separated_integer_list

一个 RegexValidator 实例，它确保一个值是一个用逗号分隔的整数列表。

int_list_validator

int_list_validator(sep=',', message=None, code='invalid', allow_negative=False)

返回一个 RegexValidator 实例，该实例确保字符串由 sep 分隔的整数组成。当 allow_negative 为 True 时，它允许负整数。

MaxValueValidator

class MaxValueValidator(limit_value, message=None)

如果 value 大于 limit_value（可以是可调用的），则引发代码为 'max_value' 的 ValidationError。

MinValueValidator

class MinValueValidator(limit_value, message=None)

如果 value 小于 limit_value（可以是可调用对象），则引发带有 'min_value' 代码的 ValidationError。

MaxLengthValidator

class MaxLengthValidator(limit_value, message=None)

如果 value 的长度大于 limit_value（可以是可调用对象），则引发带有 'max_length' 代码的 ValidationError。

MinLengthValidator

class MinLengthValidator(limit_value, message=None)

如果 value 的长度小于 limit_value（可以是可调用对象），则引发带有 'min_length' 代码的 ValidationError。

DecimalValidator

class DecimalValidator(max_digits, decimal_places)

引发 ValidationError，其中包含以下代码

  • 'max_digits' 如果数字的位数大于 max_digits。
  • 'max_decimal_places' 如果小数的位数大于 decimal_places。
  • 'max_whole_digits' 如果整数的位数大于 max_digits 和 decimal_places 之间的差值。

FileExtensionValidator

class FileExtensionValidator(allowed_extensions, message, code)

引发 ValidationError，其中包含代码 'invalid_extension'，如果 value.name 的扩展名（value 是 File）未在 allowed_extensions 中找到。扩展名与 allowed_extensions 进行不区分大小写的比较。

警告

不要依赖文件扩展名的验证来确定文件的类型。文件可以重命名为具有任何扩展名，无论它们包含什么数据。

validate_image_file_extension

validate_image_file_extension

使用 Pillow 确保 value.name (value 是 File) 具有 有效的图像扩展名。

ProhibitNullCharactersValidator

class ProhibitNullCharactersValidator(message=None, code=None)

如果 str(value) 包含一个或多个空字符 ('\x00')，则引发 ValidationError。

参数
  • message – 如果不是 None，则覆盖 message。
  • code – 如果不是 None，则覆盖 code。
message

如果验证失败，ValidationError 使用的错误消息。默认为 "Null characters are not allowed."。

code

如果验证失败，ValidationError 使用的错误代码。默认为 "null_characters_not_allowed"。

StepValueValidator

class StepValueValidator(limit_value, message=None, offset=None)

如果 value 不是 limit_value 的整数倍，则引发代码为 'step_size' 的 ValidationError，其中 limit_value 可以是浮点数、整数或十进制值或可调用对象。设置 offset 时，验证相对于 limit_value 加 offset 进行。例如，对于 StepValueValidator(3, offset=1.4)，有效值包括 1.4、4.4、7.4、10.4 等。

Django 5.0 中已更改

添加了 offset 参数。

Django 实用工具
内置视图
返回顶部