Chuyển struct Go thành JSON!

Nhập struct Go để tạo JSON mẫu theo thẻ json của chúng! Hỗ trợ Go (Golang) struct, json tags. Hữu ích cho tài liệu API và request body thử nghiệm (mock request body).
Go struct
Kết quả
 

Chuyển struct Go thành JSON!

Dán định nghĩa struct của Go để nhận một tài liệu JSON mẫu được dựng theo đúng quy tắc mà encoding/json áp dụng khi marshal: tên trong tag json:"...", field bị ẩn bằng -, option ,string, field chữ thường không export và struct nhúng được làm phẳng.

Công cụ tiện cho việc tạo body curl từ struct request của Gin, Echo hay net/http, chuẩn bị mẫu cho gRPC-Gateway hoặc tài liệu REST, và phát hiện những field có tag không cho ra key như bạn mong đợi.

Cách sử dụng

  1. Dán các khai báo type Xxx struct { ... }. Khối nhóm type ( ... ) và nhiều struct cùng lúc đều được.
  2. Nếu một field dùng struct khác, hãy đưa cả định nghĩa đó vào. Kiểu của package bên ngoài không có trong đầu vào (như decimal.Decimal) thành null.
  3. Không có option nào: struct đầu tiên không bị kiểu khác tham chiếu sẽ là JSON cấp cao nhất, nên hãy đặt struct bạn muốn lên đầu hoặc bỏ các struct không liên quan.
  4. Sao chép kết quả vào curl -d, body của Postman hoặc test handler dựa trên httptest.

Ví dụ

Đầu vào (Go struct)
type Base struct {
	ID        string    `json:"id"`
	CreatedAt time.Time `json:"created_at"`
}

type Job struct {
	Base
	Queue      string            `json:"queue"`
	Attempts   int               `json:"attempts,string"`
	Labels     map[string]string `json:"labels,omitempty"`
	TimeoutSec *int              `json:"timeout_sec,omitempty"`
	Token      string            `json:"-"`
	Done       bool
	lastErr    error
}
Đầu ra (JSON)
{
  "id": "",
  "created_at": "0001-01-01T00:00:00Z",
  "queue": "",
  "attempts": "0",
  "labels": {
    "key": ""
  },
  "timeout_sec": 0,
  "Done": false
}

Base được nhúng đóng góp trực tiếp id và created_at vào Job, và Attempts, có tag ,string, thành chuỗi "0" thay vì số. Token (tag -) và lastErr không export bị bỏ, còn Done không có tag giữ tên field Go làm key. time.Time hiện giá trị zero của Go, 0001-01-01T00:00:00Z.

Tính năng hỗ trợ

  • Dùng tag json:"name" làm key, nếu không có tag thì dùng đúng tên field.
  • Bỏ qua field json:"-" và field chữ thường không export; json:"-," giữ field dưới key nguyên văn là -.
  • Với ,string, field số và boolean được bọc thành chuỗi như "0" và "false".
  • Struct nhúng không có tag được làm phẳng vào struct cha, field bên ngoài thắng khi trùng tên; struct nhúng có tag thành object lồng nhau dưới tên đó.
  • Con trỏ (*int, *Profile) được điền theo kiểu mà nó trỏ tới, và defined type như type Status string theo kiểu nền của nó.
  • []byte thành chuỗi Base64 (rỗng), map[int]T dùng key "0", time.Duration là số nguyên nano giây 0, còn interface{}/any là null.
  • Struct tự tham chiếu như Children []Node dừng ở một mảng rỗng. Field struct lồng ẩn danh được hỗ trợ.

Trường hợp sử dụng

Body request cho test handler

Dán struct bạn bind bằng c.ShouldBindJSON(&req), tạo body, rồi gọi endpoint qua httptest.NewRequest hoặc curl. Vì key lấy thẳng từ tag, khả năng bind lệch sẽ thấp hơn.

Tìm lỗi trong tag

Tag json:"user_id" và json:"userId" dùng lẫn lộn, hay một tag bị quên làm lộ ra key viết hoa UserID, đều thấy ngay khi nhìn output.

Chia sẻ schema với client viết bằng ngôn ngữ khác

Đưa cho phía frontend hoặc Python JSON từ struct response Go của bạn; họ có thể biến nó lại thành model bằng các công cụ như JSON → TypeScript hay JSON → Python.

Lưu ý và giới hạn

  • Field omitempty luôn được hiện trong mẫu; khi marshal thật chúng bị bỏ nếu đang giữ giá trị zero.
  • Con trỏ nil được marshal thành null, nhưng mẫu hiện trường hợp đã có giá trị.
  • Kiểu có MarshalJSON() tùy biến và nội dung thực của json.RawMessage không thể biết trước nên không được phản ánh.
  • Các option mới hơn như omitzero của Go 1.24 và hành vi của encoding/json/v2 không được hỗ trợ.

Câu hỏi thường gặp

Field không có tag nhận key gì?

encoding/json dùng nguyên văn tên field đã export, nên Done bool thành "Done". Khi decode trong Go việc so khớp không phân biệt hoa/thường, nhưng client ở ngôn ngữ khác thì có, nên tag tường minh an toàn hơn.

Vì sao time.Time lại là năm 0001?

Giá trị zero của time.Time trong Go là 0001-01-01 00:00:00 UTC, được marshal theo RFC 3339 thành 0001-01-01T00:00:00Z. Đó là lý do nó khác với ngày năm 1970 trên các trang chuyển sang JSON khác.

Khi nào json:",string" có ích?

Chủ yếu cho ID int64 lớn mà JavaScript không biểu diễn chính xác được, nên chúng được truyền dưới dạng chuỗi. Mẫu hiện "0", cho client thấy rõ rằng họ sẽ nhận chuỗi.

Tôi muốn chiều ngược lại: struct Go từ JSON.

Hãy dùng trang JSON → Go struct. Đưa output của trang đó trở lại trang này là cách nhanh để kiểm tra vòng chuyển đổi có giữ nguyên key gốc hay không.