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