# Django 3.2.11.dev 文档

# 验证器

## 编写验证器

验证器是一个可调用对象，它接收一个值，如果它不符合某些标准，就会引发一个 `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`

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`。默认情况下，如果没有 找到 匹配的，会引发一个 `ValidationError`，包含 `message` 和 `code`。它的行为可以通过将 `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 flags。如果 `regex` 是一个预先编译的正则表达式，并且 `flags` 被覆盖，则 `TypeError` 被引发。默认值为 `0`。

### `EmailValidator`

class `EmailValidator`(message=None, code=None, allowlist=None)

  参数: | message -- 如果不是 `None`，则覆盖 `message`。 code -- 如果不是 `None`，则覆盖 `code`。 allowlist -- If not `None`, overrides `allowlist`.

  `message`

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

  `code`

    `ValidationError` 验证失败时使用的错误代码。默认值为 `"invalid"`。

  `allowlist`

    Allowlist of email domains. By default, a regular expression (the `domain_regex` attribute) is used to validate whatever appears after the `@` sign. However, if that string appears in the `allowlist`, this validation is bypassed. If not provided, the default `allowlist` is `['localhost']`. Other domains that don't contain a dot won't pass validation, so you'd need to add them to the `allowlist` as necessary.

  3.2 版后已移除: The `whitelist` parameter is deprecated. Use `allowlist` instead. The undocumented `domain_whitelist` attribute is deprecated. Use `domain_allowlist` instead.

### `URLValidator`

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

  `RegexValidator` 子类，确保一个值看起来像一个 URL，如果不像，则引发 `'invalid'` 的错误代码。

  回环地址和保留的 IP 空间被认为是有效的。字面 IPv6 地址（RFC 3986#section-3.2.2）和 Unicode 域都支持。

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

  `schemes`

    要验证的 URL／URI 协议列表。如果没有提供，默认列表是 `['http', 'https', 'ftp', 'ftps']`。作为参考，IANA 网站提供了一个完整的 有效 URI 协议 列表。

### `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`，会引发一个 `ValidationError`，代码为 `'max_value'`，这可能是一个可调用对象。

### `MinValueValidator`

class `MinValueValidator`(limit_value, message=None)

  如果 `value` 小于 `limit_value`，会引发一个 `ValidationError`，代码为 `'min_value'`，这可能是一个可调用对象。

### `MaxLengthValidator`

class `MaxLengthValidator`(limit_value, message=None)

  如果 `value` 的长度大于 `limit_value`，会引发一个 `ValidationError`，代码为 `'max_length'`。

### `MinLengthValidator`

class `MinLengthValidator`(limit_value, message=None)

  如果 `value` 小于 `limit_value`，会引发一个 `ValidationError`，代码为 `'min_length'`，这可能是一个可调用对象。

### `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)

  如果 `value.name` （`value` 是一个 `File``）的扩展名没有在 `allowed_extensions` 中找到，会引发一个 `ValidationError`，代码为 `'invalid_extension'`。该扩展名将与 `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"`。