JSON เป็น Go Struct: เครื่องมือสร้างส่งมอบโครงกระดูก สี่เรื่องต้องลงมือเอง
สรุปสำคัญ: วางตัวอย่างการตอบกลับ API ลงในตัวแปลง และในสิบวินาทีคุณมี struct Go พร้อม tag — แต่ตัวเลขกลายเป็น float64, ฟิลด์ทางเลือกไม่กลายเป็น pointer เอง, omitempty ตัด struct ว่างไม่ได้ และวันที่ส่วนใหญ่ยังคงเป็น string ตารางการจับคู่ฉบับเต็ม สมดุลระหว่าง pointer กับ omitzero และเช็กลิสต์สี่ขั้นตอนสำหรับเก็บงานโค้ดที่สร้างแล้วให้เรียบร้อย

สรุปก่อน: struct ที่ตัวแปลงผลิตได้ในสิบวินาทีคอมไพล์ผ่าน แต่ยังไม่พร้อมขึ้นโปรดักชัน เครื่องมือสร้างอธิบายเพียงตัวอย่างเดียวที่คุณวางลงไป — ตัวเลขกลายเป็น float64, ฟิลด์ทางเลือกไม่กลายเป็น pointer ด้วยตัวเอง, omitempty ตัด struct ว่างออกไม่ได้ และสตริงวันที่ส่วนใหญ่ยังคงเป็น string ช่องว่างสี่จุดนี้หลังจากวางแล้วยังเป็นงานของคุณ
เปลี่ยนการตอบกลับ API เป็น struct Go เป็นงานกลไกล้วน ๆ และต้นทุนของงานกลไกซ่อนอยู่ในความเงียบ: ชื่อฟิลด์พิมพ์ผิดไม่ทำให้คอมไพล์ล้ม มีแค่ฟิลด์ที่เป็นศูนย์ตลอดไป; สวิตช์จัดการ null ผิดทาง — แล้ว
"note": nullก็โผล่บนโปรดักชันในจุดที่ไม่มีใครคาดหมาย การสร้าง struct แก้ปัญหาการจัดแนวชื่อและชนิด แต่มีสองเรื่องที่ไม่เคยจัดแนวกันเอง: รูปแบบที่อยู่นอกตัวอย่างของคุณ และหุบเขาระหว่างระบบชนิดข้อมูลของ Go กับ JSON
เครื่องมือสร้างอ่านอะไรกันแท้: ตารางจับคู่
ตัวแปลง JSON → Go ทุกตัวทำงานบนตารางเดียวกัน ส่งการตอบกลับออเดอร์ทั่วไปผ่านหน้า /convert/go ของไซต์นี้ — วางตัวอย่าง เปิด json tag — แล้วคุณจะได้รูปแบบนี้:
| ค่า JSON | ชนิด Go ที่สร้าง | หมายเหตุ |
|---|---|---|
| string | string |
สตริงวันที่มักยังคงเป็น string ดู time.Time ด้านล่าง |
| จำนวนเต็ม | float64 |
encoding/json แยกวิเคราะห์ตัวเลขภายในเป็น double |
| ทศนิยม | float64 |
เปลี่ยนฟิลด์เงินเป็นไลบรารี decimal หรือ int64 ในหน่วยย่อย |
| true / false | bool |
ไม่มีกับดัก |
| null | any |
ตัวอย่าง null จุดเดียวไม่พิสูจน์อะไร fallback แบบอนุรักษ์นิยม |
| object | struct ที่มีชื่อ | object ที่ซ้อนอยู่กลายเป็น struct ของตัวเอง |
object ว่าง {} |
map[string]any |
ไม่มีฟิลด์ให้สังเกต เครื่องมือเดาไม่ได้ |
| array | []ชนิดสมาชิก |
ชนิดสมาชิกอนุมานจากตัวอย่างแรก |
| ชนิดผสม | any |
Go ไม่มี union ฟิลด์หลายชนิดตกลงไปที่ any |
// ตัวอย่างขาเข้า
// {"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"`
}
สามข้อสังเกต object ที่ซ้อนอยู่ items กลายเป็น struct ของตัวเองชื่อ Item ที่ slice อ้างถึง coupon ปรากฏเป็น null เท่านั้น: เครื่องมือพิสูจน์ไม่ได้ว่าหลังจากนี้มันจะเป็นอะไร จึงตกไปที่ any ตัวเลข qty ลงจอดเป็น int หรือ float64 แล้วแต่เครื่องมือ — กลยุทธ์ต่างกัน แต่ทุกกลยุทธ์ยืนบนสมมติฐานเดียวกัน: ตัวอย่างคือความจริงทั้งหมด
Json tag: ชื่อเดิม ตัวเลือก และข้อผิดพลาดง่าย ๆ สามข้อ
Tag แบกรับความหนาแน่นของข้อมูลสูงสุดในผลลัพธ์ของเครื่องมือสร้าง และยังเป็นจุดที่พลาดง่ายที่สุดเวลาแก้ไข กฎต่าง ๆ มาจากเอกสาร encoding/json โดยตรง:
Field int `json:"myName"` // ปรากฏภายใต้คีย์ myName
Field int `json:"myName,omitempty"` // ฟิลด์จำนวนเต็มถูกตัดเมื่อว่าง
Field int `json:",omitempty"` // ชื่อฟิลด์ค่าเริ่มต้น มีแค่ตัวเลือก
Field int `json:"-"` // ถูกละเว้นเสมอ ไม่เข้ารหัสและไม่ถอดรหัส
Field int64 `json:"id,string"` // ตัวเลขถูกเข้ารหัสอยู่ในสตริง
สามความประมาทที่ควรจำ หนึ่ง คอมมานำหน้าใน json:",omitempty" — เมื่อคุณแค่อยากข้ามค่าว่างโดยไม่เปลี่ยนชื่อคีย์ คอมมาจำเป็น; ขาดมัน ฟิลด์จะถูกถือเป็นคีย์ที่ชื่อตรงตัวว่า ,omitempty สอง เก็บคีย์ JSON เดิมไว้ใน tag (user_id, html_url) ขณะที่ฟิลด์ Go ใช้แบบแผน idiomatic (UserID, HTMLURL): ไม่มี tag การจับคู่ใช้ชื่อฟิลด์ตรงตัว คีย์ userId ในการตอบกลับจึงไม่มีวันถูก map — อย่างเงียบ ๆ สาม นอกจาก json:"-" ยังมี json:"-," — อันหลังหมายความว่าคีย์ชื่อจริงคือ -
Pointer: nil เป็นวิธีเดียวที่แยก "ไม่มี" ออกจาก "ศูนย์"
ระบบค่าศูนย์ของ Go ทำให้ int และ string แสดง "ฟิลด์ไม่ปรากฏ" ไม่ได้ — 0 และ "" อาจเป็นข้อมูลจริงหรือแค่ยังไม่ถูกแยกวิเคราะห์ คีย์ JSON เดียวกันมีสามสถานะ: ปรากฏพร้อมค่า ปรากฏเป็น null และไม่ปรากฏ ชนิดแบบ by-value ครอบคลุมแค่สถานะแรก
type Config struct {
Note string `json:"note,omitempty"` // ถูกตัดเฉพาะเมื่อเป็น "" เป๊ะ ๆ
Alias *string `json:"alias,omitempty"` // ถูกตัดเมื่อ nil
Details *Meta `json:"details,omitempty"`
}
ค่าศูนย์ของฟิลด์ pointer คือ nil json.Unmarshal ปล่อยให้เป็น nil เมื่อคีย์หายไปหรือเป็น null และ omitempty ข้ามมันเฉพาะกรณีนั้น นี่คือเหตุผลที่ตัวแปลงส่วนใหญ่มีสวิตช์ "ใช้ pointer กับ object ที่ซ้อนอยู่": เปิดแล้ว — struct ที่ซ้อนกลายเป็น *Item และในคำขอ PATCH "ฟิลด์ไม่ได้ส่ง" กับ "ส่ง null เพื่อลบ" ก็แยกออกจากกันในที่สุด ราคาที่ต้องจ่ายคือการเช็ก nil ทั่วทุกที่ — p.Address.Street panic เมื่อ Address เป็น nil หนึ่งใน crash runtime ที่พบบ่อยที่สุดของโค้ด JSON บน Go
Struct ว่างที่ omitempty ตัดไม่ได้ และช่องว่างที่ omitzero เติม
นิยามอย่างเป็นทางการของ omitempty ตัดสินจากค่า: false, 0, pointer ที่เป็น nil, interface ที่เป็น nil และ array, slices, maps หรือ string ที่ยาวเป็นศูนย์ สังเกตสิ่งที่ไม่อยู่ในรายการ: struct ว่าง
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 ไม่ทำอะไรเลย
ฟิลด์ชนิด struct ไม่เคยถูก omitempty ตัดออก — มันอยู่ในหน่วยความจำเป็นภาชนะขนาดคงที่ และภาชนะที่มีอยู่ไม่ใช่ "ว่าง" วิธีแก้คือเปลี่ยนฟิลด์เป็น *Meta; มีเพียง pointer ที่เป็น nil เท่านั้นที่ถูกทิ้ง ตั้งแต่ Go 1.24 มีสวิตช์ที่สองคือ omitzero: ตัดสินจากค่าศูนย์ของ Go โดยเรียก IsZero() bool เมื่อชนิดข้อมูลนิยามมันไว้ — วิธีเดียวที่ตัด time.Time ที่เป็นศูนย์ออกได้ ส่วน encoding/json/v2 (เวอร์ชันทดลองใน Go 1.25) ความหมายเลื่อนอีกครั้ง: omitempty ของ v2 ตัดสินจากผลลัพธ์ JSON ที่เข้ารหัสแล้ว (นับเป็นว่างเฉพาะ null, "", {}, []) ดังนั้น count: 0 ยังอยู่ในผลลัพธ์; ตอนย้ายโค้ดเก่า omitempty บนฟิลด์ bool และตัวเลขต้องเปลี่ยนเป็น omitzero เพื่อรักษาความหมายเดิม
ทุกตัวเลขกลายเป็น float64: กับดักจำนวนเต็มใหญ่
เมื่อไม่ระบุชนิด ตัวถอดรหัสของ encoding/json ถือว่าตัวเลขเป็น float64 และ float64 มี mantissa เพียง 53 บิต กรณีคลาสสิกของ JavaScript — 9007199254740993 กลายเป็น 9007199254740992 — มีอยู่ใน Go เช่นกัน ตราบใดที่ฟิลด์ปลายทางเป็น float64 หรือ any
var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] คือ float64(9007199254740992) ความละเอียดหายไปแล้ว
สามทางออก ประกาศฟิลด์ struct เป็น int64 แล้วตัวถอดรหัสจะแยกวิเคราะห์เข้าฟิลด์นั้นอย่างเป๊ะ เมื่อต้องผ่าน any ให้เรียก decoder.UseNumber() เพื่อให้ตัวเลขลงจอดเป็นสตริง json.Number ที่คุณแปลงอย่างตั้งใจ อย่าใช้จุดทศนิยมกับเงินเด็ดขาด — เก็บหน่วยย่อยใน int64 หรือใช้ไลบรารี decimal ทุกครั้งที่ API คืน ID แบบ snowflake หรือเลขออเดอร์ 64 บิต หัวข้อนี้คือการเช็กบังคับ
time.Time รับเฉพาะ RFC 3339
เจอ "2024-01-15T10:30:00Z" เครื่องมือสร้างจะ map เป็น time.Time; เจอ "2024-01-15 10:30:00" ก็ปล่อยเป็น string ไม่ใช่ความขี้เกียจ — เป็นข้อจำกัดแบบแข็งของ encoding/json: time.Time เรียกใช้ UnmarshalJSON และแยกวิเคราะห์อย่างเคร่งครัดตาม layout RFC 3339 2006-01-02T15:04:05Z07:00 ขาด T ขาดเขตเวลา หรือ Z ตามด้วย offset ทั้งหมดล้มเหลว:
parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""
เมื่อรูปแบบจากต้นทางเปลี่ยนไม่ได้ วิธีแก้มาตรฐานคือชนิดข้อมูลที่เขียนเองครอบ time.Time โดย UnmarshalJSON ของมันลองหลาย 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
}
เปรียบเทียบกับเครื่องมือยอดนิยม: ต่างกันที่นโยบาย ไม่ใช่ความสามารถ
เครื่องมือสร้าง struct Go ยอดนิยมหลายตัวบนเว็บทำงานบนกฎเดียวกัน แต่ต่างกันที่นโยบายเริ่มต้น สามประเด็นที่ควรเทียบก่อนเลือกใช้ หนึ่ง ชนิดของจำนวนเต็ม — บางเครื่องมือเลือก int เสมอ บางเครื่องมือเลือก float64 ตามพฤติกรรมจริงของ encoding/json สอง การจัดการ null — บางเครื่องมือมีตัวเลือก "ทำเป็น pointer เมื่อพบ null" แยกออกมาชัดเจน บางเครื่องมือซ่อนไว้ในโหมด "จับคู่แบบระวัง" สาม ชื่อโครงสร้างราก — บางเครื่องมือให้ตั้งชื่อเองผ่านตัวเลือก rootName บางเครื่องมือตั้งเป็น Root ตายตัวแล้วให้คุณเปลี่ยนทีหลัง ทั้งหมดนี้เป็นการตัดสินใจเชิงนโยบาย ไม่ใช่ความสามารถของอัลกอริทึม เพราะกฎการแปลงมาตรฐานมีเพียงหนึ่งชุดเดียว
ทางเลือกที่แตกต่างอย่างสิ้นเชิงคือการเขียน struct เองจากเอกสาร API ทั้งหมดโดยไม่ใช้ตัวอย่างเลย วิธีนี้ได้สัญญาที่สมบูรณ์กว่า แต่ช้ากว่าหลายเท่าและพลาดง่ายเวลาฟิลด์มีเป็นสิบ ๆ ระดับ เครื่องมือจึงยังคงเป็นจุดเริ่มที่ดีที่สุด ขอแค่จำว่าผลลัพธ์คือ "ร่างแรกจากตัวอย่าง" ไม่ใช่ "คำตอบสุดท้ายจากข้อกำหนด" ยิ่ง API มีเวอร์ชันมาก ยิ่งควรมีไฟล์ทดสอบโครงสร้างที่กักเก็บรูปแบบไว้เป็นคู่เทียบตลอดอายุโปรเจกต์
เช็กลิสต์สี่ขั้นหลังจากสร้างเสร็จ
สี่ขั้นตอนแยกผลลัพธ์ของเครื่องมือสร้างออกจากโค้ดโปรดักชัน และการเดินผ่านครั้งเดียวถูกกว่าการ debug ภายหลัง:
- เปลี่ยน fallback any ทุกจุด: ค้นหา
anyดูตัวอย่างจริงสามถึงห้าชุดต่อฟิลด์ที่ตกไปอยู่ใน fallback แล้วลงจอดเป็นชนิดเฉพาะเจาะจงหรือ pointer; - ตรวจความกว้างของตัวเลขซ้ำ: ย้าย ID จำนวนเงินและตัวนับจาก float64 ไป int64 / int32 / decimal; ถ้าไม่แน่ใจความกว้าง เขียน int64;
- ทำเครื่องหมายความเป็นทางเลือก: pointer หรือ omitempty/omitzero สำหรับฟิลด์ของ object ใน array, ร่างกาย PATCH และฟิลด์ nullable ของ API บุคคลที่สาม — ตัดสินความหมายของ nil ครั้งเดียว ตรงนี้;
- คอมไพล์และทดสอบไปกลับ: รัน
go vetจากนั้นเพิ่ม test ไปกลับ Marshal→Unmarshal เพื่อล็อกรูปแบบบนสาย — มันจับการเลื่อนพฤติกรรมของการอัปเดต encoding/json ในอนาคต
จากตัวอย่างสู่สัญญา: เส้นแบ่งของตัวแปลง
ตัวแปลงตอบคำถามว่า "ตัวอย่างนี้หน้าตาเป็นอย่างไร" ไม่ใช่ "อินเทอร์เฟซนี้จะหน้าตาเป็นอย่างไรตลอดไป" เครื่องมือคู่แข่งพูดตรง ๆ ไว้ในเอกสารของตัวเอง: ตัวอย่างเดียวพิสูจน์รูปแบบโปรดักชันไม่ได้ — ความเป็นทางเลือก รูปแบบวันที่ และค่า enum ต้องการมนุษย์ตรวจ จึงควรสร้างนิสัย: ก่อนวาง รวบรวมการตอบกลับที่มีแนวโน้มเผยความต่างมากที่สุด (ลิสต์ว่าง ครบทุกฟิลด์ หนึ่งชุดเต็มไปด้วย null); หลังสร้าง ให้ถือผลลัพธ์เป็นร่าง ไม่ใช่ของส่งมอบ ถ้าอินเทอร์เฟซมีเอกสารสัญญา ให้ทำข้อจำกัดให้ชัดด้วย JSON Schema แล้วจัดแนวโค้ดที่สร้างกับมัน — เอาชนะการอนุมานจากตัวอย่างได้ทั้งอันดับ สำหรับมุมมองข้ามภาษาของปัญหาเดียวกัน ฝั่ง Java อยู่ในบททดสอบภาคสนามของเครื่องมือสร้าง Java สัญญา frontend อยู่ใน interface TypeScript; หุบเขาความละเอียดของตัวเลขกลับมาในทุกภาษาด้วยเครื่องแต่งกายต่างกัน อ่านรายละเอียดในกับดักตัวเลขใหญ่ของ JSON
ฟิลด์ใดบ้างที่หลังสร้างแล้วยังต้องแก้ด้วยมือ?
อย่างน้อยสี่: fallback any, ความกว้างของตัวเลข (float64 → int64), เปลี่ยนฟิลด์ทางเลือกเป็น pointer และคำถามว่าฟิลด์วันที่ควรเป็น string หรือ time.Time ทั้งสี่คือรูปแบบโปรดักชันที่มองไม่เห็นในตัวอย่าง; เครื่องมือเดาไม่ได้ มนุษย์ต้องเติม ในทางปฏิบัติการรวบรวมรายการฟิลด์เหล่านี้ทำได้เร็วด้วยการค้นคำว่า any ในไฟล์ที่สร้างแล้วไล่เช็กทีละจุดจบภายในสิบนาทีสำหรับ API ขนาดกลาง และควรจดลงในคอมเมนต์เหนือ struct ทันทีเพื่อให้สมาชิกทีมคนต่อไปเห็นเหตุผลเดียวกันโดยไม่ต้องเปิดการสนทนาใหม่
ทำไมฟิลด์ของฉันยังโผล่ใน JSON หลังเพิ่ม omitempty?
omitempty ข้ามเฉพาะค่าศูนย์: false, 0, "", nil, slice ว่าง struct ว่าง {} ไม่ใช่ค่าศูนย์ จึงรอด — เปลี่ยนฟิลด์เป็น pointer time.Time ที่เป็นศูนย์ต้องใช้ omitzero ไม่ใช่ omitempty
ทำไม ID จำนวนเต็มใหญ่ของฉันเปลี่ยนไปหลังถอดรหัส?
เมื่อไม่ระบุชนิด encoding/json แยกวิเคราะห์ตัวเลขเป็น float64 ที่มี 53 บิต mantissa; จำนวนเต็มเกิน 2^53 เสียความละเอียด กำหนดชนิดฟิลด์เป็น int64 หรือเรียก UseNumber() เพื่อเก็บตัวเลขเป็น json.Number
เมื่อไรฟิลด์ object ที่ซ้อนอยู่ควรเป็น pointer?
สองกรณี: ฟิลด์อาจไม่ปรากฏหรือเป็น null (nil แยก "ไม่ได้ส่ง" ออกจาก "ค่าศูนย์") และคำขอ PATCH ต้องแยก "ไม่ได้ส่ง" กับ "ส่ง null เพื่อลบ" ใน struct การตอบกลับทั่วไปที่ฟิลด์ไม่ nullable ชนิดแบบ by-value ปลอดภัยกว่า — จ่ายค่าเช็ก nil เฉพาะเมื่อจำเป็นต้องแยกแยะจริง ๆ
ควรเก็บตัวอย่าง JSON ไว้ใช้ยืนยันพฤติกรรมอย่างไร?
เก็บไฟล์นามสกุล .json ของการตอบกลับจริงที่สะท้อนขอบเขตไว้ในโฟลเดอร์ testdata ของโปรเจกต์ แล้วเขียนทดสอบที่อ่านทุกไฟล์ ทำ Unmarshal เข้า struct จากนั้น Marshal กลับออกมาเทียบกับต้นฉบับ เมื่อ encoding/json อัปเดตพฤติกรรมทดสอบชุดนี้จะเตือนการเปลี่ยนแปลงก่อนที่มันจะไปถึงผู้ใช้ในโปรดักชัน
สรุปเป็นประโยคเดียวคือเครื่องมือแปลงซื้อเวลาให้คุณสิบวินาที แต่ความถูกต้องระยะยาวของโครงสร้างข้อมูลยังเป็นการลงทุนที่ต้องจ่ายด้วยการอ่านข้อกำหนด การรวบรวมตัวอย่างที่หลากหลาย และการเขียนทดสอบที่จับการเปลี่ยนแปลงของเขตข้อมูลอย่างเป็นระบบในทุกรอบปล่อยเวอร์ชัน