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 лише коли справді потрібна розрізнюваність.