Go标准库JSON响应需设Content-Type、检查Marshal错误、优先用Encoder流式写入，状态码须显式控制，time.Time字段需明确tag，核心是早暴露错误、语义清晰、行为可预测。
Go标准库json.Marshal与http.ResponseWriter配合使用是基础但易出错的起点
直接用json.Marshal序列化结构体再写入http.ResponseWriter，看似简单，但漏掉关键步骤会导致前端解析失败或服务端 panic。最常见错误是没设置Content-Type头，浏览器或客户端默认按text/plain处理响应，JSON字符串被当成纯文本；另一个是没检查json.Marshal返回的error——当结构体含不可序列化字段（如func、chan、未导出字段嵌套指针）时会静默失败或panic。
实操建议：
- 始终在
WriteHeader前调用w.Header().Set("Content-Type", "application/json; charset=utf-8") - 必须检查
json.Marshal返回的err，非nil时应记录日志并返回http.StatusInternalServerError - 避免直接
w.Write原始字节，优先用w.WriteHeader(statusCode)+w.Write(b)显式控制状态码
func handler(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
data := map[string]string{"msg": "ok"}
b, err := json.Marshal(data)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
w.WriteHeader(http.StatusOK)
w.Write(b)
}
用encoding/json.Encoder替代json.Marshal可减少内存拷贝和中间切片
当响应数据较大（如查询返回上千条记录），json.Marshal先生成完整[]byte再写入响应体，会额外分配内存；而json.Encoder直接流式写入http.ResponseWriter（它实现了io.Writer），更省内存、更适合大响应。
注意点：
-
Encoder不自动设置Content-Type，仍需手动调用w.Header().Set - 如果写入过程中发生错误（如客户端提前断连），
Encode会返回error，需捕获并处理 - 不能在
Encode后调用w.WriteHeader——状态码必须在写入前设置，否则可能被忽略
func handler(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(http.StatusOK)
enc := json.NewEncoder(w)
err := enc.Encode(map[string]int{"count": 123})
if err != nil {
log.Printf("encode error: %v", err)
}
}
自定义ResponseWriter封装常用状态码和结构（如Success/Fail）容易掩盖HTTP语义
很多项目定义类似WriteSuccess(w, data)或WriteJSON(w, 200, data)的工具函数，初衷是简化，但实际带来两个问题：一是把HTTP状态码硬编码进业务逻辑，导致404、422等语义丢失；二是统一包装后难以做细粒度响应控制（如部分接口要加Cache-Control，部分要设Set-Cookie）。
更稳妥的做法是：
- 保留
http.ResponseWriter原生接口，让 handler 自己决定状态码和头信息 - 若真要复用，只封装
json序列化+Content-Type设置，不碰WriteHeader - 对错误响应，统一用
http.Error或自定义ErrorResponse结构体，但状态码仍由 handler 显式传入
第三方库如github.com/go-chi/chi或github.com/gin-gonic/gin的JSON方法本质仍是封装，别盲目依赖
像ctx.JSON(200, data)这类方法看着方便，但底层仍是调用json.Marshal或Encoder，只是把Content-Type和WriteHeader打包了。问题在于：一旦遇到自定义时间格式、空值处理（omitempty vs ""）、循环引用，这些封装往往不提供透出底层json.Encoder的钩子，调试困难。
建议：
- 小项目用标准库足够，无需引入框架
- 中大型项目若选框架，务必确认其
JSON方法是否支持自定义json.Marshaler或Encoder.SetEscapeHTML等配置 - 所有
time.Time字段必须明确指定json:"xxx,time_ms"等 tag，否则默认 RFC3339 格式可能和前端期望不符
Go 的 JSON 响应设计，核心不是“怎么写得短”，而是“怎么让错误暴露得早、状态码语义清晰、序列化行为可预测”。最容易被忽略的是：http.ResponseWriter不是普通io.Writer——它的WriteHeader只能调用一次，且必须在任何Write之前；而json包对零值、嵌套结构、指针解引用的处理，全靠 struct tag 和类型定义驱动，写错一个json:"-,omitempty"就可能导致字段消失。