JSON Toolkit

JSON sang Go Struct: trình tạo giao bộ khung, bốn việc cần đến tay bạn

Kết luận: Dán một phản hồi API mẫu vào bộ chuyển đổi và trong mười giây bạn có struct Go kèm tag — nhưng số trở thành float64, trường tùy chọn tự thân không bao giờ thành con trỏ, omitempty không gỡ được struct rỗng và phần lớn ngày tháng vẫn là string. Bảng ánh xạ đầy đủ, sự cân bằng giữa con trỏ và omitzero, và danh sách kiểm tra bốn bước để hoàn thiện mã đã tạo.

Trung cấpĐọc khoảng 6 phútXuất bản 2026-11-22Cập nhật 2026-11-22
Chuyển đổi mẫu JSON thành mã struct Go bằng công cụ trực tuyến

Kết luận trước: những struct mà bộ chuyển đổi tạo ra trong mười giây sẽ biên dịch được, nhưng chưa sẵn sàng cho sản xuất. Trình tạo chỉ mô tả đúng mẫu duy nhất bạn đã dán — số trở thành float64, trường tùy chọn tự thân không bao giờ thành con trỏ, omitempty không gỡ được struct rỗng, và phần lớn chuỗi ngày tháng vẫn là string. Bốn khoảng trống này sau khi dán vẫn là việc của bạn.

Biến một phản hồi API thành struct Go là việc thuần cơ khí, và cái giá của việc cơ khí nằm trong im lặng: tên trường gõ nhầm không gây lỗi biên dịch, chỉ có một trường mãi mãi bằng không; một công tắc sai trong xử lý null — và "note": null xuất hiện trên sản xuất ở nơi không ai chờ nó. Việc tạo struct giải quyết việc căn chỉnh tên và kiểu, nhưng hai thứ không bao giờ tự căn chỉnh được: các biến thể ngoài mẫu của bạn và hố sâu giữa hệ kiểu của Go và JSON.

Trình tạo thực sự đọc gì: bảng ánh xạ

Mọi bộ chuyển đổi JSON → Go đều chạy trên cùng một bảng. Đưa một phản hồi đơn hàng điển hình qua trang /convert/go của site này — dán mẫu, bật json tag — và bạn nhận được dạng này:

Giá trị JSON Kiểu Go tạo ra Ghi chú
string string Chuỗi ngày tháng thường vẫn là string, xem time.Time bên dưới
số nguyên float64 encoding/json phân tích số bên trong dưới dạng double
thập phân float64 Thay trường tiền tệ bằng thư viện decimal hoặc int64 ở đơn vị nhỏ hơn
true / false bool Không có bẫy
null any Một mẫu null không chứng minh được gì, fallback bảo thủ
đối tượng struct có tên Đối tượng lồng nhau trở thành struct riêng
đối tượng rỗng {} map[string]any Không có trường quan sát được, trình tạo không đoán
mảng []KiểuPhầnTử Kiểu phần tử suy ra từ mẫu đầu tiên
kiểu hỗn hợp any Go không có union, trường nhiều kiểu rơi vào any
// Mẫu đầu vào
// {"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"`
}

Ba nhận xét. Đối tượng lồng nhau items trở thành struct riêng Item được slice tham chiếu. coupon chỉ xuất hiện dưới dạng null: trình tạo không thể chứng minh sau này nó là gì và rơi vào any. Số qty hạ cánh thành int hoặc float64 tùy công cụ — các chiến lược khác nhau, nhưng đều dựa trên cùng một giả định: mẫu là toàn bộ chân lý.

Json tag: tên gốc, các tùy chọn và ba lỗi dễ mắc

Tag mang mật độ thông tin cao nhất trong đầu ra của trình tạo và cũng là phần dễ sai nhất khi chỉnh sửa. Quy tắc đến thẳng từ tài liệu encoding/json:

Field int `json:"myName"`            // xuất hiện dưới khóa myName
Field int `json:"myName,omitempty"`  // trường nguyên bị bỏ khi rỗng
Field int `json:",omitempty"`        // tên trường mặc định, chỉ có tùy chọn
Field int `json:"-"`                 // luôn bị bỏ qua, không mã hóa cũng không giải mã
Field int64 `json:"id,string"`       // số được mã hóa bên trong chuỗi

Ba chỗ cẩu thả đáng nhớ. Thứ nhất, dấu phẩy đứng đầu trong json:",omitempty" — khi bạn chỉ muốn bỏ qua giá trị rỗng mà không đổi tên khóa, dấu phẩy bắt buộc; thiếu nó, trường bị coi là khóa tên đúng chữ ,omitempty. Thứ hai, giữ khóa JSON gốc trong tag (user_id, html_url) trong khi trường Go dùng quy ước idiomatic (UserID, HTMLURL): thiếu tag, việc khớp đi theo đúng tên trường, nên khóa userId trong phản hồi không bao giờ map được — một cách âm thầm. Thứ ba, ngoài json:"-" còn có json:"-," — cái sau nghĩa là khóa thực sự tên là -.

Con trỏ: nil là cách duy nhất phân biệt "vắng mặt" với "không"

Hệ giá trị không của Go không cho phép int và string diễn đạt "trường không có mặt" — 0 và "" có thể là dữ liệu thật hoặc đơn giản chưa được phân tích. Cùng một khóa JSON có ba trạng thái: hiện diện kèm giá trị, hiện diện dạng null và vắng mặt. Kiểu theo giá trị chỉ phủ trạng thái đầu.

type Config struct {
  Note    string  `json:"note,omitempty"`   // bị bỏ chỉ khi đúng ""
  Alias   *string `json:"alias,omitempty"`  // bị bỏ khi nil
  Details *Meta   `json:"details,omitempty"`
}

Giá trị không của trường con trỏ là nil. json.Unmarshal để nó nil khi khóa vắng mặt hoặc là null, và omitempty bỏ qua nó chỉ trong trường hợp đó. Đó là lý do phần lớn bộ chuyển đổi có công tắc "dùng con trỏ cho đối tượng lồng nhau": bật lên — struct lồng nhau thành *Item, và trong yêu cầu PATCH "trường không gửi" và "null gửi để xóa" cuối cùng cũng tách rời. Cái giá là kiểm tra nil khắp nơi — p.Address.Street panic khi Address là nil, một trong những crash runtime phổ biến nhất của mã JSON trên Go.

Struct rỗng mà omitempty không gỡ được, và lỗ hổng mà omitzero lấp

Định nghĩa chính thức của omitempty xét theo giá trị: false, 0, con trỏ nil, interface nil và mảng, slices, map hay chuỗi độ dài không. Hãy để ý thứ không có trong danh sách: struct rỗng.

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 chẳng làm gì

Trường kiểu struct không bao giờ bị omitempty bỏ qua — nó sống trong bộ nhớ như một thùng chứa kích thước cố định, và thùng chứa tồn tại không phải là "rỗng". Cách sửa là biến trường thành *Meta; chỉ con trỏ nil bị bỏ đi. Từ Go 1.24 có công tắc thứ hai, omitzero: xét theo giá trị không của Go, gọi IsZero() bool khi kiểu định nghĩa nó — cách duy nhất bỏ được time.Time bằng không. Với encoding/json/v2 (thử nghiệm ở Go 1.25) ngữ nghĩa lại dịch chuyển: omitempty của v2 xét theo kết quả JSON đã mã hóa (chỉ null, "", {}, [] tính là rỗng), nên count: 0 vẫn nằm trong đầu ra; khi di chuyển mã cũ, omitempty trên trường bool và số phải đổi thành omitzero để giữ nguyên nghĩa ban đầu.

Mọi số trở thành float64: cái bẫy của số nguyên lớn

Không có kiểu tường minh, bộ giải mã của encoding/json coi số là float64, và float64 chỉ có 53 bit mantissa. Trường hợp kinh điển của JavaScript — 9007199254740993 biến thành 9007199254740992 — cũng tồn tại ở Go, miễn là trường đích là float64 hoặc any.

var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] là float64(9007199254740992), độ chính xác đã mất

Ba lối thoát. Khai báo trường struct là int64 và bộ giải mã phân tích chính xác vào đó. Khi cần đi qua any, gọi decoder.UseNumber() để số hạ cánh thành chuỗi json.Number mà bạn chuyển đổi một cách có ý thức. Đừng bao giờ dùng số thực dấu phẩy động cho tiền — lưu đơn vị nhỏ hơn trong int64 hoặc dùng thư viện decimal. Bất cứ khi nào API trả về ID snowflake hay số đơn hàng 64 bit, phần này là bước kiểm tra bắt buộc.

time.Time chỉ chấp nhận RFC 3339

Trước "2024-01-15T10:30:00Z" trình tạo map time.Time; trước "2024-01-15 10:30:00" để lại string. Không phải lười — là giới hạn cứng của encoding/json: time.Time triển khai UnmarshalJSON và phân tích nghiêm ngặt theo layout RFC 3339 2006-01-02T15:04:05Z07:00. Thiếu T, thiếu múi giờ hoặc Z kèm offset phía sau — tất cả đều đổ:

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

Khi định dạng upstream không thể thay đổi, cách sửa chuẩn là một kiểu tự viết bọc time.Time, với UnmarshalJSON thử nhiều 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
}

Danh sách kiểm tra bốn bước sau khi tạo

Bốn bước tách đầu ra của trình tạo khỏi mã sản xuất, và đi qua chúng một lần rẻ hơn là debug về sau:

  1. Thay mỗi fallback any: tìm any, xem ba đến năm mẫu thật cho mỗi trường đang fallback rồi hạ xuống kiểu cụ thể hoặc con trỏ;
  2. Kiểm tra lại độ rộng số: chuyển ID, số tiền và bộ đếm từ float64 sang int64 / int32 / decimal; nếu nghi ngờ độ rộng, viết int64;
  3. Đánh dấu tính tùy chọn: con trỏ hoặc omitempty/omitzero cho trường của đối tượng trong mảng, thân PATCH và trường nullable của API bên thứ ba — quyết định ngữ nghĩa nil một lần, tại đây;
  4. Biên dịch và test hai chiều: chạy go vet, rồi thêm test hai chiều Marshal→Unmarshal để khóa định dạng trên dây — nó bắt được sự trôi hành vi của các bản cập nhật encoding/json sau này.

Từ mẫu đến hợp đồng: ranh giới của bộ chuyển đổi

Bộ chuyển đổi trả lời "mẫu này trông thế nào", không trả lời "giao diện này mãi mãi trông thế nào". Các công cụ đối thủ nói thẳng điều đó trong tài liệu của chính họ: một mẫu không thể chứng minh các biến thể sản xuất — tính tùy chọn, định dạng ngày và giá trị enum cần con người xem xét. Vậy nên hãy xây thói quen: trước khi dán, thu thập các phản hồi dễ lộ khác biệt nhất (danh sách rỗng, đầy đủ trường, một bản toàn null); sau khi tạo, coi đầu ra là bản nháp, không phải bản giao. Nếu giao diện có tài liệu hợp đồng, hãy làm ràng buộc tường minh bằng JSON Schema và căn mã đã tạo theo nó — thắng suy luận từ mẫu cả bậc. Để nhìn ngang cùng một vấn đề, phía Java được đề cập trong bài thử nghiệm thực địa của bộ tạo Java, hợp đồng frontend trong các interface TypeScript; hố độ chính xác số quay lại trong mỗi ngôn ngữ với một lớp cải trang khác, chi tiết ở cái bẫy số lớn của JSON.

Những trường nào sau khi tạo vẫn cần chỉnh sửa thủ công?

Ít nhất bốn: fallback any, độ rộng số (float64 → int64), biến trường tùy chọn thành con trỏ, và việc trường ngày nên là string hay time.Time. Cả bốn là biến thể sản xuất vô hình trong mẫu; trình tạo không đoán, con người phải bổ sung.

Tại sao trường của tôi vẫn xuất hiện trong JSON sau khi thêm omitempty?

omitempty chỉ bỏ qua giá trị không: false, 0, "", nil, slice rỗng. Struct rỗng {} không phải giá trị không, nên vẫn sống — hãy biến trường thành con trỏ. time.Time bằng không cần omitzero, không phải omitempty.

Tại sao ID nguyên lớn của tôi đổi sau khi giải tuần tự?

Không có kiểu tường minh, encoding/json phân tích số thành float64, chỉ mang 53 bit mantissa; số nguyên vượt 2^53 mất độ chính xác. Kiểu hóa trường thành int64, hoặc gọi UseNumber() để giữ số dưới dạng json.Number.

Khi nào trường đối tượng lồng nhau nên là con trỏ?

Hai trường hợp: trường có thể vắng mặt hoặc là null (nil tách "không gửi" khỏi "giá trị không"), và yêu cầu PATCH cần phân biệt "không gửi" với "null gửi để xóa". Trong struct phản hồi thông thường với trường không nullable, kiểu theo giá trị an toàn hơn — chỉ trả giá cho việc kiểm tra nil khi thực sự cần sự phân biệt.

Tài liệu tham khảo

Bài viết liên quan

JSON sang lớp Java: bộ tạo chỉ đưa khung, để lên production còn thiếu năm thứ

Cái nhìn thực tế về thứ một bộ tạo JSON-to-Java thực sự xuất ra — số trở thành Double, đối tượng lồng nhau thành class nội bộ static, và không sinh ra một annotation Jackson nào. Độ chính xác tiền tệ, đổi tên trường, xoá kiểu, trường lạ và ngày tháng là năm thứ bạn phải tự bổ sung, mỗi thứ kèm code chép được ngay.

Trung cấpĐọc khoảng 10 phútCập nhật 2026-11-04

Tại sao số nguyên lớn mất độ chính xác

Số nguyên vượt quá 2^53-1 mất độ chính xác trong JSON.parse. ID snowflake, mã đơn hàng và bigint trong cơ sở dữ liệu đều gặp vấn đề này, nên hãy giữ chúng dưới dạng chuỗi từ đầu đến cuối.

Trung cấpĐọc khoảng 4 phútCập nhật 2026-11-04