STRUCTUREцифровые системыОбсудить проект
НОВОСТЬ · Engineering

api-contract-check: проверка API по TypeScript-типам без дублирования схем

Разработчик ARFA Generator представил инструмент api-contract-check, который преобразует привычные TypeScript-типы запросов и ответов в схемы проверки реальных данных. Цель проекта — обнаруживать несовпадения контрактов непосредственно при обращении к API.

Главное

Аннотации TypeScript помогают редактору кода и компилятору, но сами по себе исчезают после сборки JavaScript. Поэтому ответ сервера с неожиданным null, пропущенным полем или другой структурой может пройти через типизированный клиент без предупреждения. Автор api-contract-check предлагает перенести проверку из области предположений в момент фактического обмена данными между приложением и сервисом.

На этапе сборки модуль builder анализирует декларации TypeRequest и TypeResponse вместе с необходимыми импортами. Результатом становится обычная структура JavaScript, описывающая ожидаемые поля и типы значений. Её можно сохранить отдельно, передать в другие средства валидации или подключить только там, где выполняется конкретный запрос. Такой вариант не заставляет описывать одинаковую модель вручную в типах приложения и в независимой схеме проверки.

Подробности

Выполняемый в браузере модуль checker работает уже с полученной структурой. Его задача — сопоставить исходящий запрос и входящий ответ с объявленными ограничениями, обнаружить несоответствия и сообщить о лишних свойствах. Автор показывает использование проверки непосредственно внутри общей функции HTTP-запроса, до передачи ответа бизнес-логике. Тогда нарушение договорённости с сервером становится отдельной понятной ошибкой, а не проявляется позже в интерфейсе.

Подход отличается от генерации клиента по OpenAPI: отправной точкой здесь являются модели, которые действительно нужны конкретному интерфейсу. Он также отличается от ручных Zod-подобных схем, поскольку разработчику не приходится параллельно поддерживать второе описание каждого объекта. Однако преимущества зависят от дисциплины команды: сами TypeScript-типы всё равно надо своевременно согласовывать с бэкендом, иначе локальная проверка лишь раньше выявит расхождение.

Что это меняет

api-contract-check входит в набор ARFA Generator и может использоваться отдельно в собственном процессе сборки. Описанные автором оценки скорости генерации и небольшого размера рантайма пока следует воспринимать как результаты его демонстрации, а не независимое сравнение всех валидаторов. Практическая польза для команды состоит прежде всего в явных границах данных, воспроизводимой диагностике и возможности добавить проверку постепенно, начиная с самых важных методов API.

Первоисточник

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

Читать исходную новость целиком ↗