Go Web开发中真正的优雅是让handler只关注业务逻辑，通过封装JSONResponse函数统一处理Content-Type、状态码和序列化，避免直接使用json.Marshal+w.Write导致的崩溃、语义不清等问题。
Go Web 开发中，所谓“优雅”不是堆砌中间件或强塞三层嵌套结构，而是让每个 handler 只关心业务逻辑，不碰 Content-Type、不手动调用 w.WriteHeader()、不重复写 json.NewEncoder(w).Encode(...)。真正的优雅，是错误能透出、状态码语义清晰、序列化不 panic、结构体可测试可导出。
为什么直接用 json.Marshal + w.Write 写响应容易崩？
这不是风格问题，是硬性缺陷：
-
Content-Type没设——某些客户端（比如老版本 Axios 或 Postman 的 raw 模式）会当普通文本解析，response.data变成字符串而不是对象 -
json.Marshal返回([]byte, error)，忽略error就等于默许 panic：字段未导出、含func类型、循环引用，都会让整个请求卡死或 500 且无日志 - HTTP 状态码全写
200——创建资源该用201 Created、删完无内容该用204 No Content，硬编码 200 会让前端无法靠 status 做自动重试或清缓存 - 用
map[string]interface{}当响应体——IDE 无提示、单元测试难 mock、字段拼错运行时才暴露
应该定义一个真正可用的 Response 结构体
别用 map，也别一上来就加 code/msg/data 三层壳。先从传输层干净封装开始：
type Response struct {
Code int `json:"code"` // 业务码，如 200/4001/5003
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
Timestamp int64 `json:"timestamp"`
}
-
Data用interface{}是为了兼容性，但实际 handler 中应传具体 struct（如User、OrderList），不是map -
Timestamp是int64而非time.Time：避免时区、格式化依赖，前端直接Date.now()对齐 - 所有字段首字母大写——否则 JSON 序列化为空，这是最常被忽略的导出规则
- 不要加
Pagination字段到顶层结构体——只在列表接口的Data里嵌套，否则单条资源响应也带空 pagination，误导前端
封装 JSONResponse 函数，而不是 Success/Fail 工具集
所谓 “Success/Fail” 是业务协议层的事，JSONResponse 只管三件事：设头、序列化、写状态码。它不该决定 Code 是 0 还是 200，也不该内置 "success" 字符串：
func JSONResponse(w http.ResponseWriter, data interface{}, statusCode int, message string) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(statusCode)
resp := Response{
Code: statusCode, // 或按需映射为业务码，但别在这里硬编码
Message: message,
Data: data,
Timestamp: time.Now().Unix(),
}
if err := json.NewEncoder(w).Encode(resp); err != nil {
http.Error(w, "encoding error", http.StatusInternalServerError)
log.Printf("JSON encode failed: %v", err)
}
}
- 参数显式传
statusCode，不默认 200——POST /users就该传http.StatusCreated -
message保留为可选调试字段，生产环境建议统一设为空字符串，避免泄露路径、SQL 片段等 - 别在函数里打日志——日志由中间件或 handler 上层统一加 trace_id 和请求路径
- 不要用
json.Marshal+w.Write：前者可能分配大内存，后者不处理流式写入失败；json.Encoder更稳妥
别把 ResponseWriter 存成全局变量或结构体字段
这是并发场景下最隐蔽的坑：
- 每个 HTTP 请求都有独立的
http.ResponseWriter和*http.Request实例 - 一旦你把它存进包级变量、或某个结构体的字段（比如
svc.w = w），多个 goroutine 会同时读写它 - 结果可能是 A 请求的响应体被写进 B 请求的连接，或者
WriteHeader被覆盖，前端收到 200 但 body 是空的，查日志却显示一切正常 - 正确做法：所有封装函数都把
w http.ResponseWriter作为参数传入，不保存、不复用、不缓存
最复杂的点从来不是结构体怎么定义，而是谁来决定 HTTP 状态码、谁来捕获 panic、谁来控制 Content-Type 的生命周期——这些必须收口到同一层，且不能跨 goroutine 共享状态。否则再“统一”的格式，也会在高并发下漏出裂缝。
