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.

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": nullse 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í:
- 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; - 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;
- 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;
- 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.