Руководство по конвертации JSON в типы TypeScript

Зачем конвертировать JSON в типы TypeScript

При взаимодействии фронтенда и бэкенда ответы API обычно представлены в формате JSON. Написание интерфейсов TypeScript вручную занимает много времени и подвержено ошибкам, особенно когда интерфейсы имеют много полей и глубокую вложенность. Автоматическая генерация определений типов позволяет:

• Сократить усилия по написанию интерфейсов вручную
• Предотвратить опечатки в именах полей
• Поддерживать согласованность типов между фронтендом и бэкендом
• Ускорить автодополнение и рефакторинг кода

Базовые правила конвертации

Простой объект

{
  "id": 1,
  "name": "Alice",
  "active": true
}

Сгенерированный результат:

interface RootObject {
  id: number;
  name: string;
  active: boolean;
}

Правила маппинга типов

Значение JSON	Тип TypeScript
"hello"	string
42	number
3.14	number
true / false	boolean
null	null
[1, 2, 3]	number[]
{"a": 1}	Вложенный интерфейс

Использование Инструмента JSON→TypeScript

Шаг 1: Получить данные JSON

Скопируйте ответ API из панели Network в DevTools браузера или вставьте существующие данные JSON напрямую.

Шаг 2: Открыть инструмент

Перейдите к Инструменту JSON→TypeScript и вставьте ваш JSON в область ввода.

Шаг 3: Настроить параметры генерации

• Имя корневого интерфейса: По умолчанию RootObject; используйте семантическое имя, например UserInfo
• Модификатор экспорта: Выберите interface или type
• Опциональные поля: Должны ли поля со значениями null быть помечены как опциональные (?)
• Модификатор readonly: Добавлять ли readonly ко всем полям

Шаг 4: Сгенерировать и скопировать

Нажмите кнопку генерации. Определение типа TypeScript появится мгновенно — скопируйте его в буфер обмена одним кликом.

Обработка вложенных объектов

Глубоко вложенный JSON автоматически разбивается на несколько интерфейсов:

{
  "user": {
    "profile": {
      "avatar": "url",
      "bio": "text"
    }
  }
}

Результат генерации:

interface Profile {
  avatar: string;
  bio: string;
}

interface User {
  profile: Profile;
}

interface RootObject {
  user: User;
}

Рекомендуется разбивать сгенерированные интерфейсы на отдельные файлы, организованные по модулям.

Обработка объединённых типов

Когда массив содержит элементы разных типов:

{
  "items": ["text", 42, true]
}

Инструмент генерирует объединённый тип:

interface RootObject {
  items: (string | number | boolean)[];
}

Обработка опциональных полей

Некоторые поля в ответах API могут отсутствовать. Распространённые подходы:

• Когда значение поля null, пометить его как опциональное: bio?: string | null
• Когда поле отсутствует, пометить его как опциональное: bio?: string
• Включить «Помечать null-поля как опциональные» в инструменте для автоматической обработки

На практике: Генерация типов из реального API

1. Откройте DevTools браузера → панель Network
2. Найдите целевой запрос API, правый клик → Копировать ответ
3. Вставьте в Инструмент JSON→TypeScript
4. Установите имя корневого интерфейса (напр. ApiResponse)
5. Скопируйте сгенерированный результат в каталог types/ вашего проекта

Частые проблемы

Проблема	Причина	Решение
Типы слишком специфичны	Выведены из одного образца данных	Добавить больше образцов данных
Вложенность слишком глубокая	Сложная структура JSON	Вручную объединить некоторые интерфейсы
Несогласованные типы элементов массива	Массивы смешанных типов	Использовать объединённые типы или дженерики
Даты становятся string	JSON не имеет типа даты	Вручную изменить на тип Date

Продвинутые советы

1. Форматируйте JSON с помощью Форматера JSON перед генерацией типов
2. Используйте тот же подход с Инструментом JSON→Go для генерации Go-структур
3. Комбинируйте сгенерированные интерфейсы с Zod для валидации во время выполнения
4. Для крупных проектов используйте openapi-typescript для генерации из Swagger

Итоги

Автоматическая генерация типов TypeScript из JSON — мощный способ повысить эффективность разработки. Инструмент JSON→TypeScript позволяет завершить определение типов за секунды, избегая утомительности и ошибок ручного написания. В сочетании с техниками вложенности и опциональных полей из этого руководства вы сможете обработать любой сложный сценарий.