JSON Toolkit

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.

Średniozaawansowany~6 min czytaniaOpublikowano 2026-11-22Zaktualizowano 2026-11-22
Konwersja próbki JSON na kod struktury Go za pomocą narzędzia online

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": null pojawia 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:

  1. 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;
  2. 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;
  3. 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;
  4. 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.

Źródła

Powiązane artykuły

JSON na klasę Java: generator da szkielet, do produkcji brakuje jeszcze pięciu rzeczy

Praktyczne spojrzenie na to, co generator JSON-to-Java naprawdę emituje — liczby stają się Double, zagnieżdżone obiekty statycznymi klasami wewnętrznymi, a nie powstaje ani jedna adnotacja Jacksona. Precyzja pieniędzy, zmiana nazw pól, wymazywanie typów, nieznane pola i daty to pięć rzeczy, które musisz uzupełnić sam, każda z kodem gotowym do wklejenia.

Średniozaawansowany~10 min czytaniaZaktualizowano 2026-11-04

Dlaczego duże liczby całkowite tracą precyzję

Liczby całkowite powyżej 2^53-1 tracą precyzję w JSON.parse. Identyfikatory snowflake, numery zamówień i biginty bazodanowe wszystkie na to trafiają, więc trzymaj je jako łańcuchy od początku do końca.

Średniozaawansowany~4 min czytaniaZaktualizowano 2026-11-04