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.

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": nullmuncul 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:
- Gantikan setiap fallback any: cari
any, semak tiga hingga lima contoh sebenar bagi setiap medan fallback kemudian mendaratkan pada jenis konkrit atau penunjuk; - Semak semula lebar berangka: alihkan ID, amaun dan pengira dari float64 ke int64 / int32 / decimal; ragu-ragu tentang lebar, tulis int64;
- 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;
- 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.