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

Валидация в библиотеке Validator.js (чаще в реализации validatorjs для JavaScript) опирается на строго определённую структуру хранения и возврата ошибок. Основная идея заключается в том, что каждая ошибка привязана к конкретному полю, а набор сообщений формируется в виде централизованного объекта, называемого «ошибочным пакетом» (error bag).

Общая модель представления ошибок

Результат валидации формируется в виде объекта, содержащего:

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

Ключевой элемент — объект ошибок, где каждое поле сопоставляется с массивом строковых сообщений.

errors = {
  fieldName: ["Сообщение об ошибке 1", "Сообщение об ошибке 2"]
}

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

Структура error bag

Error bag представляет собой специализированную коллекцию, содержащую:

  • ключи полей формы;
  • массивы сообщений;
  • методы доступа к ошибкам.

Типичная структура:

{
  errors: {
    name: ["Имя обязательно для заполнения"],
    email: ["Email имеет некорректный формат"]
  }
}

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

Привязка ошибок к полям

Каждое правило валидации формирует собственное сообщение при нарушении. При наличии нескольких правил на одно поле:

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

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

name: required + min:3 + max:20

Результат:

name: [
  "Поле обязательно",
  "Минимальная длина 3 символа"
]

Структура сообщений правил

Сообщения формируются на основе шаблонов правил. Базовая структура сообщения содержит:

  • имя атрибута;
  • название правила;
  • параметры правила.

Шаблон:

:attribute :rule :parameters

Пример:

Email должен быть корректным адресом

или с параметрами:

Пароль должен содержать минимум :min символов

После интерполяции:

Пароль должен содержать минимум 8 символов

Плейсхолдеры в сообщениях

В сообщениях используются специальные маркеры:

  • :attribute — имя поля
  • :min — минимальное значение
  • :max — максимальное значение
  • :size — фиксированный размер
  • :value — текущее значение

Пример шаблона:

Поле :attribute должно быть не меньше :min

Результат:

Поле age должно быть не меньше 18

Внутренняя структура ошибок

Каждая ошибка представляется как элемент массива строк. В расширенных реализациях дополнительно могут присутствовать:

  • код правила;
  • метаинформация;
  • уровень критичности.

Обобщённая структура:

{
  field: {
    rule: "required",
    message: "Поле обязательно",
    type: "validation"
  }
}

Однако в стандартной модели Validator.js чаще используется упрощённый формат — массив строк.

Группировка ошибок

Ошибки группируются по ключам полей. При этом:

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

Пример:

user.email
user.password

Структура:

{
  "user.email": ["Некорректный email"],
  "user.password": ["Слишком короткий пароль"]
}

Вложенные структуры данных

Для объектов и массивов применяется точечная нотация:

user.profile.age
items.0.name

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

Пример:

{
  "user.profile.age": ["Возраст должен быть числом"]
}

Формирование стандартных сообщений

Стандартные сообщения генерируются автоматически на основе набора правил:

  • required
  • email
  • min
  • max
  • numeric
  • string

Каждое правило имеет дефолтный шаблон сообщения, который подставляется при отсутствии пользовательской настройки.

Кастомизация сообщений

Структура позволяет переопределять сообщения на нескольких уровнях:

  • глобально для всех полей;
  • для конкретного поля;
  • для конкретного правила.

Формат:

{
  "email.required": "Email обязателен",
  "password.min": "Пароль слишком короткий"
}

Результирующая структура ошибок остаётся неизменной — изменяется только текст сообщений.

Приоритет сообщений

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

  1. сообщения для конкретного поля и правила;
  2. сообщения для правила глобально;
  3. стандартные сообщения библиотеки.

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

Формат возврата результата валидации

Результат валидации включает:

{
  passes: boolean,
  fails: boolean,
  errors: {
    field: [messages]
  }
}

При этом основной акцент делается на объекте errors.

Сериализация ошибок

Для передачи через API структура часто сериализуется в JSON:

{
  "errors": {
    "email": [
      "Email обязателен",
      "Email имеет неверный формат"
    ]
  }
}

Сериализация сохраняет:

  • ключи полей;
  • порядок сообщений;
  • группировку ошибок.

Множественные ошибки одного поля

При наличии нескольких правил поведение зависит от конфигурации:

  • режим «stop on first failure» — возвращается первая ошибка;
  • режим полного сбора — возвращаются все ошибки.

Полная структура:

password: [
  "Минимум 8 символов",
  "Должен содержать цифру",
  "Должен содержать символ"
]

Обработка агрегированных сообщений

В некоторых сценариях требуется объединение сообщений в одну строку:

"Email обязателен; Email имеет неверный формат"

Однако стандартная структура Validator.js сохраняет массивный формат для упрощения обработки на уровне интерфейса.

Особенности структуры сообщений

Ключевые характеристики системы сообщений:

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

Локализация сообщений

Поддержка языков реализуется через словари сообщений:

{
  required: "Поле обязательно",
  email: "Некорректный email"
}

Структура ошибок при этом не изменяется, изменяется только содержимое строк.

Влияние структуры на обработку на клиенте

Формат errors позволяет:

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

Основной принцип — прямое соответствие ключа поля и UI-элемента формы.

Оглавление