应使用统一响应结构体封装writejson函数：code严格对应http状态码，message为用户提示，data仅承载业务数据，pagination仅列表接口使用，bizcode区分业务码；错误路径也返回同结构体，避免混用状态码与业务码。
为什么直接在 handler 里写 json.NewEncoder(w).Encode() 不够优雅
因为每次都要重复设 Content-Type、手动调用 w.WriteHeader()、检查 json.Marshal 错误，稍一遗漏就会返回空响应或 panic。更麻烦的是，不同 handler 对「成功」「失败」的判断逻辑不一致：有的用 http.StatusOK 包裹业务错误码，有的直接 http.Error()，前端拿到 200 却发现 code: 400，语义混乱。
关键问题不在序列化本身，而在于 HTTP 状态码和业务状态码混用、错误路径未走同一结构体、Data 字段语义模糊（是业务数据？还是错误详情？）。
- HTTP 状态码应真实反映请求结果：400 就该是
w.WriteHeader(http.StatusBadRequest)，不是200+{"code":400} -
Data必须只承载业务数据，错误信息统一走Message字段，否则前端要写两套解析逻辑 - 所有 handler 都该返回同一个结构体实例，而不是
map[string]interface{}—— 后者让 IDE 失去提示、测试难覆盖、Swagger 无法生成准确类型
Response 结构体该包含哪些字段才真正实用
别抄网上“code/message/data”三字段万金油模板。它掩盖了 HTTP 层和业务层的职责分离。真正需要的是：
-
Code int：严格对应 HTTP 状态码（200、404、500），不是业务码。这样 Nginx、CDN、浏览器缓存行为才可预期 -
Message string：用户可见提示，生产环境可为空，开发环境建议保留（便于调试） -
Data interface{}：仅当有业务数据时填充，配合omitempty标签，避免空数组/空对象污染响应 -
Pagination *PaginationInfo：仅列表接口设置，非列表接口不出现该字段，避免前端每次都要做类型断言
业务码如果真需要，加个 BizCode int 字段，和 Code 明确区分开。时间戳字段慎加——除非审计强依赖，否则前端自己取 Date header 更轻量。
封装 WriteJSON 函数时最容易踩的三个坑
很多人封装完函数就以为万事大吉，结果上线后发现日志全丢、panic 不被捕获、状态码被覆盖。根本原因是对 Go HTTP 的执行模型理解偏差。
- 别在封装函数里调用
w.WriteHeader()后再调用json.NewEncoder(w).Encode()—— 如果 handler 已经写过 header（比如中间件提前设置了 401），这里会 panic - 别忽略
json.NewEncoder(w).Encode()的返回 error：它可能因字段不可导出（小写首字母）、含func类型、循环引用而失败，错误必须透出并记录，不能静默吞掉 - 别用包级变量或结构体字段缓存
http.ResponseWriter或*http.Request—— 每个请求都是独立 goroutine，复用会导致 A 请求响应写到 B 请求的连接上
正确做法是把 WriteJSON 设计为纯函数：输入 w、status、v，内部只做一次 w.WriteHeader(status) 和一次 json.NewEncoder(w).Encode(v)，错误原样返回给 handler 上层处理。
要不要用中间件自动包装响应
不要。gorilla/mux、chi 甚至 Gin 的 Recovery 中间件都解决不了核心问题：中间件不知道 handler 是否已写响应、是否已 panic、是否调用了 http.Error。强行包装会导致重复写 header、两次 encode、或 panic 后仍试图 write。
真正可靠的路径只有一条：每个 handler 显式构造 Response 实例，并在最后调用 WriteJSON。错误路径也走同一结构体，比如 Response{Code: http.StatusUnauthorized, Message: "token expired"}，而不是 http.Error(w, "...", 401)。
唯一值得加的中间件是 panic 捕获（defer recover()），但它只负责兜底，不替代 handler 内部的结构化错误构造。复杂点在于：handler 内部的校验、DB 查询、下游调用等每一步错误，都要转成明确的 Response 实例，而不是裸 error 一路传上去再统一处理——那样会丢失上下文，也违背 Go 的显式错误处理哲学。
