真正靠谱的统一封装需从结构体定义、函数封装、调用习惯三处卡死边界：Code（HTTP状态码）、Message（非nil字符串提示）、Data（可序列化interface{}）、Timestamp（UnixMilli()），分页等元信息不得混入Data；Success/ Error函数须显式return并避免混用Abort与JSON；禁用自动中间件包装，强制每个handler显式调用，确保可控可测。
直接在 handler 里用 c.JSON(200, map[string]interface{}{"code": 0, "msg": "ok", "data": user}) 看似快，但三个月后你会被自己写的 47 个接口格式搞崩溃。真正靠谱的统一封装，不是加一层中间件自动包，而是从结构体定义、函数封装、调用习惯三处同时卡死边界。
Response 结构体字段怎么定才不翻车
别抄网上“通用万能 struct”，字段语义混乱是后续所有问题的源头。核心就四字段，少一个都难维护，多一个都容易误用：
-
Code：必须是 HTTP 状态码（200、404、500），不是业务码。Nginx、CDN、浏览器缓存全靠它判断响应性质 -
Message：纯字符串，非指针；空值用""，不是nil；生产环境只给用户看的提示，别塞sql: no rows这种 -
Data：类型为interface{}，但实际传入必须是可序列化类型（struct、map、[]T），且字段首字母大写；禁止传func、chan、未导出字段结构体 -
Timestamp：用time.Now().UnixMilli()，不用Format，避免 GC 和时区歧义
分页信息（total、page、page_size）绝对不塞进 Data。它不属于业务数据，是传输元信息，该单独字段或由前端按约定解析 header。
Gin 框架里 Success / Error 函数怎么封装才不 panic
最常见错误是封装函数里没 return，导致 c.JSON 调用后继续执行，触发 http: multiple response.WriteHeader calls panic。正确姿势是把逻辑收口、强制终止：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- Success 函数末尾必须跟
return，且只设http.StatusOK；不要在函数里塞if err != nil { Error(...) }，错误路径应由 handler 自己控制分支 - Error 函数接受
statusCode int（如400）和message string，内部固定用c.JSON(statusCode, Response{...})，不硬编码200 - 别写
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
}
为什么不能用中间件自动包装响应
看似省事，实则埋雷。中间件无法感知 handler 是否已写响应、是否已调用 http.Error、是否 panic 后被 recovery 捕获过。典型翻车场景：
- handler 里写了
c.String(400, "bad request")，中间件再套一层 JSON，结果返回{"code":200,"msg":"success","data":"bad request"} - 数据库查询失败，handler 调用
http.Error(w, "db down", 503)，中间件仍试图 encode struct，panic 报write on closed body - 上传接口返回
204 No Content，中间件强行塞Data: null，违反 RFC
真正的“统一”来自约束，不是自动化。每个 handler 显式调用 Success 或 Error，才是可控、可测、可 debug 的路径。
Content-Type 和 json.Marshal 错误怎么防
裸用 json.NewEncoder(w).Encode() 容易忽略两件事：头没设、错误没判。一旦 struct 里有 func 字段或未导出字段，Encode 直接 panic，服务静默挂掉。
- 必须在写之前调用
w.Header().Set("Content-Type", "application/json; charset=utf-8")，某些旧版 Axios 依赖这个头识别 JSON -
json.Marshal返回error，不能忽略；json.NewEncoder(w).Encode()内部也会 panic，所以推荐先data, err := json.Marshal(resp)，err 不为 nil 就log.Error+http.Error(w, ..., 500) - 别信“我这 struct 肯定能序列化”，加个单元测试，用
reflect扫描所有字段是否可导出、是否含func/unsafe.Pointer
复杂点在于：timestamp 字段要不要加 omitempty？不要。它是诊断关键字段，空值也得传，否则排查时连响应时间都对不上。
