Глобальная настройка валидации

В библиотеке class-validator поведение валидации определяется не только декораторами, но и набором параметров, задающих общую стратегию обработки данных. Эти параметры формируют единый слой управления, который влияет на результат выполнения функций validate и validateOrReject.

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

Интерфейс ValidatorOptions и влияние параметров

Основу конфигурации составляет интерфейс ValidatorOptions, определяющий поведение движка валидации.

Ключевые параметры конфигурации

whitelist Удаляет свойства объекта, которые не имеют соответствующих декораторов валидации.

  • true — лишние поля удаляются из объекта
  • используется для защиты от несанкционированных данных

forbidNonWhitelisted Ужесточённый режим whitelist.

  • вместо удаления лишних свойств выбрасывается ошибка
  • применяется в системах с жёсткой схемой данных

forbidUnknownValues Запрещает валидацию объектов без метаданных.

  • предотвращает передачу “сырых” объектов
  • усиливает контроль типов

skipMissingProperties Игнорирует отсутствующие свойства.

  • полезно для partial update (PATCH)

skipNullProperties / skipUndefinedProperties Пропускает проверку null или undefined.

  • снижает шум ошибок при частичных данных

validationError Определяет состав объекта ошибки.

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

stopAtFirstError Прерывает валидацию после первой ошибки.

  • ускоряет обработку
  • уменьшает нагрузку на сложные схемы

dismissDefaultMessages Отключает стандартные сообщения ошибок.

  • используется при кастомной локализации

Формирование единого набора опций

Отсутствие встроенного глобального конфигурационного объекта компенсируется созданием централизованного набора параметров.

Базовый конфигурационный объект

import { validate } from "class-validator";

const validationOptions = {
  whitelist: true,
  forbidNonWhitelisted: true,
  skipMissingProperties: false,
  stopAtFirstError: false,
  validationError: {
    target: false,
    value: false,
  },
};

Такой объект применяется во всех вызовах validate, обеспечивая единообразие поведения.

Централизация через обёртку

Для устранения дублирования создаётся слой абстракции:

import { validate as baseValidate } from "class-validator";

const defaultOptions = {
  whitelist: true,
  forbidNonWhitelisted: true,
  skipMissingProperties: false,
};

export function validate(entity) {
  return baseValidate(entity, defaultOptions);
}

Подобная структура формирует де-факто глобальную конфигурацию, применяемую ко всем сущностям.

Управление контейнером зависимостей

Одним из ключевых глобальных механизмов является интеграция с DI-контейнером через useContainer.

import { useContainer } from "class-validator";
import { Container } from "some-di-container";

useContainer(Container);

Роль контейнера

Контейнер необходим для:

  • внедрения зависимостей в кастомные валидаторы
  • разрешения сервисов внутри ValidatorConstraint
  • централизованного управления зависимостями

Поведение при отсутствии контейнера

Без настройки контейнера:

  • кастомные валидаторы не могут получать сервисы
  • логика проверки становится статической

Глобальные стратегии обработки ошибок

Поведение ошибок в class-validator формируется структурой ValidationError.

Структура ошибки

Каждая ошибка может содержать:

  • constraints — список нарушенных правил
  • property — имя поля
  • children — вложенные ошибки
  • value — исходное значение (опционально)

Управление глубиной данных

const options = {
  validationError: {
    target: false,
    value: false,
  },
};

Отключение этих полей снижает объём возвращаемых данных и упрощает сериализацию ошибок.

Поведенческие режимы валидации

Режим строгой схемы

Комбинация параметров:

  • whitelist: true
  • forbidNonWhitelisted: true
  • forbidUnknownValues: true

Характеристики:

  • входные данные должны строго соответствовать DTO
  • любые лишние поля вызывают ошибку

Режим частичного обновления

Используется для PATCH-операций:

  • skipMissingProperties: true
  • skipUndefinedProperties: true

Поведение:

  • проверяются только переданные поля
  • отсутствующие свойства игнорируются

Режим быстрого отказа

const options = {
  stopAtFirstError: true,
};

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

  • минимизация вычислений
  • возврат первой найденной ошибки
  • оптимизация в высоконагруженных системах

Консистентность валидации через доменные слои

В крупных приложениях формируется единый слой валидации, который применяется ко всем DTO.

Пример доменного стандарта

const DOMAIN_VALIDATION_OPTIONS = {
  whitelist: true,
  forbidNonWhitelisted: true,
  skipMissingProperties: false,
  stopAtFirstError: false,
  validationError: {
    target: false,
    value: false,
  },
};

Использование такого объекта обеспечивает одинаковое поведение на уровне:

  • входных API
  • внутренних сервисов
  • межсервисного взаимодействия

Управление поведением кастомных валидаторов

Кастомные валидаторы в class-validator часто зависят от глобальных механизмов.

import { ValidatorConstraint, ValidatorConstraintInterface } from "class-validator";

@ValidatorConstraint({ async: true })
class IsUniqueUser implements ValidatorConstraintInterface {
  async validate(value) {
    return value !== "admin";
  }
}

При использовании DI:

  • доступ к сервисам зависит от useContainer
  • поведение становится частью глобальной инфраструктуры приложения

Интеграция с метаданными декораторов

class-validator строится на основе метаданных, создаваемых декораторами @IsString, @Length, @ValidateNested и другими.

Глобальные параметры влияют на интерпретацию этих метаданных:

  • whitelist управляет фильтрацией свойств на основе наличия метаданных
  • forbidUnknownValues проверяет наличие зарегистрированных схем
  • skipMissingProperties изменяет правила интерпретации отсутствующих ключей

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

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

Централизованная конфигурация уровня приложения

Используется единый модуль конфигурации:

  • хранение всех ValidatorOptions
  • экспорт в сервисы валидации
  • единая точка изменения поведения

Многоуровневая конфигурация

Разделение на уровни:

  • базовые опции (системные)
  • доменные опции (бизнес-логика)
  • локальные опции (конкретный вызов validate)

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

Функциональная композиция опций

const base = { whitelist: true };
const api = { forbidNonWhitelisted: true };

const merged = { ...base, ...api };

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

Контроль стабильности поведения валидации

Глобальная настройка в class-validator фактически сводится к контролю следующих аспектов:

  • степень жёсткости проверки схемы
  • стратегия обработки ошибок
  • поведение при неполных данных
  • взаимодействие с DI-контейнером
  • фильтрация входных объектов

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

Оглавление