在 Go 中调用 REST API（如 Geckoboard 领导榜接口）时，需通过结构体建模请求数据；关键在于正确导出字段并使用 json 标签控制序列化键名，确保生成符合 API 要求的标准 JSON。
在 go 中调用 rest api（如 geckoboard 领导榜接口）时，需通过结构体建模请求数据；关键在于正确导出字段并使用 `json` 标签控制序列化键名，确保生成符合 api 要求的标准 json。
Go 语言要求：只有首字母大写的字段才是可导出（exported）字段，才能被 json.Marshal 等外部包访问并序列化。若定义为小写字段（如 label、value），即使结构体本身是大写的，这些字段仍为私有，json 包无法读取，最终序列化结果中将完全缺失对应字段——这正是初学者常遇到的“JSON 字段为空”或“结构体不生效”的根本原因。
正确的做法是：统一使用大写首字母命名字段，并通过 json struct tag 显式指定 JSON 键名。例如，针对 Geckoboard 领导榜所需的 label、value 和 previous_value 字段，应定义如下：
type Contestant struct {
Label string `json:"label"`
Value int8 `json:"value"`
PreviousRank int8 `json:"previous_rank"`
}
type LeaderboardRequest struct {
APIKey string `json:"api_key"`
Data LeaderboardData `json:"data"`
}
type LeaderboardData struct {
Items []Contestant `json:"item"` // 注意：Geckoboard 文档中键名为 "item"（单数），非 "items"
}完整使用示例：
req := LeaderboardRequest{
APIKey: "222f66ab58130a8ece8ccd7be57f12e2",
Data: LeaderboardData{
Items: []Contestant{
{Label: "Bob", Value: 4, PreviousRank: 6},
{Label: "Alice", Value: 3, PreviousRank: 4},
},
},
}
payload, err := json.Marshal(req)
if err != nil {
log.Fatal("JSON marshaling failed:", err)
}
fmt.Println(string(payload))
// 输出符合 API 要求的 JSON：
// {"api_key":"222f66ab58130a8ece8ccd7be57f12e2","data":{"item":[{"label":"Bob","value":4,"previous_rank":6},{"label":"Alice","value":3,"previous_rank":4}]}}⚠️ 注意事项：
- json tag 中的键名必须严格匹配目标 API 的字段名（包括大小写与下划线风格），例如 previous_rank 不可误写为 previousRank 或 previous-rank；
- 若字段可能为空，可添加 ,omitempty（如 json:"label,omitempty"）避免零值字段出现在输出中（但本例中 label 为必需字段，不建议省略）；
- 所有嵌套结构体（如 LeaderboardData）也须遵循相同规则：字段导出 + 正确 tag；
- 使用 json.MarshalIndent 可提升调试时的可读性，但生产环境建议用 json.Marshal 以减少开销。
遵循这一模式，你不仅能精准适配 Geckoboard 接口，还能轻松扩展支持其他 JSON API——结构清晰、类型安全、符合 Go 的惯用法（idiomatic Go）。
