本文详解 go 语言中解析 usda 食品营养数据库（api.nal.usda.gov/ndb）json 响应的常见错误与正确做法，重点解决结构体嵌套不匹配、字段类型错配导致的反序列化为空的问题。
本文详解 go 语言中解析 usda 食品营养数据库（api.nal.usda.gov/ndb）json 响应的常见错误与正确做法，重点解决结构体嵌套不匹配、字段类型错配导致的反序列化为空的问题。
USDA NDB API 返回的 JSON 并非扁平结构，而是以顶层键 "list" 包裹全部搜索结果数据。你定义的 List 结构体虽能准确描述 "list" 内部内容，但缺少对最外层对象的建模——即 JSON 实际结构为 { "list": { ... } }，而你的 json.Unmarshal(b, &l) 尝试直接将整个响应解码到 List 类型，相当于期望输入是 {...}，但实际是 {"list":{...}}，因此所有字段均为零值，最终打印出 { []}。
✅ 正确做法是：定义一个外层包装结构体，显式对应顶层 JSON 对象：
type Response struct {
List List `json:"list"`
}
type List struct {
Q string `json:"q,omitempty"`
Sr string `json:"sr,omitempty"`
Ds string `json:"ds,omitempty"`
Start int `json:"start,omitempty"` // ✅ 数字字段应使用 int/float64，而非 string
End int `json:"end,omitempty"`
Total int `json:"total,omitempty"`
Group string `json:"group,omitempty"`
Sort string `json:"sort,omitempty"`
Item []Item `json:"item,omitempty"`
}
type Item struct {
Offset int `json:"offset,omitempty"` // ✅ offset 是整数
Group string `json:"group,omitempty"`
Name string `json:"name,omitempty"`
Ndbno string `json:"ndbno,omitempty"` // ⚠️ 注意：原代码中写成了 "nbno"（漏了 'd'），必须与 JSON 键完全一致
Ds string `json:"ds,omitempty"`
}然后按如下方式解码：
var resp Response
err := json.Unmarshal(b, &resp)
if err != nil {
log.Fatal("JSON unmarshal error:", err)
}
fmt.Printf("Found %d items\n", len(resp.List.Item))
for _, item := range resp.List.Item {
fmt.Printf("- %s (NDB: %s)\n", item.Name, item.Ndbno)
}⚠️ 关键注意事项：
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
-
字段名拼写必须精确匹配 JSON 键：
"ndbno"≠"nbno"，原结构体中Ndbno的 tag 写成了`json:"nbno,omitempty"`，会导致该字段始终为空； -
数值字段优先用
int或float64：start、end、total、offset在 JSON 中均为数字，使用string会导致解析失败且无报错（因omitempty会跳过空字符串）； -
避免过度使用
omitempty：它仅影响序列化（编码），对反序列化（解码）无影响；若字段必存在，可省略以提升可读性与调试效率； -
推荐使用
log替代panic：生产环境中应妥善处理 HTTP 错误与 I/O 异常，而非直接 panic。
完整修复后的 fetch() 方法示例：
func (sr *SearchRequest) fetch() {
url := "https://api.nal.usda.gov/ndb/search/?" +
"format=" + url.QueryEscape(sr.format) +
"&q=" + url.QueryEscape(sr.q) +
"&sort=" + url.QueryEscape(sr.sort) +
"&max=" + strconv.FormatInt(sr.max, 10) +
"&offset=" + strconv.FormatInt(sr.offset, 10) +
"&api_key=" + sr.c.ApiKey
resp, err := http.Get(url)
if err != nil {
log.Printf("HTTP request failed: %v", err)
return
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
log.Printf("Failed to read response body: %v", err)
return
}
var apiResp Response
if err := json.Unmarshal(body, &apiResp); err != nil {
log.Printf("JSON decode error: %v\nRaw response: %s", err, string(body))
return
}
log.Printf("Search '%s': %d results (page %d–%d)",
sr.q, apiResp.List.Total, apiResp.List.Start+1, apiResp.List.End)
for i, item := range apiResp.List.Item[:min(3, len(apiResp.List.Item))] {
log.Printf(" [%d] %s — %s", i+1, item.Name, item.Ndbno)
}
}（注：min(a,b) 可用 int(math.Min(float64(a), float64(b))) 或 Go 1.21+ 的 cmp.Min 替代）
通过以上调整，即可稳定、准确地解析 USDA NDB API 的 JSON 响应，为后续营养数据分析打下坚实基础。
