必须定义具名响应结构体并封装success/fail等方法，禁止直接使用c.json()，以确保code/msg/data字段统一、零值语义清晰、错误码类型一致，避免多人协作时字段遗漏、类型错乱和前端兼容问题。
为什么不能直接在 handler 里写 map[string]interface{} 返回？
因为 Gin 的 c.JSON() 本身不校验结构，但业务接口一旦需要字段对齐（比如前端统一读取 code、msg、data），手动拼 map 容易漏字段、类型不一致、错误码写错——尤其多人协作时，code: 200 和 code: 0 混用，data 有时是 nil 有时是空对象，前端反复提 bug。
真正要解决的不是“怎么返回 JSON”，而是“怎么让所有接口遵守同一契约”。所以得从类型定义 + 封装响应函数入手。
定义统一响应结构体并导出关键方法
不要用匿名 struct 或全局 map，必须定义具名结构体，且提供快捷构造函数。重点是：字段名固定、JSON tag 显式声明、零值语义清晰。
-
Code类型用int，避免字符串错误码（如"success"）导致前端 switch 失败 -
Msg永远非空——即使成功也设为"ok"，避免前端res.msg?.length报错 -
Data类型用interface{}，但实际传入时建议传指针或具体类型，避免nil和空 map 混淆 - 提供
Success()、Fail()、AbortWithStatusJSON()等方法，把c.JSON()和状态码绑定
type Response struct {
Code int `json:"code"`
Msg string `json:"msg"`
Data interface{} `json:"data,omitempty"`
}
func Success(data interface{}) Response {
return Response{Code: 200, Msg: "ok", Data: data}
}
func Fail(code int, msg string) Response {
return Response{Code: code, Msg: msg, Data: nil}
}
在 handler 中强制使用封装函数，而非裸调 c.JSON()
Gin 的中间件无法拦截已写出的响应，所以靠约定不如靠约束。最有效的方式是：把 c 包一层，只暴露封装后的响应方法。
- 不要在 handler 里出现
c.JSON(200, ...)，一律用c.Success(...)或c.Fail(400, "...") - 通过
gin.Context的Set()和Get()实现方法注入，或更干脆——写个*ResponseCtx包裹原c，重写响应方法 - 注意
Abort()行为：比如鉴权失败要c.Abort()并立即返回，不能先写Fail()再Abort()，否则可能触发 panic（已写 header 后又写 body）
示例：
func GetUser(c *gin.Context) {
user, err := db.GetUserByID(c.Param("id"))
if err != nil {
c.AbortWithStatusJSON(404, Fail(404, "user not found"))
return
}
c.JSON(200, Success(user)) // ✅ 推荐：Success 已含 code/msg，c.JSON 只管状态码
}
全局错误处理中间件必须复用同一响应结构
Gin 的 c.Error() 只存 error，不自动转 JSON。如果用了 Recovery() 中间件，默认返回 HTML，和你的 JSON 接口完全割裂。
- 自定义 Recovery 中间件，捕获 panic 后调用
Fail(500, "internal error") - 注册
gin.ErrorHandler时，用c.AbortWithStatusJSON()输出，而不是c.Error()+ 单独 recover - 注意：
net/http的标准错误（如 404 Not Found）不会进c.Error()，需靠路由未匹配时的c.AbortWithStatus(404)手动兜底
常见坑：panic("db timeout") 被 Recovery 捕获后，如果只打印日志不返回 JSON，前端收不到 code: 500，只会看到空响应或超时。
统一结构最难的不是定义，而是让所有人——包括新来的同事、临时改接口的测试同学——不绕过封装。上线前最好加个静态检查：grep -r "c\.JSON" 项目目录，删掉所有漏网之鱼。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
