不推荐用 gin 中间件自动包装响应，因 responsewriter 不可重读，c.json() 后无法捕获原始数据，易触发“response already committed”错误、broken pipe panic 及统一格式失效。
用 Gin 中间件自动包装响应会踩哪些坑
不推荐用中间件自动把 c.Next() 后的响应体再读一遍、套上统一结构——这种做法在 c.JSON() 已写入 body 后根本捕获不到原始数据，还可能触发 http: response already committed 错误。Gin 的 ResponseWriter 不支持 rewind，中间件无法“事后补救”已发出的响应。
常见错误现象包括：前端收不到 data 字段、code 总是 200、panic 时日志里出现 write tcp: broken pipe。本质是试图绕过 Gin 的执行流控制，和框架底层机制冲突。
- 别在中间件里调用
c.Writer.Header().Set()后再试图读c.Writer.Body—— 它不是可读流 - 不要用
io.TeeReader拦截 Gin 的c.Request.Body，Gin 默认已解析 form 或 json，多次读会报http: read on closed body - 如果用了
c.Abort()或c.String()等非 JSON 返回方式，中间件完全无法感知，统一格式就漏了
真正能落地的 Gin 统一响应中间件只做一件事
它不干涉业务逻辑，也不重写响应体，只确保每个 handler 都显式调用封装函数——通过 context 标记 + defer 校验实现“强制约定”。
核心思路：在中间件里往 c 写一个标记（比如 c.Set("response_written", true)），然后在 defer 里检查是否被设置；没设就 panic 或 log 警告，倒逼开发者调用 Success(c, data) 或 Error(c, code, msg)。
- 定义两个导出函数：
Success(*gin.Context, interface{})和Error(*gin.Context, int, string)，内部调用c.JSON()并设标记 - 中间件仅含三行：
c.Next()+defer检查标记 +if !c.IsWritten() { log.Warn("handler missed response write") } - 禁止 handler 里直接用
c.JSON()、c.String()、c.Status()—— 这些绕过封装，破坏一致性
为什么 Response 结构体字段必须大写 + 正确 tag
Go 的 json.Marshal 只序列化首字母大写的导出字段，且依赖 json: tag 控制 key 名。写成 Code int `json:"code"` 是底线，写成 code int `json:"code"` 或漏掉 tag，结果就是返回空对象 {} 或字段名大小写错乱。
典型翻车点：字段名拼错（Msg 写成 msg）、tag 里多空格（`json: "code"` → 实际是 `json:"code"`）、忘记加 omitempty 导致 data: null 出现在成功响应里。
-
Data interface{} `json:"data,omitempty"`—— 成功时为 struct/map，失败时为nil，避免冗余"data": null -
Timestamp int64 `json:"timestamp"`—— 用time.Now().UnixMilli()，别用time.Now().Unix()丢精度 - 所有字段必须导出：
Code、Message、Data、Timestamp，小写开头等于没序列化
不用中间件也能统一？那得靠函数封装 + 团队约束
最简方案是删掉中间件，只提供 WriteJSON(w http.ResponseWriter, code int, data interface{}) 函数，在每个 handler 末尾手动调用。它比中间件更可控，没有 panic 恢复、body 重放等副作用。
这个函数内部固定写 w.Header().Set("Content-Type", "application/json; charset=utf-8")，调用 json.NewEncoder(w).Encode()，并确保 http.StatusOK 之外的状态码也走同一结构（比如 400 返回 {"code":400,"message":"xxx","data":null}）。
- 别让
WriteJSON自动设置http.StatusXXX—— HTTP 状态码和业务 code 必须解耦，前端靠code字段判断逻辑分支 - 函数第一行加
if w.Header().Get("Content-Type") == "" { ... }，防止 handler 提前设了别的 Content-Type 导致乱码 - 单元测试里传
httptest.NewRecorder()，断言响应 body 是否含"code"和"data"字段，比测中间件容易十倍
真正难的不是写代码，是让所有人记住：每次写 handler，最后那一行必须是 WriteJSON(w, 200, result) 或 WriteJSON(w, 400, nil)。别的路都通向维护地狱。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
