@IsEmail

Декоратор @IsEmail в библиотеке class-validator предназначен для проверки строковых значений на соответствие формату адреса электронной почты. Проверка основана на синтаксических правилах RFC и включает валидацию локальной части, домена и допустимых символов.

Ключевая особенность декоратора заключается в том, что он работает на уровне метаданных класса и интегрируется с системой валидации объектов, позволяя декларативно описывать правила проверки данных.

Базовое использование

Минимальная форма применения ограничивается указанием декоратора без параметров:

import { IsEmail } from "class-validator";

export class CreateUserDto {
  @IsEmail()
  email: string;
}

В этом случае используется стандартный набор правил проверки email-адреса. Значение должно содержать символ @, корректный домен и допустимую локальную часть.

Внутренняя логика проверки

При валидации выполняется последовательность проверок:

  • наличие символа @ и разделение строки на локальную и доменную части;
  • проверка допустимых символов в локальной части;
  • проверка структуры домена (наличие точек, корректные TLD);
  • контроль длины строки (в зависимости от настроек);
  • дополнительная нормализация в зависимости от опций.

Важно: @IsEmail не гарантирует существование почтового ящика, проверяется только формат строки.

Параметры декоратора

Декоратор принимает объект опций, позволяющий гибко управлять правилами проверки.

@IsEmail(options?: IsEmailOptions)

allow_display_name

Позволяет использовать отображаемое имя перед адресом.

@IsEmail({ allow_display_name: true })
email: string;

Примеры допустимых значений:

  • John Doe <john@example.com>
  • Support <support@mail.com>

При включении параметра парсер извлекает email из строки с отображаемым именем.

require_display_name

Обязывает наличие отображаемого имени.

@IsEmail({ require_display_name: true })
email: string;

Строка без имени будет считаться невалидной.

allow_utf8_local_part

Разрешает использование UTF-8 символов в локальной части адреса.

@IsEmail({ allow_utf8_local_part: true })
email: string;

Пример допустимого значения:

  • пользователь@domain.com

Без включения этой опции такие значения считаются некорректными.

require_tld

Определяет обязательность наличия верхнеуровневого домена.

@IsEmail({ require_tld: true })
email: string;

При значении false допускаются адреса вида:

  • user@localhost

При значении true подобные адреса отклоняются.

ignore_max_length

Отключает проверку максимальной длины email-строки.

@IsEmail({ ignore_max_length: true })
email: string;

По умолчанию действует ограничение длины в соответствии с RFC-стандартами (обычно 254 символа).

domain_specific_validation

Включает более строгую проверку доменной части с учётом особенностей популярных почтовых провайдеров.

@IsEmail({ domain_specific_validation: true })
email: string;

При включении усиливается проверка корректности домена и поддоменов.

blacklisted_chars

Позволяет указать набор запрещённых символов.

@IsEmail({ blacklisted_chars: "<>\" " })
email: string;

Если в строке присутствует хотя бы один символ из списка, значение считается невалидным.

Примеры комплексного использования

Комбинация нескольких опций позволяет реализовать строгую валидацию:

import { IsEmail } from "class-validator";

export class RegisterDto {
  @IsEmail({
    allow_utf8_local_part: true,
    require_tld: true,
    ignore_max_length: false,
    domain_specific_validation: true,
  })
  email: string;
}

В данном случае проверка становится более строгой и учитывает как синтаксис, так и практическую корректность доменной части.

Поведение при преобразовании данных

class-validator работает с уже созданными объектами классов. Поэтому важна предварительная трансформация входных данных:

import { plainToInstance } from "class-transformer";
import { validate } from "class-validator";

const input = {
  email: "user@example.com",
};

const dto = plainToInstance(CreateUserDto, input);

validate(dto).then(errors => {
  console.log(errors);
});

Без преобразования декораторы могут не сработать корректно, так как отсутствуют метаданные класса.

Особенности работы с пробелами и форматированием

Email-валидатор автоматически обрабатывает:

  • ведущие и завершающие пробелы (в большинстве конфигураций);
  • вложенные отображаемые имена при включённой опции allow_display_name;
  • экранированные символы в локальной части.

Однако избыточное форматирование строки может привести к отклонению значения, особенно при строгих настройках.

Ограничения проверки

Несмотря на широкий набор правил, декоратор имеет принципиальные ограничения:

  • не проверяется существование домена через DNS;
  • не выполняется SMTP-проверка;
  • не гарантируется доставка письма;
  • возможны ложноположительные и ложноотрицательные результаты при нестандартных доменах.

Сочетание с другими декораторами

@IsEmail часто используется совместно с другими валидаторами:

import { IsEmail, IsNotEmpty, MaxLength } from "class-validator";

export class UserDto {
  @IsNotEmpty()
  @MaxLength(254)
  @IsEmail()
  email: string;
}

Такой подход позволяет усилить контроль над входными данными за счёт комбинирования правил.

Типичные сценарии применения

  • регистрация пользователей;
  • восстановление пароля;
  • подписка на рассылки;
  • идентификация аккаунтов в API;
  • проверка контактных данных в формах.

Поведение при ошибках валидации

При несоответствии формату возвращается объект ошибки с метаданными:

{
  "property": "email",
  "constraints": {
    "isEmail": "email must be an email"
  }
}

Сообщение может быть переопределено через систему локализации или кастомные сообщения валидатора.

Производительность

Валидация email-строк относится к лёгким операциям, однако при массовой обработке данных следует учитывать:

  • количество проверяемых объектов;
  • включённые дополнительные опции (например, domain-specific validation);
  • глубину интеграции с трансформацией объектов.

При стандартных сценариях нагрузка минимальна и не требует оптимизации.

Оглавление