统一响应封装必须卡死结构体、调用习惯与错误路径三处边界：Code为HTTP状态码（非业务码），Message为用户提示字符串，Data为可序列化接口类型，Timestamp为毫秒时间戳；Success/ Error函数需显式return且禁止混用AbortWithError。
直接用 c.JSON(200, map[string]interface{}{"code": 0, "msg": "ok", "data": user}) 写接口，上线两周后你就会在日志里看到 17 个不同格式的 {"code":200}、{"status":1}、{"success":true,"result":{}} —— 前端同学已经提了三次“能不能别改返回字段名了”。真正能落地的统一封装，不是加个中间件自动包，而是从结构体定义、handler 调用习惯、错误路径三处卡死边界。
Response 结构体字段必须严格按语义拆分
别抄网上“万能 struct”，字段一多就失控。只保留四个字段，少一个难维护，多一个易误用：
-
Code：必须是 HTTP 状态码（http.StatusOK、http.StatusBadRequest），不是业务码。Nginx 缓存、CDN 判断、浏览器重试全靠它 -
Message：纯string类型，非指针；空值用""，不是nil；生产环境只传用户可见提示，别塞"pq: duplicate key" -
Data：类型为interface{}，但实际只允许传可序列化类型（User{}、[]Post、map[string]string），且所有字段首字母大写；禁止传func、chan、未导出字段的 struct -
Timestamp：用time.Now().UnixMilli()，不是time.Time或Format()；前端直接用Date.now()对齐，避免时区/解析歧义
分页字段（total、page、page_size）绝对不塞进 Data —— 它是传输元信息，不是业务数据。要么单独提一层字段，要么由前端按 header 或约定路径解析。
Gin 中 Success / Error 函数必须显式 return
最常见 panic 是封装函数里没 return，导致 c.JSON() 后继续执行，触发 http: multiple response.WriteHeader call。正确姿势是收口 + 强制终止：
立即学习“go语言免费学习笔记（深入）”；
-
Success(c *gin.Context, data interface{})末尾必须跟return，且只设http.StatusOK；不要在里面写if err != nil { Error() }—— 错误分支该由 handler 自己控制 -
Error(c *gin.Context, statusCode int, message string)内部固定用c.JSON(statusCode, Response{...})，不硬编码200；statusCode必须是真实 HTTP 码（400、401、500） - 禁用
AbortWithError这类混合函数 ——c.Abort()和c.JSON()是两件事，混用极易漏响应 - 所有封装函数签名统一为
func(c *gin.Context)，不接收*http.Request或全局w，避免 goroutine 竞态
示例：
func Success(c *gin.Context, data interface{}) {
c.JSON(http.StatusOK, Response{
Code: http.StatusOK,
Message: "success",
Data: data,
Timestamp: time.Now().UnixMilli(),
})
return
}
为什么不能依赖中间件自动包装返回体
中间件拦截 Write 看似省事，实际踩坑率极高：
- handler 里调了
http.Error(w, "", 400)，中间件仍尝试读取空 body 并 marshal，结果返回{"code":200,"msg":"success","data":null}—— 错误被吞掉 - handler panic 了，中间件还没来得及 wrap 就已崩溃，日志里看不到原始 panic 位置和堆栈
- 多个中间件叠加时，header 可能被重复设置，触发
http: superfluous response.WriteHeader callpanic - Swagger 文档和 TypeScript 类型推导失效 —— 中间件返回的 JSON 结构无法静态分析，生成的 client 代码不可靠
真正稳妥的方式是每个 handler 显式构造 Response{} 并调用 c.JSON()，所有分支（成功、校验失败、DB error、not found）都走同一结构体路径。
Code 字段到底该放 HTTP 状态码还是业务码
放业务码（比如 Code: 1001）是高频翻车点。后果很直接：Nginx 把 Code: 1001 + HTTP 200 当作缓存友好响应，把错误接口也缓存了。
正确解法是解耦：
-
Code严格对应 HTTP 状态码语义（200、400、404、500） - 真要传业务码？加一个独立字段：
BusinessCode int `json:"biz_code,omitempty"`，和Code并列 - 前端通过
response.Code控制 loading / retry / toast 类型，通过response.BusinessCode做具体业务跳转或提示
复杂点不在结构设计，而在每个 handler 是否真的坚持只走一条 c.JSON() 路径 —— 没人会检查第 48 个接口有没有偷偷用 map[string]interface{}，直到前端报“这个接口的 data 字段突然变成 result 了”。
