В основе библиотеки лежит система декораторов, которая опирается на возможности метаданных TypeScript и рантайм-хранилище описаний правил. Декоратор в этом контексте представляет собой функцию, привязываемую к классу или его свойству и записывающую информацию о правилах проверки в глобальное хранилище.
Ключевая особенность заключается в том, что декораторы не выполняют валидацию напрямую. Они лишь фиксируют метаданные, которые затем используются отдельным механизмом проверки.
Процесс работы можно разделить на два фундаментальных этапа:
1. Фаза определения классов
При объявлении класса и применении декораторов происходит регистрация правил:
анализируется декоратор (например, @IsString(),
@MinLength(5))
формируется описание ограничения
описание сохраняется в глобальном хранилище метаданных
связь устанавливается между:
Важно: на этом этапе не создаётся ни одного объекта класса, а значит никакой проверки данных не происходит.
2. Фаза выполнения валидации
Когда вызывается функция валидации (validate,
validateSync), происходит обратный процесс:
Таким образом, декораторы выступают как описательная прослойка, а не как исполняемая логика.
В основе механизма лежит библиотека reflect-metadata,
которая позволяет:
Каждый декоратор записывает информацию через ключи метаданных, например:
Метаданные аккумулируются в структуру, доступную глобальному хранилищу валидатора.
Class-validator использует централизованное хранилище метаданных, где информация организована примерно следующим образом:
класс
свойство
список валидаторов
Такой подход позволяет:
При использовании декоратора вида:
@IsString()
name: string;происходит следующее:
В результате свойство name получает ассоциированный
набор ограничений, но само по себе не изменяется.
Одним из ключевых архитектурных решений является ленивая интерпретация метаданных:
Это позволяет:
Каждый стандартный декоратор представляет собой обёртку над функцией проверки:
@IsString() — проверяет тип string@IsNumber() — проверяет числовой тип@MinLength(n) — проверяет длину строки@Max(n) — ограничивает числовое значениеВнутри каждый декоратор:
Фактическое выполнение происходит в общем движке валидации.
Библиотека позволяет создавать собственные декораторы через механизм регистрации:
Пример логической структуры:
При этом пользовательский декоратор интегрируется в общую систему так же, как и встроенные правила.
Центральным компонентом выступает хранилище метаданных, которое:
Каждый декоратор при вызове добавляет запись в это хранилище, а не изменяет объект напрямую.
Дополнительный уровень логики позволяет управлять применением правил:
Декораторы могут быть привязаны к определённым группам, что позволяет:
Если к одному свойству применено несколько декораторов, они:
Это означает, что итоговая проверка формируется как композиция независимых ограничений.
Архитектура строго разделяет две зоны:
Декораторы:
Валидатор:
Такое разделение делает систему расширяемой и предсказуемой.
Хотя библиотека используется в JavaScript-окружении, её основная сила раскрывается через TypeScript:
Декораторы становятся связующим звеном между типами компиляции и динамической валидацией.
Работа декораторов имеет несколько важных особенностей:
Это означает, что вся система строится вокруг этапа инициализации приложения, а не runtime-логики объектов.