因为c.JSON()是响应即发、不可拦截的底层方法，一旦调用就立刻写入HTTP body并标记状态已发送，导致后续中间件无法获取或修改响应内容，且重复调用会触发“response.WriteHeader called twice”错误。
为什么 Gin 的 c.JSON() 不能直接用作统一返回？
因为 c.JSON() 是响应即发、不可拦截的底层方法，一旦调用就立刻写入 HTTP body 并标记状态已发送。如果你在中间件或封装函数里提前调用它，后续逻辑（比如日志、错误处理、鉴权拦截）就再也拿不到响应内容，甚至会触发 http: response.WriteHeader called twice 错误。
真正能统一控制 JSON 返回的，是「不直接调用 c.JSON()」，而是把数据先存起来，等所有处理完成再统一输出。
- 推荐方式：定义一个结构体（如
Response），所有 handler 返回该结构体或 error，由统一出口（比如自定义c.Render()或中间件后置钩子）调用c.JSON() - 避免方式：在中间件里看到错误就直接
c.JSON(400, ...)—— 这会让后续 handler 无法执行，也破坏了责任分离 - 注意：
c.Abort()必须配合c.Status()或c.JSON()使用，否则客户端收不到任何响应
Gin 中实现统一 JSON 返回的两种可靠路径
路径一：用 c.Set() + 自定义 Render 方法（轻量、可控）
路径二：用中间件 + c.Next() 后检查 c.Writer 状态（适合已有项目渐进改造）
- 路径一示例：在 handler 里写
c.Set("response", Response{Code: 0, Data: user})，然后在全局中间件末尾读取并调用c.JSON(200, resp) - 路径二关键点：Gin 的
ResponseWriter不支持重写已写内容，所以必须在c.Next()前记录预期状态，c.Next()后判断是否已写 —— 实际更推荐路径一 - 别用
recovery中间件做统一返回：它只捕获 panic，不处理业务错误，且恢复后无法修改已发送的响应
Response 结构体设计要注意什么？
字段命名和类型直接影响前端解析成本和后端维护难度。不要照搬其他框架的 success/message 模式，Gin 场景下建议：
- 必含
code（int）：HTTP 状态码仅反映传输层，业务码（如 1001=用户不存在）需单独字段 - 推荐
msg（string）：不是所有场景都需要提示语，设为空字符串比设为"ok"更灵活 - 数据字段用
data（interface{}）：避免为每种返回类型定义 struct，但注意 nil 切片序列化为null而非[]，必要时用指针或包装类型 - 避免嵌套
result字段：前端解构多一层，徒增沟通成本；直接平铺code/msg/data即可
如何让错误也走统一 JSON 返回？
核心是把错误转换成 Response，而不是靠 panic 或 log.Fatal。Gin 本身不提供 error-to-response 自动映射，得自己串起来。
- 定义业务错误类型，如
type BizError struct { Code int; Msg string }，实现Error()方法 - 在 handler 里用
if err != nil { c.Set("response", Response{Code: err.(*BizError).Code, Msg: err.Error(), Data: nil}); return } - 不要用
errors.New()直接返回：它没有业务码，无法区分 400/401/500 场景；统一用自定义错误类型 - HTTP 标准错误（如 404）仍应调用
c.JSON(404, Response{Code: 404, Msg: "not found"})，保持语义清晰
统一返回不是加个中间件就完事，关键是把“构造响应”这个动作从各个 handler 里收口，否则永远有漏网之鱼。最容易被忽略的是异步 goroutine 里的错误 —— 它们不在 Gin 请求生命周期内，c.Set() 无效，必须显式传参或用 channel 汇总。
