--- title: "验证器" version: 5.0 locale: zh-hans source: https://docs.djangoproject.com/zh-hans/5.0/ref/validators/ canonical: https://djangodocs.dev/zh-hans/5.0/ref/validators/ --- # 验证器 ## 编写验证器 验证器是一个可调用对象，它接受一个值，如果不符合某些条件，则会引发 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.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`](/zh-hans/5.0/ref/models/fields/#django.db.models.Field.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`](#django.core.validators.RegexValidator)，例如，使用了这种技术。如果在 [`validators`](/zh-hans/5.0/ref/models/fields/#django.db.models.Field.validators) 模型字段选项中使用了一个基于类的验证器，你应该通过添加 [deconstruct()](/zh-hans/5.0/topics/migrations/#custom-deconstruct-method) 和 `__eq__()` 方法来确保它是 [可由迁移框架序列化](/zh-hans/5.0/topics/migrations/#migration-serializing)。 ## 如何运行验证器 请参阅 [表单验证器](/zh-hans/5.0/ref/forms/validation/) 了解更多关于表单中如何运行验证器的信息，以及 [验证对象](/zh-hans/5.0/ref/models/instances/#validating-objects) 了解模型中如何运行验证器。请注意，当你保存模型时，验证器不会自动运行，但如果你使用的是 [`ModelForm`](/zh-hans/5.0/topics/forms/modelforms/#django.forms.ModelForm)，它将在你的表单中包含的任何字段上运行验证器。请参阅 [模型表单文档](/zh-hans/5.0/topics/forms/modelforms/)，了解模型验证如何与表单交互。 ## 内置验证器 [`django.core.validators`](#module-django.core.validators) 模块包含了一系列用于模型和表单字段的可调用验证器。它们是内部使用的，但也可以用于你自己的字段。它们可以作为自定义 `field.clean()` 方法的补充，也可以代替这些方法。 ### `RegexValidator` #### `class RegexValidator(regex=None, message=None, code=None, inverse_match=None, flags=0)` **参数:** - `regex` -- 如果不是 `None`，则覆盖 [`regex`](#django.core.validators.RegexValidator.regex)。可以是一个正则表达式字符串或预先编译的正则表达式。 - `message` -- 如果不是 `None`，则覆盖 [`message`](#django.core.validators.RegexValidator.message)。 - `code` -- 如果不是 `None`，则覆盖 [`code`](#django.core.validators.RegexValidator.code)。 - `inverse_match` -- 如果不是 `None`，则覆盖 [`inverse_match`](#django.core.validators.RegexValidator.inverse_match)。 - `flags` -- 如果不是 `None`，则覆盖 [`flags`](#django.core.validators.RegexValidator.flags)。在这种情况下， [`regex`](#django.core.validators.RegexValidator.regex) 必须是一个正则表达式字符串，否则会引发 [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError)。 一个 [`RegexValidator`](#django.core.validators.RegexValidator) 用 [`re.search()`](https://docs.python.org/3/library/re.html#re.search) 为给定的正则表达式搜索提供的 `value`。默认情况下，如果没有 **找到** 匹配的，会引发一个 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)，包含 [`message`](#django.core.validators.RegexValidator.message) 和 [`code`](#django.core.validators.RegexValidator.code)。它的行为可以通过将 [`inverse_match`](#django.core.validators.RegexValidator.inverse_match) 设置为 `True` 来反转，在这种情况下，当 **找到** 匹配的时，就会引发 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)。 #### `regex` 使用 [`re.search()`](https://docs.python.org/3/library/re.html#re.search) 在提供的 `value` 中搜索的正则表达式模式。可以是一个字符串，也可以是用 [`re.compile()`](https://docs.python.org/3/library/re.html#re.compile) 创建的预先编译的正则表达式。默认为空字符串，将在所有可能的 `value` 中找到。 #### `message` 当验证失败时 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError) 使用的错误信息。默认值为 `"Enter a valid value"`。 #### `code` [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError) 验证失败时使用的错误代码。默认值为 `"invalid"`。 #### `inverse_match` [`regex`](#django.core.validators.RegexValidator.regex) 的匹配模式。默认为 `False`。 #### `flags` 在编译正则表达式字符串 [`regex`](#django.core.validators.RegexValidator.regex) 时使用的 [regex flags](https://docs.python.org/3/library/re.html#contents-of-module-re)。如果 [`regex`](#django.core.validators.RegexValidator.regex) 是一个预先编译的正则表达式，并且 [`flags`](#django.core.validators.RegexValidator.flags) 被覆盖，则 [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError) 被引发。默认值为 `0`。 ### `EmailValidator` #### `class EmailValidator(message=None, code=None, allowlist=None)` **参数:** - `message` -- 如果不是 `None`，则覆盖 [`message`](#django.core.validators.EmailValidator.message)。 - `code` -- 如果不是 `None`，则覆盖 [`code`](#django.core.validators.EmailValidator.code)。 - `allowlist` -- 如果不是 `None`，则覆盖 [`allowlist`](#django.core.validators.EmailValidator.allowlist)。 [`EmailValidator`](#django.core.validators.EmailValidator) 确保一个值看起来像一个电子邮件，并且如果不是，则引发带有 [`message`](#django.core.validators.EmailValidator.message) 和 [`code`](#django.core.validators.EmailValidator.code) 的 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)。长度超过 320 个字符的值总是被认为是无效的。 #### `message` 如果验证失败， [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError) 使用的错误信息。默认为 `"Enter a valid email address"`。 #### `code` [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError) 验证失败时使用的错误代码。默认值为 `"invalid"`。 #### `allowlist` 电子邮件域名的允许列表。默认情况下，会使用正则表达式（`domain_regex` 属性）来验证出现在 `@` 符号后面的内容。但是，如果该字符串出现在 `allowlist` 中，将绕过此验证。如果未提供，默认的 `allowlist` 是 `['localhost']`。其他不包含点的域名将无法通过验证，因此您需要根据需要将它们添加到 `allowlist` 中。 > **Changed in Django 3.2.20** > > 在旧版本中，长度超过 320 个字符的值可能被视为有效。 ### `URLValidator` #### `class URLValidator(schemes=None, regex=None, message=None, code=None)` [`RegexValidator`](#django.core.validators.RegexValidator) 的子类，用于确保一个值看起来像一个 URL，如果不是，则引发错误代码为 `'invalid'` 的错误。长度超过 [`max_length`](#django.core.validators.URLValidator.max_length) 字符的值总是被视为无效。 回环地址和保留的 IP 空间被认为是有效的。字面 IPv6 地址（[**RFC 3986 Section 3.2.2**](https://datatracker.ietf.org/doc/html/rfc3986.html#section-3.2.2)）和 Unicode 域都支持。 除了它的父类 [`RegexValidator`](#django.core.validators.RegexValidator) 的可选参数外，`URLValidator` 还接受一个额外的可选属性： #### `schemes` 要验证的 URL／URI 协议列表。如果没有提供，默认列表是 `['http', 'https', 'ftp', 'ftps']`。作为参考，IANA 网站提供了一个完整的 [有效 URI 协议](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml) 列表。 > **Warning** > > 以 `file:///` 开头的值即使提供了 `file` 方案也不会通过验证。有效值必须包含主机信息。 #### `max_length` > **New in Django 3.2.20** 可以被视为有效的值的最大长度。默认为 2048 个字符。 > **Changed in Django 3.2.20** > > 在旧版本中，长度超过 2048 个字符的值可能被视为有效。 ### `validate_email` #### `validate_email` 一个 [`EmailValidator`](#django.core.validators.EmailValidator) 实例，没有任何自定义。 ### `validate_slug` #### `validate_slug` 一个 [`RegexValidator`](#django.core.validators.RegexValidator) 实例，确保一个值只由字母、数字、下划线或连字符组成。 ### `validate_unicode_slug` #### `validate_unicode_slug` 一个 [`RegexValidator`](#django.core.validators.RegexValidator) 实例，确保一个值只由 Unicode 字母、数字、下划线或连字符组成。 ### `validate_ipv4_address` #### `validate_ipv4_address` 一个 [`RegexValidator`](#django.core.validators.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`](#django.core.validators.RegexValidator) 实例，确保一个值是一个逗号分隔的整数列表。 ### `int_list_validator` #### `int_list_validator(sep=',', message=None, code='invalid', allow_negative=False)` 返回一个 [`RegexValidator`](#django.core.validators.RegexValidator) 实例，以确保字符串由 `sep` 分隔的整数组成。当 `allow_negative` 为 `True` 时，它允许负整数。 ### `MaxValueValidator` #### `class MaxValueValidator(limit_value, message=None)` 如果 `value` 大于 `limit_value`，会引发一个 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)，代码为 `'max_value'`，这可能是一个可调用对象。 ### `MinValueValidator` #### `class MinValueValidator(limit_value, message=None)` 如果 `value` 小于 `limit_value`，会引发一个 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)，代码为 `'min_value'`，这可能是一个可调用对象。 ### `MaxLengthValidator` #### `class MaxLengthValidator(limit_value, message=None)` 如果 `value` 的长度大于 `limit_value`，会引发一个 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)，代码为 `'max_length'`。 ### `MinLengthValidator` #### `class MinLengthValidator(limit_value, message=None)` 如果 `value` 小于 `limit_value`，会引发一个 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)，代码为 `'min_length'`，这可能是一个可调用对象。 ### `DecimalValidator` #### `class DecimalValidator(max_digits, decimal_places)` 引发 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)，代码如下： - `'max_digits'`，如果数字数量大于 `max_digits`。 - `'max_decimal_places'`，如果小数的数量大于 `decimal_places`。 - `'max_whole_digits'`，如果整数位数大于 `max_digits` 和 `decimal_places` 之间的差值。 ### `FileExtensionValidator` #### `class FileExtensionValidator(allowed_extensions, message, code)` 如果 `value.name` （`value` 是一个 `` File` ``）的扩展名没有在 `allowed_extensions` 中找到，会引发一个 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)，代码为 `'invalid_extension'`。该扩展名将与 `allowed_extensions` 进行不区分大小写的比较。 > **Warning** > > 不要依赖文件扩展名的验证来确定文件的类型。文件可以重命名为任何扩展名，无论它们包含什么数据。 ### `validate_image_file_extension` #### `validate_image_file_extension` 使用 Pillow 确保 `value.name` （`value` 是一个 [`File`](/zh-hans/5.0/ref/files/file/#django.core.files.File)）具有 [一个有效的图像扩展名](https://pillow.readthedocs.io/en/latest/handbook/image-file-formats.html) 。 ### `ProhibitNullCharactersValidator` #### `class ProhibitNullCharactersValidator(message=None, code=None)` 如果 `str(value)` 包含一个或多个空字符（`'\x00'`），则引发 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)。 **参数:** - `message` -- 如果不是 `None`，则覆盖 [`message`](#django.core.validators.ProhibitNullCharactersValidator.message)。 - `code` -- 如果不是 `None`，则覆盖 [`code`](#django.core.validators.ProhibitNullCharactersValidator.code)。 #### `message` 如果验证失败， [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError) 使用的错误信息。默认值为 `"Null characters are not allowed."`。 #### `code` 当验证失败时 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError) 所使用的错误代码。默认为 `"null_characters_not_allowed"`。 ### `StepValueValidator` #### `class StepValueValidator(limit_value, message=None, offset=None)` 如果 `value` 不是 `limit_value` 的整数倍，其中 `limit_value` 可以是浮点数、整数、小数值或可调用对象，则会引发一个代码为 `'step_size'` 的 [`ValidationError`](/zh-hans/5.0/ref/exceptions/#django.core.exceptions.ValidationError)。当设置了 `offset` 时，验证将针对 `limit_value` 加上 `offset` 进行。例如，对于 `StepValueValidator(3, offset=1.4)`，有效的值包括 `1.4`、`4.4`、`7.4`、`10.4` 等等。 > **Changed in Django 5.0** > > 添加了 `offset` 参数。