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

Сначала вывод: структуры, которые конвертер выдаёт за десять секунд, компилируются, но не готовы к продакшену. Генератор описывает только тот единственный образец, который вы вставили — числа становятся 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
}
Чек-лист из четырёх шагов после генерации
Четыре шага отделяют вывод генератора от продакшен-кода, и пройти их один раз дешевле, чем потом отлаживать:
- Замените каждый fallback any: найдите
any, проверьте три-пять реальных образцов по каждому fallback-полю, затем приземлите в конкретный тип или указатель; - Перепроверьте числовые разряды: перенесите ID, суммы и счётчики с float64 на int64 / int32 / decimal; при сомнении в разрядности пишите int64;
- Разметьте опциональность: указатели или omitempty/omitzero для полей объектов в массивах, PATCH-телах и nullable-полях сторонних API — семантику nil решите один раз, здесь;
- Скомпилируйте и протестируйте туда-обратно: запустите
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 только когда действительно нужна различимость.