Генератор структур JSON в TypeScript / Go / Rust

Генерирует идиоматические типы в вашем целевом языке, выводя схему из одного или нескольких образцов JSON. Типы полей выводятся — строки остаются строками, числа становятся числовым типом языка, булевы — bool, массивы — slices/списками/массивами, вложенные объекты — вложенными типами. Опциональные поля (которые иногда null или отсутствуют между образцами) помечаются как nullable в выводе. На базе quicktype-core, того же движка, что стоит за quicktype.io.

Пример

Вход JSON:

{
  "name": "Ada",
  "age": 36,
  "active": true,
  "tags": ["math", "logic"]
}

Выход TypeScript (цель = TypeScript, имя типа = User):

export interface User {
  name: string;
  age: number;
  active: boolean;
  tags: string[];
}

Типичные ловушки и как с ними справляться

У вывода типов из JSON есть фундаментальные пределы — JSON не несёт достаточно информации, чтобы полностью ограничить систему типов. Шаблоны ниже описывают, где выведенный тип может не совпадать с тем, что вы хотите.

• Опциональный vs. обязательный по одному образцу. Один JSON-объект не может сказать генератору, какие поля опциональные. Передайте несколько образцов (вставьте JSON-массив репрезентативных объектов), чтобы генератор мог пометить иногда отсутствующие поля как опциональные.
• Пустые массивы. `{"items": []}` даёт массив `any` — у генератора нет элемента для вывода. Включите хотя бы один заполненный пример или поправьте тип вручную после генерации.
• Гетерогенные элементы массива. JSON-массив `[1, "two"]` становится union-типом — результат может быть неудобен в некоторых целевых языках (особенно Go). Если массив должен быть однородным в реальных данных, поправьте образец.
• Строки дат. У JSON нет типа Date. ISO 8601-строки дат выводятся как `string`. quicktype иногда может определить их как Date в выводе TypeScript — настройте вручную, если нужна более строгая типизация.
• Числовые ID, теряющие точность. JSON-числа > 2^53 (большие 64-битные ID) теряют точность при парсинге JavaScript. Сгенерированный TypeScript-тип всё равно использует `number`. Для 64-битной точности используйте `string` в JSON или мигрируйте на `bigint`-тип вручную.
• Поля с подчёркиванием vs. camelCase. Генератор сохраняет именование полей JSON. Если ваш JSON использует snake_case, а целевой язык ожидает camelCase, вывод использует snake_case-поля с serde/json-аннотациями там, где это применимо. Переопределите постобработкой или флагами CLI quicktype.

Почему первая генерация медленная?

Бандл движка quicktype составляет около 465 КБ gzipped. Он загружается при первом клике «Сгенерировать», что занимает 2–3 секунды на 4G. После этого модуль кэшируется на остаток сессии страницы — и браузер кэширует его между визитами, так что последующие первые клики тоже мгновенные, если кэш не очищали.

Можно ли генерировать из нескольких JSON-образцов?

Оберните образцы в JSON-массив и вставьте массив. Генератор выводит объединение полей, увиденных среди образцов, и помечает поля как опциональные, когда они отсутствуют хотя бы в одном. Это правильный способ обеспечить, что сгенерированные типы выдерживают вариации в реальных данных.

Какой язык выбрать для backend-кода?

Соответствуйте тому, что уже использует ваш проект. Вывод Go использует стандартные struct-теги для `encoding/json`. Rust использует serde-derive. Kotlin использует kotlinx.serialization-аннотации. Java выдаёт POJO, совместимые с Jackson. Выбор зависит от проекта, а не от предпочтений.

Сохраняются ли комментарии полей?

У JSON нет синтаксиса комментариев, поэтому в вводе нет комментариев для переноса. quicktype может включать doc-комментарии в вывод для некоторых языков — это автогенерируемые описания, а не пользовательский контент.

Загружается ли мой JSON?

Нет. Всё работает в вашем браузере — ввод обрабатывается локально модулем JavaScript quicktype-core на этой странице. Сам quicktype-core загружается с того же origin (хост статических ассетов этого сайта); ни один сторонний сервер не видит ваши данные.

Какого размера JSON-образец можно использовать?

До примерно 5 МБ JSON, прежде чем генератор начнёт занимать заметное время. Генератор предназначен для репрезентативных образцов, а не полных датасетов — обычно горстки объектов достаточно, чтобы вывести чистую схему.