JSON Toolkit

JSON na Go Struct: generátor dodá kostru, čtyři věci vyžadují vaše ruce

Shrnutí: Vložte vzorkovou odpověď API do konvertoru a za deset sekund máte struktury Go s tagy — ale čísla se stanou float64, volitelná pole se sama nikdy nestanou ukazateli, omitempty nesundá prázdné struktury a většina dat zůstane string. Úplná mapovací tabulka, rovnováha mezi ukazatelem a omitzero a čtyřkrokový kontrolní seznam pro doladění vygenerovaného kódu.

Střední~6 min čteníPublikováno 2026-11-22Aktualizováno 2026-11-22
Převod vzorku JSON na kód struktury Go pomocí online nástroje

Nejprve závěr: struktury, které konvertor vyprodukuje za deset sekund, se zkompilují, ale nejsou připraveny na produkci. Generátor popisuje jen ten jediný vzorek, který jste vložili — čísla se stanou float64, volitelná pole se sama nikdy nestanou ukazateli, omitempty nesundá prázdné struktury a většina řetězců s daty zůstane string. Tyto čtyři mezery zůstávají po vložení vaší prací.

Přeměnit odpověď API na struktury Go je čistě mechanická práce a náklad mechanické práce se skrývá v tichu: jméno pole s překlepem nevyvolá chybu kompilace, jen pole navždy zůstane nulou; špatný přepínač v práci s null — a "note": null se objeví v produkci tam, kde ho nikdo nečekal. Generování struktur řeší zarovnání jmen a typů, ale dvě věci se nikdy nezarovnají samy: varianty mimo váš vzorek a propast mezi typovým systémem Go a JSON.

Co generátor skutečně čte: mapovací tabulka

Každý konvertor JSON → Go běží na téže tabulce. Prohoďte typickou odpověď objednávky stránkou /convert/go tohoto webu — vložte vzorek, zapněte json tagy — a dostanete tento tvar:

Hodnota JSON Vygenerovaný typ Go Poznámky
string string Řetězce s daty obvykle zůstávají string, viz time.Time níže
celé číslo float64 encoding/json parsuje čísla uvnitř jako double
desetinné float64 Peněžní pole nahraďte decimal knihovnou nebo int64 v menších jednotkách
true / false bool Bez pastí
null any Jediný vzorek null nic nedokazuje, konzervativní fallback
objekt pojmenovaná struktura Vnořené objekty se stanou vlastní strukturou
prázdný objekt {} map[string]any Žádná pozorovatelná pole, generátor neuhádne
pole (array) []TypPrvku Typ prvku odvozen z prvního vzorku
smíšené typy any Go nemá union, pole s více typy spadnou do any
// Vstupní vzorek
// {"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"`
}

Tři pozorování. Vnořený objekt items se stal vlastní strukturou Item, na kterou odkazuje slice. coupon se objevil jen jako null: generátor nemůže dokázat, čím bude později, a spadne do any. Číslo qty přistane jako int nebo float64 podle nástroje — strategie se liší, ale všechny opírají o stejné předpoklady: vzorek je celá pravda.

Json tagy: původní názvy, volby a tři snadné chyby

Tagy nesou nejvyšší hustotu informací ve výstupu generátoru a zároveň jsou částí, ve které se při úpravách nejsnáze chybuje. Pravidla jdou přímo z dokumentace encoding/json:

Field int `json:"myName"`            // objeví se pod klíčem myName
Field int `json:"myName,omitempty"`  // celé pole vynecháno, když je prázdné
Field int `json:",omitempty"`        // výchozí název pole, jen volba
Field int `json:"-"`                 // vždy ignorováno, ani kódovat, ani dekódovat
Field int64 `json:"id,string"`       // číslo zakódované uvnitř řetězce

Tři nedbalosti stojí za zapamatování. Za prvé, úvodní čárka v json:",omitempty" — když chcete jen přeskočit prázdné hodnoty, aniž přejmenujete klíč, čárka je povinná; bez ní je pole považováno za klíč doslova pojmenovaný ,omitempty. Za druhé, ponechte původní JSON klíč v tagu (user_id, html_url), zatímco pole Go používá idiomatickou konvenci (UserID, HTMLURL): bez tagu se párování řídí doslova názvem pole, takže klíč userId v odpovědi se nikdy nezmapuje — potichu. Za třetí, kromě json:"-" existuje i json:"-," — to druhé znamená, že klíč se opravdu jmenuje -.

Ukazatele: nil je jediný způsob, jak rozlišit „chybí" od „nula"

Systém nulových hodnot Go nedovoluje int a string vyjádřit „pole není přítomno" — 0 a "" mohou být skutečná data, nebo jen neparsovaná. Tentýž JSON klíč má tři stavy: přítomný s hodnotou, přítomný jako null a chybějící. Typy podle hodnoty pokrývají jen první.

type Config struct {
  Note    string  `json:"note,omitempty"`   // vynecháno jen když přesně ""
  Alias   *string `json:"alias,omitempty"`  // vynecháno, když nil
  Details *Meta   `json:"details,omitempty"`
}

Nulová hodnota pole-ukazatele je nil. json.Unmarshal ho nechá nil, když klíč chybí nebo je null, a omitempty ho přeskočí jen v tomto případě. Proto většina konvertorů nabízí přepínač „použít ukazatele pro vnořené objekty": zapnutý — vnořené struktury se stanou *Item, a v PATCH požadavku se „pole nebylo odesláno" a „null odesláno ke smazání" konečně rozdělí. Cena jsou kontroly nil všude — p.Address.Street spadne do paniky, když Address je nil, jeden z nejčastějších runtime pádů v JSON kódu v Go.

Prázdná struktura, kterou omitempty nesundá, a díra, kterou zaplní omitzero

Oficiální definice omitempty soudí podle hodnot: false, 0, nil ukazatele, nil interface a pole, slices, map nebo řetězce nulové délky. Všimněte si, co v seznamu není: prázdné struktury.

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 neudělal nic

Pole-struktura se nikdy nevynechá omitempty — žije v paměti jako kontejner pevné velikosti a existující kontejner není „prázdný". Oprava je přeměnit pole na *Meta; zahodí se jen nil ukazatel. Od Go 1.24 existuje druhý přepínač, omitzero: soudí podle nulové hodnoty Go, voláním IsZero() bool, když ji typ definuje — jediný způsob, jak vynechat nulový time.Time. S encoding/json/v2 (experimentálním v Go 1.25) se semantika posune znovu: omitempty ve v2 soudí podle zakódovaného JSON výsledku (jen null, "", {}, [] se počítají jako prázdné), takže count: 0 zůstane ve výstupu; při migraci starého kódu musí omitempty na bool a číselných polích přejít na omitzero, aby se zachoval původní smysl.

Každé číslo se stane float64: past velkých celých čísel

Bez explicitního typu zachází dekodér encoding/json s čísly jako s float64 a float64 má jen 53 bitů mantisy. Klasický případ JavaScriptu — 9007199254740993 se stane 9007199254740992 — existuje i v Go, dokud cílové pole je float64 nebo any.

var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] je float64(9007199254740992), přesnost už ztracena

Tři východy. Deklarujte pole struktury jako int64 a dekodér parsuje přesně do něj. Když musíte jít přes any, zavolejte decoder.UseNumber(), aby čísla přistála jako řetězce json.Number, které převádíte vědomě. Nikdy nepoužívejte plovoucí desetinnou čárku na peníze — uchovávejte menší jednotky v int64 nebo použijte decimal knihovnu. Pokaždé, když API vrací snowflake ID nebo 64bitová čísla objednávek, je tento oddíl povinnou kontrolou.

time.Time přijímá pouze RFC 3339

Před "2024-01-15T10:30:00Z" generátor namapuje time.Time; před "2024-01-15 10:30:00" zanechá string. Není to lhostejnost — je to tvrdé omezení encoding/json: time.Time implementuje UnmarshalJSON a parsuje striktně v layoutu RFC 3339 2006-01-02T15:04:05Z07:00. Chybějící T, chybějící časová zóna nebo Z následovaná offsetem — vše selže:

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

Když formát upstream nelze změnit, standardní opravou je vlastní typ obalující time.Time, jehož UnmarshalJSON zkouší několik 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
}

Čtyřkrokový kontrolní seznam po generování

Čtyři kroky oddělují výstup generátoru od produkčního kódu a jejich jedno projití stojí méně než pozdější ladění:

  1. Nahraďte každý fallback any: najděte any, zkontrolujte tři až pět reálných vzorků pro každé fallback pole a pak přistaňte na konkrétním typu nebo ukazateli;
  2. Znovu ověřte číselné šířky: přeneste ID, částky a počítadla z float64 na int64 / int32 / decimal; při pochybnostech o šířce pište int64;
  3. Označte volitelnost: ukazatele nebo omitempty/omitzero pro pole objektů v polích, PATCH tělesech a nullable polích cizích API — sémantiku nil rozhodněte jednou, zde;
  4. Zkompilujte a testujte tam a zpět: spusťte go vet, pak přidejte test tam a zpět Marshal→Unmarshal, aby se zafixoval formát na drátu — to chytá drift chování budoucích aktualizací encoding/json.

Od vzorku ke kontraktu: hranice konvertoru

Konvertor odpovídá na otázku „jak vypadá tento vzorek", ne „jak bude tento interface vypadat vždy". Konkurenční nástroje to říkají přímo ve vlastní dokumentaci: vzorek nedokáže prokázat produkční varianty — volitelnost, formáty dat a hodnoty výčtů vyžadují lidskou kontrolu. Takže si vybudujte návyk: před vložením seberte odpovědi nejvíce náchylné odhalit rozdíly (prázdný seznam, všechna pole, jeden s null); po generování berte výstup jako návrh, ne jako dodávku. Pokud interface má dokument kontraktu, udělejte omezení explicitními přes JSON Schema a vyrovnejte vygenerovaný kód podle něj — to poráží odvození ze vzorků o řád. Pro příčný pohled na tentýž problém je Java strana probrána v našem polygonovém testu Java generátoru, frontend kontrakt v TypeScript rozhraních; propast číselné přesnosti se vrací v každém jazyce v jiném kostýmu, podrobně v pasti velkých čísel JSON.

Která pole po generování stále vyžadují ruční kontrolu?

Nejméně čtyři: fallbacky any, číselné šířky (float64 → int64), přeměna volitelných polí na ukazatele a otázka, zda mají být pole dat string nebo time.Time. Všechny čtyři jsou produkční varianty neviditelné ve vzorku; generátor neuhádne, člověk musí doplnit.

Proč se mé pole stále objevuje v JSON po přidání omitempty?

omitempty přeskočí jen nulové hodnoty: false, 0, "", nil, prázdné slices. Prázdná struktura {} není nulová hodnota, takže přežije — přeměňte pole na ukazatel. Nulový time.Time potřebuje omitzero, ne omitempty.

Proč se moje velké celé ID po deserializaci změnilo?

Bez explicitního typu parsuje encoding/json čísla jako float64, který má 53 bitů mantisy; celá čísla za hranicí 2^53 ztrácejí přesnost. Typujte pole jako int64, nebo zavolejte UseNumber(), aby čísla zůstala jako json.Number.

Kdy má být vnořené pole objektu ukazatel?

Dva případy: pole může chybět nebo být null (nil odděluje „neodesláno" od „nulové hodnoty") a PATCH požadavek musí rozlišovat „neodesláno" a „null odesláno ke smazání". V běžných strukturtách odpovědí s non-nullable poli jsou typy podle hodnoty bezpečnější — plaťte za kontroly nil jen když rozlišování opravdu potřebujete.

Zdroje

Související články

JSON na třídu Java: generátor dá kostru, pro produkci chybí ještě pět věcí

Praktický pohled na to, co generátor JSON-to-Java skutečně emituje — čísla se stanou Double, vnořené objekty statickými vnitřními třídami a nevyprodukuje se jediná Jacksonova anotace. Peněžní přesnost, přejmenování polí, smazání typů, neznámá pole a data jsou pět věcí, které musíte doplnit sami, každý s kódem připraveným ke zkopírování.

Středně pokročilý~10 min čteníAktualizováno 2026-11-04

Proč velká celá čísla ztrácejí přesnost

Celá čísla nad 2^53-1 ztrácejí přesnost v `JSON.parse`. Snowflake ID, čísla objednávek i bigint primární klíče databází to zasahuje, proto je udržujte jako řetězce od začátku do konce.

Středně pokročilý~4 min čteníAktualizováno 2026-11-04