Валидация сообщений

Подсистема поддерживает валидацию сообщений по спецификации OpenAPI 3.0 (JSON Schema).

Назначение

• Контроль контрактов — гарантия соответствия структуры сообщений согласованному формату
• Раннее обнаружение ошибок — невалидные сообщения не попадают в очередь отправки
• Документирование API — схемы служат спецификацией для внешних систем

Архитектура

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Сформированное │     │  Валидатор      │     │  OpenAPI Schema │
│  сообщение      │────▶│  пакетов        │◀────│  (инт_Схемы)    │
│  (JSON)         │     │                 │     │                 │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                    ┌────────────┴────────────┐
                    ▼                         ▼
             ┌────────────┐            ┌────────────┐
             │  Успех     │            │  Ошибки    │
             │  (пусто)   │            │  (массив)  │
             └────────────┘            └────────────┘

Справочник схем

Схемы хранятся в справочнике инт_Схемы:

Реквизит	Тип	Описание
Наименование	Строка	Название схемы
ТекстСхемыJson	Строка	JSON-текст OpenAPI спецификации
URLСхемы	Строка	URL для загрузки внешней схемы

Пример схемы

{
  "openapi": "3.0.0",
  "info": {
    "title": "Orders API",
    "version": "1.0.0"
  },
  "components": {
    "schemas": {
      "Order": {
        "type": "object",
        "required": ["id", "number", "date", "items"],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Уникальный идентификатор заказа"
          },
          "number": {
            "type": "string",
            "maxLength": 11,
            "description": "Номер документа"
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "Дата и время заказа"
          },
          "amount": {
            "type": "number",
            "minimum": 0,
            "description": "Сумма заказа"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/OrderItem"
            }
          }
        }
      },
      "OrderItem": {
        "type": "object",
        "required": ["sku", "quantity"],
        "properties": {
          "sku": {
            "type": "string",
            "description": "Артикул товара"
          },
          "quantity": {
            "type": "number",
            "minimum": 0.001,
            "description": "Количество"
          },
          "price": {
            "type": "number",
            "minimum": 0,
            "description": "Цена за единицу"
          }
        }
      }
    }
  }
}

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

В справочнике инт_ПотокиДанных:

Реквизит	Значение
Валидация	✅ Включена
СхемаДанных	Ссылка на элемент инт_Схемы
ИмяСхемыПакета	Order (имя схемы в components/schemas)

API валидатора

Модуль инт_ВалидаторПакетов

Валидировать

Основной метод валидации:

МассивОшибок = инт_ВалидаторПакетов.Валидировать(
    МодельДанных,    // Соответствие/Структура — данные для проверки
    ИмяСхемы,        // Строка — имя схемы в components/schemas
    ТекстСхемыJSON   // Строка — полный текст OpenAPI-спецификации
);

Возвращает:

• Пустой массив — валидация успешна
• Массив строк — список ошибок валидации

Пример использования

// Формируем сообщение
Сообщение = Новый Соответствие;
Сообщение.Вставить("id", Строка(НовыйУникальныйИдентификатор()));
Сообщение.Вставить("number", "00001");
// Пропустили обязательное поле date

// Получаем схему
Схема = Справочники.инт_Схемы.НайтиПоНаименованию("Orders API");

// Валидируем
МассивОшибок = инт_ВалидаторПакетов.Валидировать(
    Сообщение,
    "Order",
    Схема.ТекстСхемыJson
);

Если МассивОшибок.Количество() > 0 Тогда
    Для Каждого Ошибка Из МассивОшибок Цикл
        Сообщить(Ошибка);  // "Отсутствует обязательное свойство: date"
    КонецЦикла;
КонецЕсли;

Автоматическая валидация в потоке

Если в потоке включена валидация, она выполняется автоматически после формирования сообщения:

// Справочники.инт_ПотокиДанных.СформироватьСообщениеПоПотоку
// внутри вызывает:

Если ПотокДанных.Валидация Тогда
    Справочники.инт_ПотокиДанных.ВалидироватьСообщениеПоПотоку(
        СформированноеСообщение, 
        ПотокДанных
    );
КонецЕсли;

При ошибке валидации возбуждается исключение, и сообщение получает статус ОшибкаФормирования.

Типы проверок

JSON Schema поддерживает множество правил валидации:

Типы данных

Тип	Описание
string	Строка
number	Число
integer	Целое число
boolean	Булево
array	Массив
object	Объект
null	Null

Ограничения строк

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100,
  "pattern": "^[A-Z]{2}\\d{6}$",
  "format": "email"
}

Ограничения чисел

{
  "type": "number",
  "minimum": 0,
  "maximum": 1000000,
  "multipleOf": 0.01
}

Ограничения массивов

{
  "type": "array",
  "minItems": 1,
  "maxItems": 100,
  "uniqueItems": true
}

Обязательные поля

{
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" }
  }
}

Кэширование схем

Подсистема поддерживает кэширование внешних схем через регистр инт_КэшированиеСхемOpenApi:

// Схемы по URL кэшируются автоматически
СхемаСсылка = Справочники.инт_Схемы.НайтиПоНаименованию("External API");
// Если указан URLСхемы — схема будет загружена и закэширована

Рекомендации

Версионирование схем

Включайте версию в название схемы (Orders API v1.0). При изменении контракта создавайте новую схему.

Тестирование схем

Храните тестовые JSON-файлы в tests/fixtures/ и проверяйте их в unit-тестах.

Производительность

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

Сообщения об ошибках

Добавляйте description к полям схемы — эти описания используются в сообщениях об ошибках.

Следующие шаги

• Создание потока — практическое руководство
• Многопоточность — параллельная обработка
• Очереди сообщений — механизм очередей