验证器是一个可调用对象,它接受一个值,如果不符合某些条件,则会引发 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,它将在你的表单中包含的任何字段上运行验证器。请参阅 模型表单文档,了解模型验证如何与表单交互。
django.core.validators 模块包含了一系列用于模型和表单字段的可调用验证器。它们是内部使用的,但也可以用于你自己的字段。它们可以作为自定义 field.clean() 方法的补充,也可以代替这些方法。
RegexValidator¶一个 RegexValidator 用 re.search() 为给定的正则表达式搜索提供的 value。默认情况下,如果没有 找到 匹配的,会引发一个 ValidationError,包含 message 和 code。它的行为可以通过将 inverse_match 设置为 True 来反转,在这种情况下,当 找到 匹配的时,就会引发 ValidationError。
使用 re.search() 在提供的 value 中搜索的正则表达式模式。可以是一个字符串,也可以是用 re.compile() 创建的预先编译的正则表达式。默认为空字符串,将在所有可能的 value 中找到。
当验证失败时 ValidationError 使用的错误信息。默认值为 "Enter a valid value"。
ValidationError 验证失败时使用的错误代码。默认值为 "invalid"。
EmailValidator¶EmailValidator 确保一个值看起来像一个电子邮件,并且如果不是,则引发带有 message 和 code 的 ValidationError。长度超过 320 个字符的值总是被认为是无效的。
如果验证失败, ValidationError 使用的错误信息。默认为 "Enter a valid email address"。
ValidationError 验证失败时使用的错误代码。默认值为 "invalid"。
电子邮件域名的允许列表。默认情况下,会使用正则表达式(domain_regex 属性)来验证出现在 @ 符号后面的内容。但是,如果该字符串出现在 allowlist 中,将绕过此验证。如果未提供,默认的 allowlist 是 ['localhost']。其他不包含点的域名将无法通过验证,因此您需要根据需要将它们添加到 allowlist 中。
DomainNameValidator¶一个 RegexValidator 子类,用于确保值看起来像域名。超过 255 个字符的值始终被视为无效。IP 地址不被接受为有效的域名。
除了其父类 RegexValidator 的可选参数外,DomainNameValidator 还接受一个额外的可选属性:
确定是否接受国际化域名,即包含非 ASCII 字符的域名。默认为 True。
URLValidator¶RegexValidator 的子类,用于确保一个值看起来像一个 URL,如果不是,则引发错误代码为 'invalid' 的错误。长度超过 max_length 字符的值总是被视为无效。
回环地址和保留的 IP 空间被认为是有效的。字面 IPv6 地址(RFC 3986 Section 3.2.2)和 Unicode 域都支持。
除了它的父类 RegexValidator 的可选参数外,URLValidator 还接受一个额外的可选属性:
要验证的 URL/URI 协议列表。如果没有提供,默认列表是 ['http', 'https', 'ftp', 'ftps']。作为参考,IANA 网站提供了一个完整的 有效 URI 协议 列表。
Warning
以 file:/// 开头的值即使提供了 file 方案也不会通过验证。有效值必须包含主机信息。
可以被视为有效的值的最大长度。默认为 2048 个字符。
validate_email¶一个 EmailValidator 实例,没有任何自定义。
validate_domain_name¶一个没有任何自定义的 DomainNameValidator 实例。
validate_slug¶一个 RegexValidator 实例,确保一个值只由字母、数字、下划线或连字符组成。
validate_unicode_slug¶一个 RegexValidator 实例,确保一个值只由 Unicode 字母、数字、下划线或连字符组成。
validate_ipv4_address¶一个 RegexValidator 实例,确保一个值看起来像一个 IPv4 地址。
validate_ipv6_address¶validate_ipv46_address¶validate_comma_separated_integer_list¶一个 RegexValidator 实例,确保一个值是一个逗号分隔的整数列表。
int_list_validator¶返回一个 RegexValidator 实例,以确保字符串由 sep 分隔的整数组成。当 allow_negative 为 True 时,它允许负整数。
MaxValueValidator¶如果 value 大于 limit_value,会引发一个 ValidationError,代码为 'max_value',这可能是一个可调用对象。
MinValueValidator¶如果 value 小于 limit_value,会引发一个 ValidationError,代码为 'min_value',这可能是一个可调用对象。
MaxLengthValidator¶如果 value 的长度大于 limit_value,会引发一个 ValidationError,代码为 'max_length'。
MinLengthValidator¶如果 value 小于 limit_value,会引发一个 ValidationError,代码为 'min_length',这可能是一个可调用对象。
DecimalValidator¶引发 ValidationError,代码如下:
'max_digits',如果数字数量大于 max_digits。
'max_decimal_places',如果小数的数量大于 decimal_places。
'max_whole_digits',如果整数位数大于 max_digits 和 decimal_places 之间的差值。
FileExtensionValidator¶如果 value.name (value 是一个 File`)的扩展名没有在 allowed_extensions 中找到,会引发一个 ValidationError,代码为 'invalid_extension'。该扩展名将与 allowed_extensions 进行不区分大小写的比较。
Warning
不要依赖文件扩展名的验证来确定文件的类型。文件可以重命名为任何扩展名,无论它们包含什么数据。
validate_image_file_extension¶使用 Pillow 确保 value.name (value 是一个 File)具有 一个有效的图像扩展名 。
ProhibitNullCharactersValidator¶如果 str(value) 包含一个或多个空字符('\x00'),则引发 ValidationError。
如果验证失败, ValidationError 使用的错误信息。默认值为 "Null characters are not allowed."。
当验证失败时 ValidationError 所使用的错误代码。默认为 "null_characters_not_allowed"。
StepValueValidator¶如果 value 不是 limit_value 的整数倍,其中 limit_value 可以是浮点数、整数、小数值或可调用对象,则会引发一个代码为 'step_size' 的 ValidationError。当设置了 offset 时,验证将针对 limit_value 加上 offset 进行。例如,对于 StepValueValidator(3, offset=1.4),有效的值包括 1.4、4.4、7.4、10.4 等等。
6月 18, 2025