DATAREON Platform разделяет проверку REST-запросов на типы данных и бизнес-правила
Инженер SOFROS показал на DATAREON Platform, как принимать JSON от внешних систем и возвращать понятные ошибки до передачи документов в учётный контур. Важная деталь: проверка формата и проверка бизнес-логики происходят в разное время.
Главное
В демонстрационном сценарии складская система отправляет сведения о регистрации товаров через REST API. В сообщении есть метаданные документа и список позиций с кодом, количеством и ценой. Просто проверить существование полей здесь недостаточно: строка на месте числа или формально корректная, но недопустимая цена создают разные классы ошибок. Автор предлагает проводить отбор на границе интеграционной платформы, прежде чем данные попадут к получателю.
Первый рубеж — типизированная структура запроса. DATAREON сопоставляет значения с объявленными типами DateTime, Decimal, Int и String и прекращает обработку, если не может преобразовать входные данные. Веб-обработчик при такой ошибке даже не запускается. Это позволяет не повторять ручную проверку числовых и календарных форматов в пользовательском коде, но одновременно означает, что его собственные сообщения об ошибках на этом этапе недоступны.
Подробности
Есть неочевидное исключение: пропущенное поле платформа может заменить значением по умолчанию, а не отклонить. Для строки это пустое значение, для числа — ноль, а для даты в описанном стенде использовался минимальный год 1900. Поэтому второй рубеж остаётся обязательным. В обработчике автор проверяет заполненность документа, допустимость даты, наличие товарных позиций, положительные цену и количество, а также формат номенклатурного кода.
Чтобы клиент получал предсказуемый ответ, конфигурация внешней системы дополняется параметром responseErrorSettings. В нём задают шаблон JSON с кодом, сообщением и перечнем невалидных полей. При проверках на стенде DATAREON Platform 3.2 неверные запросы возвращали HTTP 400, а успешные — HTTP 200. Для бизнес-правил обработчик собирал имена полей через NotValidFields и передавал их в ValidateParametersException.
Что это меняет
Главная эксплуатационная особенность проявилась при нескольких ошибках одновременно. Сначала система сообщала, например, о невозможности прочитать количество и цену, а несоответствие буквенного кода обнаруживалось только после исправления типов. Получателю необходимо быть готовым к последовательным раундам исправления одного документа. Кроме того, поля, которых нет в объявленной схеме, в рассматриваемом варианте не попадают в переменную обработчика и не считаются ошибкой автоматически.
Из этого опыта следует практическая граница ответственности: структура данных отвечает за преобразование типов, код — за ограничения предметной области, конфигурация адаптера — за стабильный формат ответа. Такой подход помогает сделать ошибки интеграции предсказуемыми, но не заменяет согласования схемы с отправителями и проверки поведения на конкретной версии платформы.
Первоисточник
Материал подготовлен STRUCTURE по открытой публикации Habr. Текст и иллюстрации первоисточника не воспроизводятся целиком.