HTTP状态码和业务状态码必须严格分离：前者为标准三位数（如200、401），由HTTP协议定义，用于网关、监控等基础设施识别请求处理结果；后者为自定义整数（如10001、40001），置于JSON body的code字段中，供前端做业务逻辑判断。
HTTP 状态码和业务状态码必须分开用，混着写迟早出事——前端靠 code 字段做业务跳转或提示，网关和监控只认 HTTP 状态码（比如 401 触发重定向、500 触发告警），两者语义不同、接收方不同，强行塞进同一个字段会破坏契约。
为什么不能把业务 code 当 HTTP 状态码传给 c.JSON()
常见错误是这样写：
func handler(c *gin.Context) {
c.JSON(10001, gin.H{"msg": "参数错误", "data": nil})
}
这会导致 HTTP 响应头里真的发出 HTTP/1.1 10001 Unknown，违反 RFC 7231，多数代理、CDN、浏览器会直接拒绝解析或降级处理。Go 的 net/http 库内部会对非标准状态码打日志甚至 panic（取决于版本）。
正确做法是：HTTP 状态码只用标准值（http.StatusOK、http.StatusBadRequest 等），业务状态码只出现在 JSON body 的 code 字段里。
- 参数校验失败 →
c.JSON(http.StatusBadRequest, Response{Code: 10001, Message: "xxx"}) - 未登录 →
c.JSON(http.StatusUnauthorized, Response{Code: 40001, Message: "请先登录"}) - 数据库查不到 →
c.JSON(http.StatusOK, Response{Code: 20001, Message: "用户不存在", Data: nil})（注意：这是成功请求，只是业务上没找到）
c.Status() 和 c.JSON() 的调用顺序陷阱
有人想先设状态码再塞数据，写成：
c.Status(http.StatusBadRequest)
c.JSON(http.StatusBadRequest, Response{...})
这会触发 http: multiple response.WriteHeader calls panic。因为 c.JSON() 内部已经调用了 WriteHeader，重复调用不被允许。
只需一步：c.JSON() 同时完成状态码写入和 body 编码，c.Status() 仅用于不需要 body 的场景（如 302 跳转、204 No Content）。
- 带 body 的响应：只用
c.JSON(code, data)，code是 HTTP 状态码 - 纯状态码无 body：用
c.Status(code)+c.Abort()阻止后续逻辑 - 需要自定义 header 且无 body：用
c.Writer.WriteHeader(code)，但要自己确保没被其他方法提前触发
封装 Success() 和 Fail() 时怎么选 HTTP 状态码
封装函数里最容易错的是把“业务失败”和“HTTP 失败”等同。比如用户余额不足，这不是客户端请求格式错，也不是服务不可用，而是正常业务流中的一个分支结果，HTTP 层仍是成功的：
func Fail(c *gin.Context, httpCode int, bizCode int, msg string) {
c.JSON(httpCode, Response{
Code: bizCode,
Message: msg,
Data: nil,
Timestamp: time.Now().UnixMilli(),
})
}
调用示例：
- 参数缺失 →
Fail(c, http.StatusBadRequest, 10001, "手机号不能为空") - token 过期 →
Fail(c, http.StatusUnauthorized, 40002, "登录已失效") - 下单失败（库存不足）→
Fail(c, http.StatusOK, 30003, "库存不足")（注意第一个参数是http.StatusOK）
关键点：HTTP 状态码反映的是「这次 HTTP 请求是否被服务器正常接收并处理」，不是「业务逻辑是否达成预期结果」。
中间件里统一注入 code 字段容易漏掉的细节
如果用中间件统一加 code、message、timestamp，要注意三件事：
- 中间件只能在
c.Next()之后读取c.Writer.Size()判断是否已写 body，但无法修改已写出的内容 —— 所以统一包装必须在 handler 内部完成，中间件只适合做日志、鉴权、超时等前置动作 - 别在中间件里调用
c.JSON()，否则 handler 里的c.JSON()会 panic - 如果用了
recovery中间件捕获 panic，它返回的默认错误是500+ 堆栈，需重写该中间件，让它也走你的Fail(c, http.StatusInternalServerError, 50000, ...)流程，避免暴露敏感信息
真正安全的统一出口，只有一个：所有 handler 必须通过你封装的 Success()/Fail() 函数返回，且每个函数末尾强制 return。
