JSON na Go Struct: generator dostaje szkielet, cztery rzeczy wymagają twoich rąk
Podsumowanie: Wklej przykładową odpowiedź API do konwertera i w dziesięć sekund masz struktury Go z tagami — ale liczby stają się float64, opcjonalne pola same nigdy nie stają się wskaźnikami, omitempty nie zdejmuje pustych struktur, a większość dat pozostaje stringiem. Pełna tabela mapowania, równowaga między wskaźnikiem a omitzero i czterokrokowa checklista doszlifowania wygenerowanego kodu.

Najpierw wniosek: struktury, które konwerter wyprodukuje w dziesięć sekund, się kompilują, ale nie są gotowe na produkcję. Generator opisuje tylko ten jedyny próbnik, który wkleiłeś — liczby stają się float64, opcjonalne pola same nigdy nie stają się wskaźnikami, omitempty nie zdejmuje pustych struktur, a większość stringów z datami pozostaje stringami. Te cztery luki po wklejeniu pozostają twoją pracą.
Przekształcenie odpowiedzi API w struktury Go to czysto mechaniczna praca, a koszt pracy mechanicznej kryje się w ciszy: nazwa pola z literówką nie wywoła błędu kompilacji, po prostu pole na zawsze zostaje zerem; zły przełącznik w obsłudze null — i
"note": nullpojawia się na produkcji tam, gdzie nikt go nie czekał. Generowanie struktur rozwiązuje wyrównanie nazw i typów, ale dwie rzeczy nigdy nie wyrównują się same: warianty poza twoim próbnikiem i przepaść między systemem typów Go a JSON.
Co generator naprawdę czyta: tabela mapowania
Każdy konwerter JSON → Go działa na tej samej tabeli. Przepuść typową odpowiedź zamówienia przez stronę /convert/go tej witryny — wklej próbnik, włącz tagi json — a otrzymasz ten kształt:
| Wartość JSON | Wygenerowany typ Go | Uwagi |
|---|---|---|
| string | string |
Stringi z datami zwykle pozostają stringami, zobacz time.Time niżej |
| liczba całkowita | float64 |
encoding/json parsuje liczby wewnątrz jako double |
| dziesiętne | float64 |
Pola pieniężne zamień na bibliotekę decimal lub int64 w mniejszych jednostkach |
| true / false | bool |
Bez pułapek |
| null | any |
Jeden próbnik null niczego nie dowodzi, konserwatywny fallback |
| obiekt | nazwana struktura | Zagnieżdżone obiekty stają się własną strukturą |
pusty obiekt {} |
map[string]any |
Brak obserwowalnych pól, generator nie zgaduje |
| tablica | []TypElementu |
Typ elementu wywnioskowany z pierwszej próbki |
| typy mieszane | any |
Go nie ma union, pola z wieloma typami spadają do any |
// Próbka wejściowa
// {"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"`
}
Trzy obserwacje. Zagnieżdżony obiekt items stał się własną strukturą Item, do której odnosi się slice. coupon pojawił się tylko jako null: generator nie może dowieść, czym będzie później, i spada do any. Liczba qty ląduje jako int albo float64 w zależności od narzędzia — strategie się różnią, ale wszystkie opierają się na tym samym założeniu: próbka to cała prawda.
Tagi json: oryginalne nazwy, opcje i trzy łatwe błędy
Tagi niosą największą gęstość informacji w wyjściu generatora i jednocześnie są częścią, w której przy poprawkach najłatwiej o błąd. Reguły idą prosto z dokumentacji encoding/json:
Field int `json:"myName"` // pojawia się pod kluczem myName
Field int `json:"myName,omitempty"` // całe pole pominięte, gdy puste
Field int `json:",omitempty"` // domyślna nazwa pola, tylko opcja
Field int `json:"-"` // zawsze ignorowane, ani kodować, ani dekodować
Field int64 `json:"id,string"` // liczba zakodowana wewnątrz stringa
Trzy niedopatrzenia warto zapamiętać. Po pierwsze, wiodący przecinek w json:",omitempty" — gdy chcesz tylko pomijać puste wartości, bez przemianowania klucza, przecinek jest obowiązkowy; bez niego pole traktowane jest jako klucz dosłownie nazwany ,omitempty. Po drugie, zachowaj oryginalny klucz JSON w tagu (user_id, html_url), podczas gdy pole Go używa idiomatycznej konwencji (UserID, HTMLURL): bez tagu dopasowanie idzie dosłownie po nazwie pola, więc klucz userId w odpowiedzi nigdy się nie zmapuje — po cichu. Po trzecie, oprócz json:"-" istnieje json:"-," — to drugie oznacza, że klucz naprawdę nazywa się -.
Wskaźniki: nil to jedyny sposób odróżnienia „brakuje" od „zero"
System wartości zerowych Go nie pozwala int i string wyrazić „pole nieobecne" — 0 i "" mogą być realnymi danymi albo po prostu nieprzeparsowanymi. Ten sam klucz JSON ma trzy stany: obecny z wartością, obecny jako null i nieobecny. Typy przez wartość pokrywają tylko pierwszy.
type Config struct {
Note string `json:"note,omitempty"` // pominięte tylko gdy dokładnie ""
Alias *string `json:"alias,omitempty"` // pominięte, gdy nil
Details *Meta `json:"details,omitempty"`
}
Wartość zerowa pola-wskaźnika to nil. json.Unmarshal zostawia go nil, gdy klucza brak lub jest null, a omitempty pomija go tylko w tym przypadku. Dlatego większość konwerterów oferuje przełącznik „używaj wskaźników dla zagnieżdżonych obiektów": włączony — zagnieżdżone struktury stają się *Item, i w żądaniu PATCH „pole nie wysłane" i „null wysłany do usunięcia" wreszcie się rozdzielają. Cena to sprawdzanie nil wszędzie — p.Address.Street panikuje, gdy Address jest nil, jeden z najczęstszych runtime crashy w kodzie JSON w Go.
Pusta struktura, której omitempty nie zdejmie, i dziura, którą zapełnia omitzero
Oficjalna definicja omitempty sądzi po wartościach: false, 0, wskaźniki nil, interfejsy nil oraz tablice, slices, map lub stringi zerowej długości. Zauważ, czego nie ma na liście: pustych struktur.
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 nic nie zrobił
Pole-struktura nigdy nie jest pomijane przez omitempty — żyje w pamięci jako kontener o stałym rozmiarze, a istniejący kontener nie jest „pusty". Poprawka to zamiana pola na *Meta; odrzucany jest tylko wskaźnik nil. Od Go 1.24 jest drugi przełącznik, omitzero: sądzi po zerowej wartości Go, wywołując IsZero() bool, gdy typ go definiuje — jedyny sposób pominięcia zerowego time.Time. Z encoding/json/v2 (eksperymentalnym w Go 1.25) semantyka znów się przesuwa: omitempty w v2 sądzi po zakodowanym wyniku JSON (tylko null, "", {}, [] liczą się jako puste), więc count: 0 zostaje w wyjściu; przy migracji starego kodu omitempty na polach bool i numerycznych musi przejść na omitzero, by zachować pierwotny sens.
Każda liczba staje się float64: pułapka dużych całkowitych
Bez jawnego typu dekoder encoding/json traktuje liczby jako float64, a float64 ma tylko 53 bity mantysy. Klasyczny przypadek JavaScriptu — 9007199254740993 stający się 9007199254740992 — istnieje też w Go, dopóki pole docelowe jest float64 lub any.
var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] to float64(9007199254740992), precyzja już stracona
Trzy wyjścia. Zadeklaruj pole struktury jako int64, a dekoder parsuje dokładnie w nie. Kiedy musisz przejść przez any, wywołaj decoder.UseNumber(), żeby liczby lądowały jako stringi json.Number, które świadomie konwertujesz. Nigdy nie używaj zmiennoprzecinkowych do pieniędzy — przechowuj mniejsze jednostki w int64 albo użyj biblioteki decimal. Zawsze, gdy API zwraca ID snowflake albo 64-bitowe numery zamówień, ta sekcja jest obowiązkową kontrolą.
time.Time przyjmuje tylko RFC 3339
Przed "2024-01-15T10:30:00Z" generator zmapuje time.Time; przed "2024-01-15 10:30:00" zostawi string. To nie lenistwo — twarde ograniczenie encoding/json: time.Time implementuje UnmarshalJSON i parsuje ściśle w layoucie RFC 3339 2006-01-02T15:04:05Z07:00. Brakująca T, brakująca strefa czasowa albo Z z następującym offsetem — wszystko pada:
parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""
Kiedy formatu upstream nie da się zmienić, standardową poprawką jest własny typ opakowujący time.Time, którego UnmarshalJSON próbuje kilku layoutów:
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
}
Czterokrokowa checklista po wygenerowaniu
Cztery kroki oddzielają wyjście generatora od kodu produkcyjnego, a ich jednokrotne przejście kosztuje mniej niż późniejsze debugowanie:
- Zamień każdy fallback any: znajdź
any, sprawdź trzy-pięć realnych próbek dla każdego pola w fallbacku, potem wyląduj na konkretnym typie albo wskaźniku; - Ponownie sprawdź szerokości numeryczne: przenieś ID, kwoty i liczniki z float64 na int64 / int32 / decimal; w razie wątpliwości o szerokości pisz int64;
- Oznacz opcjonalność: wskaźniki albo omitempty/omitzero dla pól obiektów w tablicach, ciałach PATCH i polach nullable zewnętrznych API — semantykę nil rozstrzygnij raz, tutaj;
- Skompiluj i przetestuj tam i z powrotem: uruchom
go vet, potem dodaj test tam i z powrotem Marshal→Unmarshal, żeby utrwalić format na drucie — to łapie dryf zachowania przyszłych aktualizacji encoding/json.
Od próbki do kontraktu: granica konwertera
Konwerter odpowiada na pytanie „jak wygląda ta próbka", a nie „jak zawsze będzie wyglądać ten interfejs". Konkurencyjne narzędzia mówią to wprost we własnej dokumentacji: próbka nie może dowieść wariantów produkcyjnych — opcjonalność, formaty dat i wartości wyliczeń wymagają ludzkiej weryfikacji. Buduj więc nawyk: przed wklejeniem zbierz odpowiedzi najbardziej skłonne odsłonić różnice (pusta lista, wszystkie pola, jedna z null); po wygenerowaniu traktuj wyjście jako szkic, a nie dostawę. Jeśli interfejs ma dokument kontraktu, uczynij ograniczenia jawnymi przez JSON Schema i wyrównaj wygenerowany kod według niego — to bije wnioskowanie z próbek o rząd wielkości. Dla poprzecznego spojrzenia na ten sam problem strona Java jest omówiona w naszym poligonowym teście generatora Java, kontrakt frontendu w interfejsach TypeScript; przepaść precyzji numerycznej wraca w każdym języku w innym kostiumie, szczegółowo w pułapce dużych liczb JSON.
Które pola po wygenerowaniu wciąż wymagają ręcznej poprawki?
Co najmniej cztery: fallbacki any, szerokości numeryczne (float64 → int64), zamiana pól opcjonalnych na wskaźniki oraz pytanie, czy pola dat mają być string czy time.Time. Wszystkie cztery to warianty produkcyjne niewidoczne w próbce; generator nie zgaduje, człowiek musi uzupełnić.
Dlaczego moje pole nadal pojawia się w JSON po dodaniu omitempty?
omitempty pomija tylko zerowe wartości: false, 0, "", nil, puste slices. Pusta struktura {} nie jest wartością zerową, więc przeżywa — zamień pole na wskaźnik. Zerowy time.Time potrzebuje omitzero, nie omitempty.
Dlaczego moje duże całkowite ID zmieniło się po deserializacji?
Bez jawnego typu encoding/json parsuje liczby jako float64, który ma 53 bity mantysy; całkowite poza 2^53 tracą precyzję. Otypizuj pole jako int64 albo wywołaj UseNumber(), by zachować liczby jako json.Number.
Kiedy zagnieżdżone pole obiektu powinno być wskaźnikiem?
Dwa przypadki: pole może być nieobecne lub null (nil oddziela „nie wysłano" od „wartości zerowej") i żądanie PATCH musi rozróżniać „nie wysłano" oraz „null wysłany do usunięcia". W zwykłych strukturach odpowiedzi z polami non-nullable typy przez wartość są bezpieczniejsze — płacij koszt sprawdzania nil tylko wtedy, gdy rozróżnianie naprawdę jest ci potrzebne.