如何在 Go 中正确返回 JSON 响应

本文详解在 go Web 开发中规范返回 jsON 数据的两种推荐方式：手动设置 Content-Type 头并使用 json.Marshal，或直接利用 json.Encoder 流式编码，确保响应符合 restful 规范且可被前端可靠消费。

本文详解在 go web 开发中规范返回 json 数据的两种推荐方式：手动设置 `content-type` 头并使用 `json.marshal`，或直接利用 `json.encoder` 流式编码，确保响应符合 restful 规范且可被前端可靠消费。

在 Go 中返回 JSON 并非简单地将字节切片写入 http.ResponseWriter，而需同时满足两个关键条件：正确的 HTTP 响应头（尤其是 Content-Type: application/json） 和 合法、格式良好的 JSON 字符串。否则，前端框架（如 React、Vue 或 axios）可能无法自动解析响应，导致 response.json() 抛错或数据丢失。

以下是在基于 httprouter 的示例中实现标准 JSON 响应的两种专业做法：

✅ 推荐方式一：显式设置 Header + json.MarshalIndent（适合调试与结构化输出）

func Index(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {     p, err := getJsonResponse()     if err != nil {         http.Error(w, "internal Server Error", http.StatusInternalServerError)         return     }      // 关键：声明响应内容类型为 JSON     w.Header().Set("Content-Type", "application/json; charset=utf-8")     // 使用 MarshalIndent 提升可读性（生产环境可改用 json.Marshal）     w.WriteHeader(http.StatusOK)     fmt.Fprint(w, String(p)) }

⚠️ 注意：fmt.Fprintf(w, string(response)) 存在隐患——若 response 含非 UTF-8 字节或未校验 JSON 合法性，易引发乱码或解析失败；且遗漏 Content-Type 将导致浏览器/客户端默认按 text/plain 处理。

✅ 推荐方式二：使用 json.Encoder（更安全、内存友好、推荐用于生产）

func Index(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {     fruits := map[string]int{"Apples": 25, "Oranges": 10}     vegetables := map[string]int{"Carrots": 10, "Beets": 0} // 修正拼写：Carrats → Carrots     d := Data{Fruit: fruits, Veggies: vegetables}     p := Payload{Stuff: d}      // 直接编码到 ResponseWriter，自动处理 UTF-8 和流式写入     w.Header().Set("Content-Type", "application/json; charset=utf-8")     w.WriteHeader(http.StatusOK)     if err := json.NewEncoder(w).Encode(p); err != nil {         http.Error(w, "JSON encode error", http.StatusInternalServerError)         return     } }

该方式优势显著：

• 自动处理字符编码与转义；
• 支持大结构体流式序列化，避免中间 []byte 内存拷贝；
• Encode() 内置错误检查，便于及时捕获序列化异常（如含 nil channel、不支持类型的字段）。

? 补充建议与最佳实践

• 始终设置状态码：显式调用 w.WriteHeader(http.StatusOK)（或 400/500 等），避免依赖默认 200 导致语义模糊；
• 统一错误处理：避免 panic(err)，应返回 4xx/5xx 状态码及结构化错误 JSON（例如 {“error”: “invalid request”}）；
• 类型定义优化：Fruits 和 Vegetables 宜定义为具名类型以增强可读性与 JSON 字段控制（当前 map[string]int 序列化为对象，符合预期）；
• 生产环境精简缩进：json.MarshalIndent 适用于开发调试；上线时建议改用 json.Marshal 减少空格开销。

通过以上任一方式，你的 Go 服务即可输出标准、健壮、可互操作的 JSON 响应，无缝对接现代前端生态。