如何使用Golang实现JSON序列化_使用json.Marshal返回客户端数据_技术教程

Go中API返回JSON需确保字段导出并合理使用json标签，设置Content-Type响应头，用json.Marshal或更优的json.NewEncoder处理序列化，严格检查错误并避免不可序列化类型。

在 Go 中，使用 json.Marshal 将结构体或基本类型转为 JSON 字节流，再通过 HTTP 响应返回给客户端，是最常见的 API 数据输出方式。关键在于确保数据可序列化、设置正确响应头、处理错误，并避免常见陷阱。

确保结构体字段可导出且可序列化

Go 的 json 包只能序列化**首字母大写的导出字段**。小写字段会被忽略，不会出现在 JSON 中。

建议为字段添加 JSON 标签（tag），控制键名、是否忽略空值、时间格式等：

用 json:"name" 自定义字段名
用 json:"name,omitempty" 在字段为空值（零值）时跳过该字段
对 time.Time 类型，推荐用 json:"created_at,string" 输出为字符串格式（ISO8601）

示例：

type User struct {
  ID int `json:"id"`
  Name string `json:"name"`
  Email string `json:"email,omitempty"`
  CreatedAt time.Time `json:"created_at,string"`
}

用 json.Marshal 生成 JSON 并写入 ResponseWriter

调用 json.Marshal 返回 []byte 和 error。不要直接打印或忽略 error —— 序列化失败通常因含不可序列化类型（如函数、map[interface{}]interface{}、未导出字段嵌套等）。

标准写法是：

先设置响应头：w.Header().Set("Content-Type", "application/json; charset=utf-8")
调用 json.Marshal，检查 error；若失败，用 http.Error 返回 500
成功则用 w.Write(data) 输出字节流（注意不是 fmt.Fprint）

示例片段：

func handler(w http.ResponseWriter, r *http.Request) {
  u := User{ID: 1, Name: "Alice", CreatedAt: time.Now()}
  w.Header().Set("Content-Type", "application/json; charset=utf-8")
  data, err := json.Marshal(u)
  if err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
    return
  }
  w.Write(data)
}

处理嵌套结构与 nil 指针安全

如果结构体字段是指针（如 *string、*int），且值为 nil，默认会序列化为 null。这通常是期望行为，但需确认前端能否正确处理。

若想完全跳过 nil 字段，仍可用 omitempty 标签 —— 它对 nil 指针、nil slice、nil map 等均生效。

注意：嵌套结构体中含未导出字段或不可序列化类型（如 sync.Mutex），会导致 json.Marshal 报错。建议只序列化纯数据结构，业务逻辑对象可额外定义 DTO（Data Transfer Object）类型。

更简洁可靠的方式：使用 json.NewEncoder

相比 json.Marshal + w.Write，直接用 json.NewEncoder(w).Encode(v) 更推荐：

自动处理 Content-Type（但仍建议显式设置）
边编码边写入，内存更友好（尤其大数据量）
一次调用完成，不易漏掉 error 检查

示例：

w.Header().Set("Content-Type", "application/json; charset=utf-8")
err := json.NewEncoder(w).Encode(u)
if err != nil {
http.Error(w, "JSON encode error", http.StatusInternalServerError)
return
}

基本上就这些。核心是结构体设计合理、标签用得准、错误不忽略、响应头不遗漏。不复杂但容易忽略细节。