Опции валидации

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

Основной принцип заключается в том, что одна и та же схема может вести себя по-разному в зависимости от переданных опций, не меняя при этом своего описания. Это позволяет разделять структуру данных и правила её обработки.

Выполнение валидации в Joi осуществляется через метод validate, которому может быть передан объект настроек:

const result = schema.validate(value, options);

Либо через встроенные настройки схемы:

const schema = Joi.object({
  name: Joi.string()
}).options(options);

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

  • при вызове validate(value, options)
  • через метод .options() или .prefs() у схемы
  • глобально через базовую конфигурацию Joi
  • на уровне вложенных схем (с переопределением)

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

Обработка неизвестных полей

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

allowUnknown

Параметр allowUnknown определяет, допускаются ли дополнительные свойства в объектах:

Joi.object({
  name: Joi.string()
}).validate(data, { allowUnknown: true });

Поведение:

  • true — неизвестные поля сохраняются
  • false — неизвестные поля считаются ошибкой

В случае объектов параметр особенно важен для API, где структура данных может расширяться без изменения схемы.

stripUnknown

Параметр stripUnknown управляет удалением лишних полей:

Joi.object({
  name: Joi.string()
}).validate(data, { stripUnknown: true });

Возможные режимы:

  • false — поля сохраняются
  • true — удаляются все неизвестные поля
  • { objects: true } — рекурсивное удаление в глубине объектов

Это позволяет использовать Joi не только как валидатор, но и как инструмент нормализации данных.

Управление остановкой валидации

abortEarly

Параметр abortEarly влияет на стратегию обработки ошибок:

const result = schema.validate(data, { abortEarly: false });

Поведение:

  • true — валидация прекращается после первой ошибки
  • false — собираются все ошибки

При значении false результат содержит полный список проблем, что особенно полезно для форм и пользовательских интерфейсов.

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

convert

Joi может автоматически преобразовывать входные данные в ожидаемые типы.

schema.validate(data, { convert: true });

Типичные преобразования:

  • строки → числа
  • строки → даты
  • строковые булевы значения → boolean

При отключении:

{ convert: false }

значения проверяются строго без приведения типов, что важно для строгих API контрактов.

Обязательность и стратегия presence

presence

Параметр presence задаёт поведение обязательности полей по умолчанию:

schema.validate(data, { presence: 'required' });

Возможные значения:

  • required — все поля обязательны
  • optional — поля по умолчанию необязательны
  • forbidden — поля запрещены

Этот параметр переопределяет поведение схемы, но не отменяет явно заданные .required() или .optional().

Контекст для сообщений и шаблонов

context

Параметр context используется для передачи дополнительных данных в генерацию сообщений об ошибках:

schema.validate(data, {
  context: {
    label: 'Пользователь'
  }
});

Контекст может применяться в кастомных сообщениях:

Joi.string().messages({
  'string.base': '{{#label}} должен быть строкой'
});

В результате {{#label}} подставляется из контекста.

Настройка сообщений об ошибках

messages

Параметр messages позволяет переопределять стандартные сообщения Joi:

schema.validate(data, {
  messages: {
    'string.empty': 'Поле не должно быть пустым',
    'any.required': 'Поле обязательно'
  }
});

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

Поведение функций и сложных типов

Joi по умолчанию игнорирует функции и нестандартные структуры при валидации объектов. Это поведение может быть изменено через комбинацию параметров:

  • allowUnknown
  • convert
  • кастомные правила

Функции в объектах обычно исключаются из результата при использовании stripUnknown.

Строгий режим

Хотя строгий режим не является отдельной опцией в объекте настроек, он влияет на поведение преобразования:

schema.validate(data, { convert: false });

или через метод:

schema.strict();

В строгом режиме:

  • запрещается автоматическое приведение типов
  • значения должны строго соответствовать описанию схемы

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

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

const base = Joi.defaults(schema => schema.options({
  abortEarly: false,
  stripUnknown: true
}));

Либо через создание преднастроенной версии схем:

const customJoi = Joi.defaults(schema => schema.options({
  convert: false,
  allowUnknown: false
}));

Такая конфигурация применяется ко всем схемам, созданным из этой базы.

Наследование опций в сложных схемах

Вложенные структуры наследуют параметры от родительской схемы:

const schema = Joi.object({
  user: Joi.object({
    name: Joi.string()
  })
}).options({
  abortEarly: false,
  stripUnknown: true
});

Поведение:

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

Обработка ошибок и структура результата

Результат валидации при расширенных опциях содержит:

  • value — нормализованные данные
  • error — объект ошибок (или null)
  • warning — предупреждения (в некоторых конфигурациях)

При abortEarly: false структура ошибок включает массив деталей, каждая из которых описывает конкретное нарушение.

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

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

  • convert: true увеличивает время обработки из-за приведения типов
  • abortEarly: false увеличивает нагрузку при ошибках
  • stripUnknown: true добавляет этап постобработки объекта

В высоконагруженных системах часто используется минимальный набор преобразований и строгая схема.

Комбинирование опций

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

schema.validate(data, {
  abortEarly: false,
  allowUnknown: false,
  stripUnknown: true,
  convert: true,
  presence: 'required'
});

Такая конфигурация задаёт:

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

Переопределение поведения на уровне схемы

Схемы могут иметь встроенные настройки:

const schema = Joi.object({
  id: Joi.number(),
  name: Joi.string()
}).options({
  stripUnknown: true,
  abortEarly: false
});

При этом вызов validate может дополнительно уточнить поведение:

schema.validate(data, { convert: false });

Локальный параметр convert переопределит настройку схемы, но не затронет остальные опции.

Роль опций в архитектуре валидации

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

  • строгость проверки
  • степень нормализации
  • формат ошибок
  • политика обработки неизвестных данных

Такое разделение позволяет использовать одну и ту же схему в различных контекстах: API, формы, внутренние сервисы и интеграции.

Оглавление