# Django 5.2.8 documentation

# 验证器

## 编写验证器

验证器是一个可调用对象，它接受一个值，如果不符合某些条件，则会引发 `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 -- 如果不是 `None`，则覆盖 `allowlist`。

  An `EmailValidator` ensures that a value looks like an email address, and raises a `ValidationError` with `message` and `code` if it doesn't. Values longer than 320 characters are always considered invalid.

  message

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

  code

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

  allowlist

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

### `DomainNameValidator`

class DomainNameValidator(accept_idna=True, message=None, code=None)

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

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

  accept_idna

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

### `URLValidator`

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

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

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

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

  schemes

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

    Warning

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

  max_length

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

### `validate_email`

validate_email

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

### `validate_domain_name`

validate_domain_name

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

### `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` 进行不区分大小写的比较。

  Warning

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

### `validate_image_file_extension`

validate_image_file_extension

  Uses Pillow to ensure that `value.name` (`value` is a `File`) has a valid image extension.

### `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` 的整数倍，其中 `limit_value` 可以是浮点数、整数、小数值或可调用对象，则会引发一个代码为 `'step_size'` 的 `ValidationError`。当设置了 `offset` 时，验证将针对 `limit_value` 加上 `offset` 进行。例如，对于 `StepValueValidator(3, offset=1.4)`，有效的值包括 `1.4`、`4.4`、`7.4`、`10.4` 等等。