Метод validate и его параметры

Метод validate является центральной частью механизма проверки объектов в библиотеке class-validator. Он выполняет обход всех декораторов валидации, применённых к свойствам объекта, и формирует структурированный результат, содержащий ошибки, если они обнаружены.

В актуальной реализации метод имеет следующую форму:

validate(object: object, validatorOptions?: ValidatorOptions): Promise<ValidationError[]>

Возвращаемое значение всегда является Promise, который разрешается в массив объектов ValidationError[]. Если ошибок нет, возвращается пустой массив.

Первый параметр является обязательным и представляет собой экземпляр класса или обычный объект, содержащий поля с декораторами валидации.

Второй параметр — объект конфигурации, управляющий поведением процесса проверки.

Первый параметр: проверяемый объект

Суть параметра

Первый аргумент object — это сущность, к которой применены правила валидации через декораторы. Именно его свойства анализируются во время выполнения validate.

await validate(user);

Особенности обработки

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

Второй параметр: ValidatorOptions

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

skipMissingProperties

skipMissingProperties?: boolean

Если установлено в true, отсутствующие свойства не проверяются.

{
  skipMissingProperties: true
}

Поведение:

  • свойства undefined игнорируются;
  • применяется в сценариях частичного обновления объектов (PATCH-логика).

whitelist

whitelist?: boolean

Удаляет все свойства, не имеющие валидаторов.

Поведение:

  • в объекте остаются только явно описанные поля;
  • остальные удаляются перед возвратом результата.

forbidNonWhitelisted

forbidNonWhitelisted?: boolean

Используется совместно с whitelist. Вместо удаления лишних свойств выбрасывает ошибку.

Логика:

  • если найдено поле без декораторов — добавляется ошибка;
  • часто применяется в API-валидации для строгих контрактов.

forbidUnknownValues

forbidUnknownValues?: boolean

Запрещает проверку объектов, которые не являются экземплярами классов с декораторами.

Поведение:

  • если передан “сырой” объект без метаданных — выбрасывается ошибка;
  • усиливает защиту от неконтролируемых структур данных.

groups

groups?: string[]

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

Пример логики:

  • поля помечаются группами groups: ['create'] или groups: ['update'];
  • validate проверяет только совпадающие группы.

always

always?: boolean

Если true, игнорирует группировку и выполняет все валидаторы, помеченные как always.

validationError

validationError?: {
  target?: boolean;
  value?: boolean;
}

Управляет тем, какие данные попадут в объект ошибки:

  • target: включает исходный объект;
  • value: включает значение проверяемого свойства.

Используется для уменьшения объёма данных в ответах API.

Поведение метода validate

Асинхронная модель выполнения

Метод всегда возвращает Promise, даже если внутри нет асинхронных валидаторов.

const errors = await validate(user);

Внутренне процесс включает:

  1. построение дерева метаданных;
  2. последовательную проверку каждого поля;
  3. выполнение синхронных и асинхронных правил;
  4. агрегацию ошибок.

Структура результата ValidationError

Каждая ошибка имеет следующую структуру:

{
  property: string;
  constraints?: Record<string, string>;
  children?: ValidationError[];
  target?: object;
  value?: any;
}

property

Имя поля, где обнаружена ошибка.

constraints

Объект с описанием нарушенных правил:

{
  isEmail: "email must be valid",
  minLength: "too short"
}

children

Ошибки вложенных объектов.

target

Ссылка на исходный объект (если включено в options).

value

Фактическое значение поля.

Влияние вложенных структур

Метод validate рекурсивно обходит вложенные классы при использовании декораторов:

  • @ValidateNested()
  • @Type(() => Class)

Поведение:

  • создаётся отдельный контекст проверки;
  • ошибки группируются в children;
  • сохраняется структура объекта.

Работа с массивами

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

@IsString({ each: true })
tags: string[];

Особенности:

  • параметр each: true активирует проверку каждого элемента;
  • ошибки возвращаются с индексной привязкой внутри children.

Отличие от validateSync

Хотя validate является основным методом, существует синхронный аналог:

  • validate — всегда Promise;
  • validateSync — немедленный результат без async-валидаторов.

При наличии асинхронных правил validateSync не рекомендуется, так как игнорирует их.

Поведение при пустых объектах

Если объект не содержит ни одного валидируемого поля:

  • при forbidUnknownValues = false возвращается пустой массив;
  • при строгих настройках возможна ошибка.

Взаимодействие с transform-логикой

При использовании class-transformer:

  • сначала выполняется преобразование plain → class;
  • затем передаётся в validate;
  • метаданные валидации работают только на классах.

Типичные сценарии использования options

Строгая API-валидация

{
  whitelist: true,
  forbidNonWhitelisted: true,
  forbidUnknownValues: true
}

Частичное обновление

{
  skipMissingProperties: true
}

Разделение логики create/update

{
  groups: ['create']
}

Обработка ошибок на верхнем уровне

Результат validate обычно агрегируется:

  • пустой массив → объект валиден;
  • непустой массив → объект содержит нарушения правил.

Ошибки могут быть преобразованы в:

  • HTTP-ответы;
  • логические исключения;
  • структуры валидационных отчётов.

Влияние производительности

Основные факторы нагрузки:

  • количество декораторов;
  • глубина вложенности;
  • наличие асинхронных валидаторов;
  • массивы больших размеров.

Оптимизация достигается через:

  • ограничение вложенности;
  • использование skipMissingProperties;
  • точечное применение groups.
Оглавление