粘贴 Go 的 struct 定义,就能按照 encoding/json 在 marshal 时所用的同一套规则生成示例 JSON 文档:json:"..." 标签名、用 - 隐藏的字段、,string 选项、未导出的小写字段,以及被展开的嵌入 struct。
用 Gin、Echo 或 net/http 的请求 struct 生成 curl 请求体、为 gRPC-Gateway 或 REST 文档准备示例,以及找出标签没有生成预期 key 的字段时,它都很方便。
type Xxx struct { ... } 声明。分组的 type ( ... ) 块以及一次粘贴多个 struct 都没问题。decimal.Decimal)会变成 null。curl -d、Postman 请求体或基于 httptest 的处理函数测试中。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
}{
"id": "",
"created_at": "0001-01-01T00:00:00Z",
"queue": "",
"attempts": "0",
"labels": {
"key": ""
},
"timeout_sec": 0,
"Done": false
}嵌入的 Base 把 id 和 created_at 直接贡献给了 Job;带 ,string 标签的 Attempts 变成字符串 "0" 而不是数字。Token(标签为 -)和未导出的 lastErr 被去掉,没有标签的 Done 则以 Go 字段名作为 key。time.Time 显示 Go 的零值 0001-01-01T00:00:00Z。
json:"name" 标签作为 key,没有标签时退回到完全相同的字段名。json:"-" 字段和未导出的小写字段;json:"-," 会以字面量 key - 保留该字段。,string 时,数值和布尔字段会被包成 "0"、"false" 这样的字符串。*int、*Profile)用所指向的类型填充,type Status string 这样的自定义类型按其底层类型处理。[]byte 变成 Base64(空)字符串,map[int]T 使用 "0" 作为 key,time.Duration 是以纳秒计的整数 0,interface{}/any 为 null。Children []Node 这样自引用的 struct 会在空数组处停止。支持匿名嵌套 struct 字段。粘贴用 c.ShouldBindJSON(&req) 绑定的 struct,生成请求体,再通过 httptest.NewRequest 或 curl 调用接口。由于 key 直接来自标签,绑定不匹配的情况会更少。
json:"user_id" 和 json:"userId" 混用,或者忘写标签导致大写的 UserID key 泄漏出去,在输出中一眼就能看出来。
把 Go 响应 struct 生成的 JSON 交给前端或 Python 使用方,他们可以用 JSON → TypeScript 或 JSON → Python 等工具再把它变回模型。
omitempty 字段在示例中总会显示;实际 marshal 时,它们为零值就会被省略。nil 指针会 marshal 成 null,但示例展示的是有值的情况。MarshalJSON() 的类型以及 json.RawMessage 的实际内容无从得知,不会体现在输出中。omitzero 等较新的选项以及 encoding/json/v2 的行为。encoding/json 会原样使用导出的字段名,所以 Done bool 变成 "Done"。在 Go 中解码时不区分大小写匹配,但其他语言的客户端并非如此,所以显式写标签更安全。
time.Time 是 0001 年?Go 中 time.Time 的零值是 0001-01-01 00:00:00 UTC,按 RFC 3339 marshal 后为 0001-01-01T00:00:00Z。这就是它与其他 → JSON 页面中 1970 年日期不同的原因。
json:",string" 什么时候有用?主要用于 JavaScript 无法精确表示的大 int64 ID,让它们以字符串形式传输。示例显示 "0",能让客户端清楚地知道会收到字符串。
请使用 JSON → Go struct 页面。把它的输出再放回本页,可以快速确认往返转换后原始 key 是否保持不变。