JSON Toolkit

JSON в Go Struct: генератор отдаёт скелет, четыре вещи требуют ваших рук

Главное: Вставьте пример ответа API в конвертер, и через десять секунд у вас есть структуры Go с тегами — но числа становятся float64, необязательные поля сами никогда не становятся указателями, omitempty не убирает пустые структуры, а большинство дат остаётся строкой. Полная таблица маппинга, баланс между указателем и omitzero и чек-лист из четырёх шагов для доводки сгенерированного кода.

Средний~6 мин чтенияОпубликовано 2026-11-22Обновлено 2026-11-22
Преобразование примера JSON в код структуры Go с помощью онлайн-инструмента

Сначала вывод: структуры, которые конвертер выдаёт за десять секунд, компилируются, но не готовы к продакшену. Генератор описывает только тот единственный образец, который вы вставили — числа становятся float64, необязательные поля сами никогда не становятся указателями, omitempty не убирает пустые структуры, а большинство строк с датами остаются строками. Эти четыре пробела после вставки остаются вашей работой.

Превратить ответ API в структуры Go — работа чисто механическая, и стоимость механической работы прячется в тишине: имя поля с опечаткой не вызывает ошибку компиляции, просто поле навсегда остаётся нулём; неверный переключатель в обработке null — и "note": null появляется в продакшене там, где его не ждали. Генерация структур решает выравнивание имён и типов, но две вещи никогда не выравниваются сами: варианты за пределами вашего образца и пропасть между системой типов Go и JSON.

Что генератор реально читает: таблица маппинга

Каждый конвертер JSON → Go работает по одной и той же таблице. Пропустите типичный ответ заказа через страницу /convert/go этого сайта — вставьте образец, включите json-теги — и получите такой вид:

Значение JSON Сгенерированный тип Go Примечания
string string Строки с датами обычно остаются строками, см. time.Time ниже
целое float64 encoding/json разбирает числа внутри как double
десятичное float64 Денежные поля замените на decimal-библиотеку или int64 в мелких единицах
true / false bool Без ловушек
null any Один образец null ничего не доказывает, консервативный fallback
объект именованная структура Вложенные объекты становятся собственной структурой
пустой объект {} map[string]any Нет наблюдаемых полей, генератор не угадывает
массив []ТипЭлемента Тип элемента выведен из первого образца
смешанные типы any У Go нет union, поля с несколькими типами падают в any
// Входной образец
// {"id":"A-1029","items":[{"sku":"J-01","qty":2}],"coupon":null}
type Root struct {
  ID     string `json:"id"`
  Items  []Item `json:"items"`
  Coupon any    `json:"coupon"`
}

type Item struct {
  Sku string `json:"sku"`
  Qty int    `json:"qty"`
}

Три наблюдения. Вложенный объект items стал собственной структурой Item, на которую ссылается slice. coupon появился только как null: генератор не может доказать, чем он будет потом, и падает в any. Число qty приземляется как int или float64 в зависимости от инструмента — стратегии различаются, но все опираются на одно допущение: образец — вся правда.

Json-теги: оригинальные имена, опции и три лёгкие ошибки

Теги несут наибольшую плотность информации в выводе генератора и одновременно являются самой лёгкой частью для ошибки при правках. Правила идут прямо из документации encoding/json:

Field int `json:"myName"`            // появляется под ключом myName
Field int `json:"myName,omitempty"`  // целое поле опущено, когда пустое
Field int `json:",omitempty"`        // имя поля по умолчанию, только опция
Field int `json:"-"`                 // всегда игнорируется, ни кодировать, ни декодировать
Field int64 `json:"id,string"`       // число закодировано внутри строки

Три небрежности стоит запомнить. Во-первых, ведущая запятая в json:",omitempty" — когда вы хотите лишь пропускать пустые значения, не переименовывая ключ, запятая обязательна; без неё поле трактуется как ключ, буквально называемый ,omitempty. Во-вторых, сохраняйте оригинальный JSON-ключ в теге (user_id, html_url), пока поле Go использует идиоматическую конвенцию (UserID, HTMLURL): без тега сопоставление идёт буквально по имени поля, поэтому ключ userId в ответе никогда не смапится — молча. В-третьих, помимо json:"-" существует json:"-," — последнее означает, что ключ действительно называется -.

Указатели: nil — единственный способ отличить «отсутствует» от «ноль»

Система нулевых значений Go не позволяет int и string выразить «поле отсутствует» — 0 и "" могут быть реальными данными или просто не разобранными. Один и тот же ключ JSON имеет три состояния: присутствует со значением, присутствует как null и отсутствует. Типы по значению покрывают только первое.

type Config struct {
  Note    string  `json:"note,omitempty"`   // опущено только когда ровно ""
  Alias   *string `json:"alias,omitempty"`  // опущено, когда nil
  Details *Meta   `json:"details,omitempty"`
}

Нулевое значение поля-указателя — nil. json.Unmarshal оставляет его nil, когда ключ отсутствует или null, и omitempty пропускает его только в этом случае. Поэтому большинство конвертеров предлагают переключатель «использовать указатели для вложенных объектов»: включён — вложенные структуры становятся *Item, и в PATCH-запросе «поле не отправлено» и «null отправлен для удаления» наконец разделяются. Цена — проверки nil повсюду — p.Address.Street паникует, когда Address равен nil, один из самых частых runtime-крэшей в JSON-коде на Go.

Пустая структура, которую omitempty не может убрать, и дыра, которую закрывает omitzero

Официальное определение omitempty судит по значениям: false, 0, nil-указатели, nil-интерфейсы и массивы, slices, map или строки нулевой длины. Заметьте, чего нет в списке: пустых структур.

type Order struct {
  Meta Meta `json:"meta,omitempty"`
}
type Meta struct {
  Version string
  Build   int
}

// Meta{Version: "1.0"} → "meta":{"version":"1.0","build":0}
// Meta{}              → "meta":{}   ← omitempty ничего не сделал

Поле-структура никогда не опускается omitempty — оно живёт в памяти как контейнер фиксированного размера, а существующий контейнер не «пуст». Исправление — превратить поле в *Meta; отбрасывается только nil-указатель. С Go 1.24 есть второй переключатель, omitzero: судит по нулевому значению Go, вызывая IsZero() bool, когда тип его определяет — единственный способ опустить нулевой time.Time. С encoding/json/v2 (экспериментальным в Go 1.25) семантика снова сдвигается: omitempty в v2 судит по закодированному JSON-результату (только null, "", {}, [] считаются пустыми), поэтому count: 0 остаётся в выводе; при миграции старого кода omitempty на bool- и числовых полях должен превратиться в omitzero, чтобы сохранить исходный смысл.

Каждое число становится float64: ловушка больших целых

Без явного типа декодер encoding/json трактует числа как float64, а у float64 только 53 бита мантиссы. Классический случай JavaScript — 9007199254740993, становящийся 9007199254740992, — существует и в Go, пока целевое поле float64 или any.

var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] — float64(9007199254740992), точность уже потеряна

Три выхода. Объявите поле структуры как int64, и декодер разберёт точно в него. Когда нужно пройти через any, вызовите decoder.UseNumber(), чтобы числа приземлились как строки json.Number, которые вы конвертируете осознанно. Никогда не используйте плавающую точку для денег — храните мелкие единицы в int64 или используйте decimal-библиотеку. Всякий раз, когда API возвращает snowflake-ID или 64-битные номера заказов, этот раздел — обязательная проверка.

time.Time принимает только RFC 3339

Перед "2024-01-15T10:30:00Z" генератор мапит time.Time; перед "2024-01-15 10:30:00" оставляет строку. Это не лень — жёсткое ограничение encoding/json: time.Time реализует UnmarshalJSON и разбирает строго в layout RFC 3339 2006-01-02T15:04:05Z07:00. Пропущенная T, пропущенный часовой пояс или Z с последующим offset — всё падает:

parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""

Когда формат upstream нельзя изменить, стандартное исправление — пользовательский тип, оборачивающий time.Time, чей UnmarshalJSON пробует несколько layout'ов:

type CustomDate struct{ time.Time }

func (c *CustomDate) UnmarshalJSON(b []byte) error {
  s := strings.Trim(string(b), `"`)
  t, err := time.Parse("2006-01-02 15:04:05", s)
  if err != nil {
    t, err = time.Parse(time.RFC3339, s)
    if err != nil {
      return fmt.Errorf("invalid date format: %w", err)
    }
  }
  c.Time = t
  return nil
}

Чек-лист из четырёх шагов после генерации

Четыре шага отделяют вывод генератора от продакшен-кода, и пройти их один раз дешевле, чем потом отлаживать:

  1. Замените каждый fallback any: найдите any, проверьте три-пять реальных образцов по каждому fallback-полю, затем приземлите в конкретный тип или указатель;
  2. Перепроверьте числовые разряды: перенесите ID, суммы и счётчики с float64 на int64 / int32 / decimal; при сомнении в разрядности пишите int64;
  3. Разметьте опциональность: указатели или omitempty/omitzero для полей объектов в массивах, PATCH-телах и nullable-полях сторонних API — семантику nil решите один раз, здесь;
  4. Скомпилируйте и протестируйте туда-обратно: запустите go vet, затем добавьте тест туда-обратно Marshal→Unmarshal, чтобы зафиксировать проводной формат — это ловит дрейф поведения будущих обновлений encoding/json.

От образца к контракту: граница конвертера

Конвертер отвечает на вопрос «как выглядит этот образец», а не «как всегда будет выглядеть этот интерфейс». Конкурирующие инструменты говорят это прямо в собственной документации: образец не может доказать варианты продакшена — опциональность, форматы дат и значения перечислений требуют человеческой проверки. Так что стройте привычку: перед вставкой соберите ответы, наиболее склонные обнажить различия (пустой список, все поля, один с null); после генерации считайте вывод черновиком, а не сдачей. Если у интерфейса есть документ-контракт, сделайте ограничения явными через JSON Schema и выровняйте сгенерированный код по нему — это бьёт вывод из образцов на порядок. Для поперечного взгляда на ту же проблему Java-сторона освещена в нашем полигонном тесте Java-генератора, фронтенд-контракт — в интерфейсах TypeScript; пропасть числовой точности возвращается в каждом языке в другом костюме, подробно в ловушке больших чисел JSON.

Какие поля всё ещё требуют ручной правки после генерации?

Как минимум четыре: fallback'и any, числовые разряды (float64 → int64), превращение необязательных полей в указатели и вопрос, быть ли полям дат string или time.Time. Все четыре — варианты продакшена, невидимые в образце; генератор не угадывает, человек должен дополнить.

Почему моё поле всё ещё появляется в JSON после добавления omitempty?

omitempty пропускает только нулевые значения: false, 0, "", nil, пустые slices. Пустая структура {} не является нулевым значением, поэтому выживает — превратите поле в указатель. Нулевому time.Time нужен omitzero, а не omitempty.

Почему мой большой целый ID изменился после десериализации?

Без явного типа encoding/json разбирает числа как float64, у которого 53 бита мантиссы; целые за пределами 2^53 теряют точность. Типизируйте поле как int64 или вызовите UseNumber(), чтобы сохранить числа как json.Number.

Когда вложенное поле-объект должно быть указателем?

Два случая: поле может отсутствовать или быть null (nil отделяет «не отправлено» от «нулевого значения»), и PATCH-запрос должен различать «не отправлено» и «null отправлен для удаления». В обычных структурах ответов с non-nullable полями типы по значению безопаснее — платите за проверки nil только когда действительно нужна различимость.

Источники

Похожие статьи

JSON в Java-класс: генератор даёт каркас, для продакшена нужно ещё пять вещей

Практический замер того, что реально отдаёт генератор JSON → Java——числа становятся Double, вложенные объекты — статическими внутренними классами, и ни одной аннотации Jackson. Точность денег, переименование полей, стирание генериков, неизвестные поля и даты — пять вещей, которые придётся добавить руками, с кодом, готовым к копированию.

Средний~10 мин чтенияОбновлено 2026-11-04

JSON в TypeScript: интерфейсы, type guards и пределы генерации

Генерация интерфейса по примеру JSON — половина работы: необязательные поля, null, объединения, даты и большие целые требуют ручной правки, а типы не дают валидации во время выполнения.

Средний~9 мин чтенияОбновлено 2026-11-04

Почему большие целые теряют точность

Целые выше 2^53-1 теряют точность в JSON.parse. Snowflake ID, номера заказов и bigint из базы данных все с этим сталкиваются, поэтому храните их как строки от начала до конца.

Средний~4 мин чтенияОбновлено 2026-11-04