JSON Toolkit

JSON ke Go Struct: penjana serahkan kerangka, empat perkara perlukan tangan anda

Inti pati: Tampal contoh respons API ke dalam penukar dan dalam sepuluh saat anda ada struct Go dengan tag — tetapi nombor menjadi float64, medan pilihan tidak pernah menjadi penunjuk dengan sendiri, omitempty tidak menanggalkan struktur kosong dan kebanyakan tarikh kekal sebagai string. Jadual pemetaan lengkap, keseimbangan antara penunjuk dan omitzero, serta senarai semak empat langkah untuk memperhalusi kod yang dijana.

Pertengahan~6 min bacaanDiterbitkan 2026-11-22Dikemas kini 2026-11-22
Menukar contoh JSON kepada kod struct Go menggunakan alat dalam talian

Kesimpulan dahulu: struktur yang penukar hasilkan dalam sepuluh saat berjaya disusun, tetapi belum sedia untuk pengeluaran. Penjana hanya menerangkan contoh tunggal yang anda tampal — nombor menjadi float64, medan pilihan tidak pernah menjadi penunjuk dengan sendiri, omitempty tidak menanggalkan struktur kosong, dan kebanyakan rentetan tarikh kekal sebagai string. Empat jurang ini selepas menampal kekal menjadi tugas anda.

Menukar respons API kepada struktur Go ialah kerja yang semata-mata mekanikal, dan kos kerja mekanikal bersembunyi dalam senyap: nama medan tersalah taip tidak menimbulkan ralat penyusunan, hanya satu medan yang kekal sifar selamanya; satu suis salah dalam pengendalian null — dan "note": null muncul dalam pengeluaran di tempat yang tidak dijangka. Penjanaan struktur menyelesaikan penjajaran nama dan jenis, tetapi dua perkara tidak pernah sejajar dengan sendiri: varian di luar contoh anda dan jurang antara sistem jenis Go dan JSON.

Apa yang penjana sebenarnya baca: jadual pemetaan

Setiap penukar JSON → Go berjalan pada jadual yang sama. Hantarkan respons pesanan tipikal melalui halaman /convert/go laman ini — tampal contoh, hidupkan tag json — dan anda terima bentuk ini:

Nilai JSON Jenis Go dijana Nota
string string Rentetan tarikh biasanya kekal string, lihat time.Time di bawah
integer float64 encoding/json menghurai nombor dalaman sebagai double
perpuluhan float64 Ganti medan kewangan dengan pustaka decimal atau int64 dalam unit lebih kecil
true / false bool Tiada perangkap
null any Satu contoh null tidak membuktikan apa-apa, fallback konservatif
objek struktur ber nama Objek bersarang menjadi strukturnya sendiri
objek kosong {} map[string]any Tiada medan boleh diperhatikan, penjana tidak meneka
array []JenisElemen Jenis elemen disimpulkan daripada contoh pertama
jenis bercampur any Go tiada union, medan pelbagai jenis jatuh ke any
// Contoh input
// {"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"`
}

Tiga pemerhatian. Objek bersarang items menjadi strukturnya sendiri Item yang dirujuk oleh slice. coupon hanya muncul sebagai null: penjana tidak boleh membuktikan apa ia akan menjadi kemudian dan jatuh ke any. Nombor qty mendarat sebagai int atau float64 bergantung pada alat — strategi berbeza, tetapi semua bergantung pada andaian yang sama: contoh adalah keseluruhan kebenaran.

Tag json: nama asal, pilihan dan tiga kesilapan mudah

Tag membawa ketumpatan maklumat tertinggi dalam output penjana dan juga bahagian paling mudah tersilap semasa mengubah suai. Peraturan datang terus daripada dokumentasi encoding/json:

Field int `json:"myName"`            // muncul di bawah kunci myName
Field int `json:"myName,omitempty"`  // medan integer digugurkan apabila kosong
Field int `json:",omitempty"`        // nama medan lalai, hanya pilihan
Field int `json:"-"`                 // sentiasa diabaikan, tidak dikod mahupun nyahkod
Field int64 `json:"id,string"`       // nombor dikodkan dalam rentetan

Tiga kelewatan berbalas diingat. Pertama, koma pendahulu dalam json:",omitempty" — apabila anda hanya mahu melangkau nilai kosong tanpa menamakan semula kunci, kuma wajib ada; tanpanya, medan dianggap sebagai kunci yang secara literal bernama ,omitempty. Kedua, kekalkan kunci JSON asal dalam tag (user_id, html_url) manakala medan Go gunakan konvensyen idiomatik (UserID, HTMLURL): tanpa tag, pemadanan mengikut nama medan secara literal, jadi kunci userId dalam respons tidak pernah terpetakan — dengan senyap. Ketiga, selain json:"-" wujud json:"-," — yang kedua bermaksud kunci itu benar-benar bernama -.

Penunjuk: nil satu-satunya cara membezakan "tiada" daripada "sifar"

Sistem nilai sifar Go menghalang int dan string menyatakan "medan tidak hadir" — 0 dan "" mungkin data sebenar atau sekadar tidak dihurai. Kunci JSON yang sama mempunyai tiga keadaan: hadir dengan nilai, hadir sebagai null dan tidak hadir. Jenis mengikut nilai hanya meliputi yang pertama.

type Config struct {
  Note    string  `json:"note,omitempty"`   // digugurkan hanya apabila tepat ""
  Alias   *string `json:"alias,omitempty"`  // digugurkan apabila nil
  Details *Meta   `json:"details,omitempty"`
}

Nilai sifar medan penunjuk ialah nil. json.Unmarshal meninggalkannya nil apabila kunci tiada atau null, dan omitempty melangkaunya hanya dalam kes itu. Itulah sebab kebanyakan penukar menawarkan suis "guna penunjuk untuk objek bersarang": dihidupkan — struktur bersarang menjadi *Item, dan dalam permintaan PATCH "medan tidak dihantar" dan "null dihantar untuk padam" akhirnya terpisah. Harganya ialah semakan nil di mana-mana — p.Address.Street panic apabila Address nil, salah satu crash runtime paling biasa dalam kod JSON di Go.

Struktur kosong yang omitempty tidak mampu tanggalkan, dan lubang yang diisi omitzero

Definisi rasmi omitempty menilai nilai: false, 0, penunjuk nil, interface nil dan array, slices, map atau rentetan panjang sifar. Perhatikan apa yang tiada dalam senarai: struktur kosong.

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 tidak buat apa-apa

Medan struktur tidak pernah digugurkan oleh omitempty — ia hidup dalam memori sebagai bekas saiz tetap, dan bekas yang wujud bukanlah "kosong". Pembetulan ialah menukar medan kepada *Meta; hanya penunjuk nil dibuang. Sejak Go 1.24 ada suis kedua, omitzero: dinilai mengikut nilai sifar Go, memanggil IsZero() bool apabila jenisnya mentakrifkannya — satu-satunya cara menggugurkan time.Time sifar. Dengan encoding/json/v2 (eksperimen dalam Go 1.25) semantik bergeser semula: omitempty v2 menilai hasil JSON yang dikodkan (hanya null, "", {}, [] dikira kosong), jadi count: 0 kekal dalam output; ketika memindahkan kod lama, omitempty pada medan bool dan numerik perlu menjadi omitzero untuk mengekalkan maksud asal.

Setiap nombor menjadi float64: perangkap integer besar

Tanpa jenis jelas, penyahkod encoding/json menganggap nombor sebagai float64, dan float64 hanya ada 53 bit mantissa. Kes klasik JavaScript — 9007199254740993 menjadi 9007199254740992 — wujud juga dalam Go, selagi medan sasaran ialah float64 atau any.

var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] ialah float64(9007199254740992), ketepatan sudah hilang

Tiga jalan keluar. Isytihar medan struktur sebagai int64 dan penyahkod menghurai tepat ke dalamnya. Apabila perlu melalui any, panggil decoder.UseNumber() supaya nombor mendarat sebagai rentetan json.Number yang anda tukar secara sedar. Jangan sesekali gunakan titik terapung untuk wang — simpan unit lebih kecil dalam int64 atau gunakan pustaka decimal. Setiap kali API memulangkan ID snowflake atau nombor pesanan 64 bit, bahagian ini ialah semakan wajib.

time.Time hanya terima RFC 3339

Depan "2024-01-15T10:30:00Z" penjana memetakan time.Time; depan "2024-01-15 10:30:00" meninggalkan string. Bukan malas — ia kekangan keras encoding/json: time.Time melaksanakan UnmarshalJSON dan menghurai secara ketat dalam layout RFC 3339 2006-01-02T15:04:05Z07:00. T hilang, zon waktu hilang atau Z diikuti offset — semuanya gagal:

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

Apabila format upstream tidak boleh diubah, pembetulan standard ialah jenis tersuai yang membungkus time.Time dengan UnmarshalJSON yang mencuba beberapa 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
}

Senarai semak empat langkah selepas menjana

Empat langkah memisahkan output penjana daripada kod pengeluaran, dan melaluinya sekali lebih murah daripada menyahpepijat kemudian:

  1. Gantikan setiap fallback any: cari any, semak tiga hingga lima contoh sebenar bagi setiap medan fallback kemudian mendaratkan pada jenis konkrit atau penunjuk;
  2. Semak semula lebar berangka: alihkan ID, amaun dan pengira dari float64 ke int64 / int32 / decimal; ragu-ragu tentang lebar, tulis int64;
  3. Tandakan kepililihan: penunjuk atau omitempty/omitzero untuk medan objek dalam array, badan PATCH dan medan nullable API pihak ketiga — putuskan semantik nil sekali, di sini;
  4. Susun dan uji pergi-balik: jalankan go vet, kemudian tambah ujian pergi-balik Marshal→Unmarshal untuk mengunci format atas wayar — ia menangkap hanyut tingkah laku kemas kini encoding/json pada masa depan.

Dari contoh ke kontrak: sempadan penukar

Penukar menjawab "bagaimana rupa contoh ini", bukan "bagaimana antara muka ini sentiasa kelihatan". Alat bersaing mengatakannya jujur dalam dokumentasi mereka sendiri: satu contoh tidak dapat membuktikan varian pengeluaran — kepililihan, format tarikh dan nilai enumerasi memerlukan semakan manusia. Jadi bina tabiat: sebelum menampal, kumpulkan respons paling mudah mendedahkan perbezaan (senarai kosong, semua medan, satu dengan null); selepas menjana, anggap output sebagai draf, bukan serahan. Jika antara muka ada dokumen kontrak, jadikan kekangan jelas melalui JSON Schema dan selaraskan kod yang dijana kepadanya — menewaskan inferens daripada contoh sekali ganda. Untuk panduan melintang masalah sama, sisi Java diliputi dalam ujian lapangan penjana Java kami, kontrak frontend dalam interface TypeScript; jurang ketepatan berangka kembali dalam setiap bahasa dengan kostum lain, diperincikan dalam perangkap nombor besar JSON.

Medan manakah yang masih perlukan semakan manual selepas dijana?

Sekurang-kurangnya empat: fallback any, lebar berangka (float64 → int64), menjadikan medan pilihan penunjuk dan sama ada medan tarikh patut string atau time.Time. Keempat-empatnya ialah varian pengeluaran yang tidak kelihatan dalam contoh; penjana tidak meneka, manusia perlu melengkapkan.

Mengapa medan saya masih muncul dalam JSON selepas menambah omitempty?

omitempty hanya melangkau nilai sifar: false, 0, "", nil, slices kosong. Struktur kosong {} bukan nilai sifar, jadi ia kekal — tukar medan kepada penunjuk. time.Time sifar memerlukan omitzero, bukan omitempty.

Mengapa ID integer besar saya berubah selepas penyahserialan?

Tanpa jenis jelas, encoding/json menghurai nombor sebagai float64, yang membawa 53 bit mantissa; integer melebihi 2^53 hilang ketepatan. Taipkan medan sebagai int64, atau panggil UseNumber() untuk mengekalkan nombor sebagai json.Number.

Bilakah medan objek bersarang patut menjadi penunjuk?

Dua kes: medan mungkin tiada atau null (nil memisahkan "tidak dihantar" daripada "nilai sifar"), dan permintaan PATCH perlu membezakan "tidak dihantar" dengan "null dihantar untuk padam". Dalam struktur respons biasa dengan medan non-nullable, jenis mengikut nilai lebih selamat — bayar kos semakan nil hanya apabila pembezaan benar-benar diperlukan.

Rujukan

Artikel berkaitan

JSON kepada Kelas Java: penjana hanya beri rangka, untuk produksi perlu lima perkara lagi

Tinjauan praktikal tentang apa yang penjana JSON-to-Java sebenarnya keluarkan — nombor jadi Double, objek bersarang jadi kelas dalaman statik, dan tiada anotasi Jackson langsung dihasilkan. Ketepatan wang, penamaan semula medan, pemadaman jenis, medan tidak dikenali dan tarikh ialah lima perkara yang anda sendiri perlu tambah, setiap satu dengan kod sedia salin.

Pertengahan~10 min bacaanDikemas kini 2026-11-04

Mengapa integer besar kehilangan ketepatan

Integer melebihi 2^53-1 kehilangan ketepatan dalam JSON.parse. ID snowflake, nombor pesanan dan bigint pangkalan data semuanya terjejas, jadi biarkan mereka sebagai rentetan dari hujung ke hujung.

Pertengahan~4 min bacaanDikemas kini 2026-11-04