YamlBox

Статья-путеводитель · 6 минута чтения

Генерируйте типы TypeScript из JSON, которые говорят правду

Шаг от JSON до TypeScript обычно начинается с копирования ответа API в редактор и написания интерфейса вручную — небольшая задача, которая скрывает большой риск: типы, которые вы пишете, описывают один ответ, который вы видели, а не ответы, которые вызовут ваши пользователи.

Обновлено

От JSON до TypeScript: начните с репрезентативной полезной нагрузки, а не с счастливой.

Генератор может сделать вывод только о том, что показывает ваш образец. Получите ответ, включающий неудобные случаи: запись с наличием необязательного поля и запись без него, ноль, пустой массив, десятичное число. Один хороший образец лучше пяти чистых.

Необязательные поля берутся из массивов

Учитывая один объект, каждый ключ выглядит обязательным. Учитывая массив объектов, генератор может сравнивать элементы: ключ, отсутствующий в некоторых элементах, является необязательным (ключ?: строка), а ключ, присутствующий везде, является обязательным. Вот почему вставка списка записей дает значительно лучшие типы, чем вставка одной записи.

Честно моделируйте нули

                // One sample with "deleted_at": null and one with a date
interface User {
  id: number;
  deleted_at: string | null;   // not string, not optional
}

ноль и неопределенное - это разные вещи. Поле, допускающее значение NULL, присутствует со значением NULL; необязательное поле может вообще отсутствовать. Генераторы, которые сворачивают эти два интерфейса, создают интерфейсы, которые проверяют типы, хотя и оказываются неправильными — самая дорогая ошибка, потому что компилятор перестает вас предупреждать.

Профсоюзы побеждают любого

Когда поле представляет собой строку в одной записи и число в другой (существуют запутанные API), честным типом является строка | число. Возврат к любому или неизвестному заставляет компилятор молчать и переводит ошибку в производство. Генератор, который сообщает о профсоюзе, по крайней мере, документирует реальность, и вы можете затем спросить команду API, почему.

Типы создаются во время компиляции; проверять во время выполнения

  • TypeScript исчезает во время выполнения. Ничто не препятствует появлению искаженных полезных данных в форме, запрещенной вашим интерфейсом.
  • Используйте сгенерированные типы для описания того, что вы ожидаете, а также валидатор времени выполнения (Zod, Valibot или схему JSON с AJV) на границе, где данные поступают в ваше приложение.
  • Создание схемы JSON из того же образца дает вам половину времени выполнения — проверку схемы и документирование интерфейсов.

Сохранять типы заново, а не перепечатывать

Шрифты, написанные от руки, отклоняются от API. Относитесь к генератору как к этапу вашего рабочего процесса: вставьте новый ответ, повторно сгенерируйте его, вставьте в файл типов и позвольте компилятору показать вам каждое место, где было изменено API. Это самый дешевый 2-дрейфовый детектор — и он стоит тридцать секунд.

Попробуйте это с генератором от JSON до TypeScript — вывод интерфейса или типа, обнаружены дополнительные ключи, союзы сохранены.