Документирование правил

Структура правил и их роль в валидации

Валидационные правила в Vest представляют собой декларативные тесты, объединённые в наборы (suites), формирующие поведение проверки данных. Каждый набор описывает набор условий, применяемых к конкретной сущности данных (форма, объект, модель).

Документирование правил в такой системе требует фиксации трёх ключевых аспектов:

  • логика проверки (что именно проверяется)
  • контекст применения (к какому полю или группе относится правило)
  • результат выполнения (сообщение и тип ошибки)

Базовая структура правила строится вокруг функции test, где фиксируется условие и сообщение об ошибке:

test('username', 'Имя пользователя обязательно', () => {
  enforce(value).isNotEmpty();
});

Документация таких правил должна учитывать не только текстовое описание, но и семантику проверки.

Согласованное именование правил

Именование тестов является ключевым элементом документирования. Название теста выступает идентификатором, который используется для трассировки ошибок и анализа покрытия.

Рекомендуемые подходы:

  • использование пути поля как идентификатора (user.email, profile.age)
  • выделение доменной области (auth.password.minLength)
  • группировка через префиксы (billing.card.number)

Пример:

test('auth.password.minLength', 'Пароль должен содержать минимум 8 символов', () => {
  enforce(value).longerThanOrEquals(8);
});

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

Документирование групп правил (suites)

Suite в Vest объединяет правила в единый контекст. Документирование suite включает:

  • назначение группы
  • набор полей
  • зависимости между проверками
  • порядок выполнения
const validation = suite('registration.form', () => {
  test('email', 'Некорректный email', () => {
    enforce(value).matches(/.+@.+\..+/);
  });

  test('password', 'Слабый пароль', () => {
    enforce(value).longerThan(8);
  });
});

При документировании важно фиксировать границы ответственности suite: одна форма — один suite, одна бизнес-операция — один набор.

Контекст ошибок и стандартизация сообщений

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

Требования к документированию сообщений:

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

Пример структурированного подхода:

test('profile.age', 'Возраст должен быть числом от 18 до 65', () => {
  enforce(value).greaterThanOrEquals(18);
  enforce(value).lessThanOrEquals(65);
});

Для сложных систем применяется разделение логики и сообщений через константы:

const messages = {
  ageRange: 'Возраст должен быть в допустимом диапазоне'
};

Документирование бизнес-логики правил

Валидационные правила часто отражают бизнес-ограничения, которые должны быть явно описаны.

Документация должна фиксировать:

  • происхождение ограничения (бизнес-требование)
  • причину существования правила
  • связь с другими доменными сущностями

Пример:

test('order.amount.limit', 'Сумма заказа превышает допустимый лимит', () => {
  enforce(value).lessThanOrEquals(10000);
});

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

Композиция правил и повторное использование

В Vest правила часто переиспользуются через композицию функций. Документирование в этом случае включает описание:

  • входных параметров правила
  • ожидаемого поведения
  • побочных эффектов отсутствия
const minLengthRule = (field, length) =>
  test(field, `Минимальная длина ${length}`, () => {
    enforce(value).longerThanOrEquals(length);
  });

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

Асинхронные правила и их спецификация

Асинхронные проверки требуют дополнительной документации из-за наличия внешних зависимостей (API, базы данных).

Ключевые элементы описания:

  • источник данных
  • задержки и таймауты
  • возможные состояния ошибки
  • стратегия повторов
test('email.unique', 'Email уже используется', async () => {
  const exists = await api.checkEmail(value);
  enforce(exists).isFalsy();
});

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

Метаданные правил

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

Типичные метаданные:

  • уровень критичности
  • категория ошибки
  • код ошибки
  • теги домена
test('password.strength', 'Слабый пароль', () => {
  enforce(value).matches(/(?=.*[A-Z])(?=.*\d)/);
}).meta({
  severity: 'high',
  code: 'AUTH_001',
  tags: ['auth', 'security']
});

Метаданные используются для построения отчетов и интеграции с аналитическими системами.

Документирование условий ветвления

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

test('delivery.address', 'Адрес обязателен при доставке', () => {
  if (model.deliveryType === 'courier') {
    enforce(value).isNotEmpty();
  }
});

Документация включает:

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

Локализация правил и текстов

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

Рекомендуемая модель:

  • ключ сообщения хранится в правиле
  • текст подставляется через словарь локализации
test('username.required', 'error.username.required', () => {
  enforce(value).isNotEmpty();
});

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

Версионирование и эволюция правил

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

Фиксируются:

  • дата введения правила
  • причина изменения
  • совместимость с предыдущими версиями
test('age.minimum.v2', 'Возраст должен быть не менее 18 лет', () => {
  enforce(value).greaterThanOrEquals(18);
});

Версионирование предотвращает нарушение существующих контрактов при обновлениях.

Структурное описание правил в документации

Для систематизации используется формализованное представление:

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

Пример логической схемы:

RULE:
  id: auth.password.minLength
  field: password
  type: sync
  constraint: length >= 8
  message: "Минимальная длина пароля 8 символов"
  tags: [auth, security]

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

Отладка и трассировка через документацию правил

Документирование правил служит основой для отладки. Каждый тест должен быть трассируемым:

  • коду правила соответствует конкретное сообщение
  • каждое сообщение связано с идентификатором
  • ошибки агрегируются по полям и доменам

Это позволяет строить диагностические отчеты без анализа исходного кода, опираясь только на структуру правил и их описания.

Оглавление