验证器

编写验证器

验证器是一个可调用对象，它接收一个值，并在该值不满足某些条件时引发 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)[source]
参数：

  • 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

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

message

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

code

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

inverse_match

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

flags

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

EmailValidator

class EmailValidator(message=None, code=None, allowlist=None)[source]
参数：

  • message – 如果不为 None，则覆盖 message。

  • code – 如果不为 None，则覆盖 code。

  • allowlist – 如果不为 None，则覆盖 allowlist。

EmailValidator 确保值看起来像电子邮件，如果值不符合要求，则会使用 message 和 code 抛出 ValidationError。长度超过 320 个字符的值始终被视为无效。

message

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

code

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

allowlist

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

DomainNameValidator

Django 5.1 中新增。
class DomainNameValidator(accept_idna=True, message=None, code=None)[source]

RegexValidator 的子类，用于确保值看起来像域名。长度超过 255 个字符的值始终被视为无效。IP 地址不被视为有效的域名。

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

accept_idna

确定是否接受国际化域名，即包含非 ASCII 字符的域名。默认为 True。

URLValidator

class URLValidator(schemes=None, regex=None, message=None, code=None)[source]

RegexValidator 的子类，用于确保值看起来像 URL，如果不符合要求，则会抛出错误代码 'invalid'。长度超过 max_length 个字符的值始终被视为无效。

环回地址和保留的 IP 空间被视为有效。字面 IPv6 地址（RFC 3986 第 3.2.2 节）和 Unicode 域名都受支持。

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

schemes

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

警告

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

max_length

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

validate_email

validate_email

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

validate_domain_name

Django 5.1 中新增。
validate_domain_name

一个没有任何自定义的 DomainNameValidator 实例。

validate_slug

validate_slug

一个 RegexValidator 实例，用于确保值仅包含字母、数字、下划线或连字符。

validate_unicode_slug

validate_unicode_slug

一个 RegexValidator 实例，用于确保值仅包含 Unicode 字母、数字、下划线或连字符。

validate_ipv4_address

validate_ipv4_address[source]

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

validate_ipv6_address

validate_ipv6_address[source]

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

validate_ipv46_address

validate_ipv46_address[source]

同时使用 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)[source]

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

MaxValueValidator

class MaxValueValidator(limit_value, message=None)[source]

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

MinValueValidator

class MinValueValidator(limit_value, message=None)[source]

如果 value 小于 limit_value（可能是一个可调用对象），则引发一个代码为 'min_value' 的 ValidationError。

MaxLengthValidator

class MaxLengthValidator(limit_value, message=None)[source]

如果 value 的长度大于 limit_value（可能是一个可调用对象），则引发一个代码为 'max_length' 的 ValidationError。

MinLengthValidator

class MinLengthValidator(limit_value, message=None)[source]

如果 value 的长度小于 limit_value（可能是一个可调用对象），则引发一个代码为 'min_length' 的 ValidationError。

DecimalValidator

class DecimalValidator(max_digits, decimal_places)[source]

引发以下代码的 ValidationError

  • 'max_digits' 如果数字位数大于 max_digits。

  • 'max_decimal_places' 如果小数位数大于 decimal_places。

  • 'max_whole_digits' 如果整数位数大于 max_digits 和 decimal_places 的差值。

FileExtensionValidator

class FileExtensionValidator(allowed_extensions, message, code)[source]

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

警告

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

validate_image_file_extension

validate_image_file_extension[source]

使用 Pillow 确保 value.name（value 是一个 File）具有 有效的图像扩展名。

ProhibitNullCharactersValidator

class ProhibitNullCharactersValidator(message=None, code=None)[source]

如果 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)[source]

如果 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 工具
内置视图
返回顶部