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. Текст и иллюстрации первоисточника не воспроизводятся целиком.