Go语言中用Gin框架返回JSON数据的几种方法

c.JSON()更安全，因自动设置Content-Type、状态码并处理json.Marshal()错误；手动用c.Data()+json.Marshal()易漏header、错status或panic。

直接用 c.JSON()，别手写 json.Marshal() 再塞 c.Data()——Gin 已封装好状态码、Content-Type 和错误 fallback，手动拼容易漏 header、错 status 或 panic。

为什么不能用 c.Data() + json.Marshal() 手动返回

常见的坑，往往就出在这些细节上：响应头没有设置为 Content-Type: application/json; charset=utf-8，结果前端要么解析失败，要么中文直接乱码；HTTP 状态码不管什么情况都固定返回 200，业务层面的错误根本体现不出来；还有一种也很典型，json.Marshal() 一旦报错却没有兜底处理，不是直接 panic，就是干脆返回一个空响应。

• c.Data() 不自动设置任何 header，也不处理序列化 error
• 手动调 json.Marshal() 遇到 func、chan、循环引用会 panic，而 c.JSON() 内部捕获并返回 500
• 忘记写 c.Header("Content-Type", "application/json; charset=utf-8") 是乱码主因，不是结构体 tag 问题

c.JSON() 的参数必须显式传状态码

c.JSON() 没有无状态码的重载，省略会编译报错。常见误写是 c.JSON(data)（缺 status）或 return c.JSON(200, data)（误以为它返回值）——它不 return，只写响应并标记已提交。

• 正确写法：c.JSON(http.StatusOK, data) 或 c.JSON(200, gin.H{"msg": "ok"})
• status 必须是 int，不能是 string；data 可以是 struct、map、slice，但不能含非 JSON 可序列化字段（如函数、指针未解引用）
• 若想简化，封装 SuccessJSON(c *gin.Context, data any)，内部固定调 c.JSON(200, data)

返回结构体切片时字段丢失？先看导出性和 tag

现象：返回 []User，结果 JSON 里没有 id 字段。根本原因不是类型问题，而是 Go 的 JSON 序列化只处理首字母大写的导出字段，且依赖 json: tag 控制键名。

• 错误定义：type User struct { id int `json:"id"` } → id 小写，非导出，完全被忽略
• 正确写法：ID int64 `json:"id"`（字段名大写 + 显式 tag）
• 避免滥用 json:",string"：对数字字段加这个 tag 会让前端收到字符串而非数字，解析失败
• 验证方式：c.JSON(200, []User{{ID: 1, Name: "a"}})，用 curl -i 看响应头是否含 charset=utf-8

统一响应格式必须避开 defer 和重复调用

封装 response.Success() 或 response.Fail400() 很必要，但极易踩坑：在 defer 里调用会 panic，不 return 会导致后续代码继续执行并可能再次调 c.JSON()。

• defer func() { response.Success(c, data) }() → 响应头已写入，再写触发 write on flushed body
• 每个响应函数末尾必须加 return，否则 handler 剩余逻辑仍运行
• 禁止在同一个 handler 里多次调 c.JSON()，哪怕用 c.Abort() 也救不了——c.JSON() 内部已标记写入完成
• 全局错误中间件要放在 router.Use() 链最后，靠检查 c.Errors 触发 c.AbortWithStatusJSON()，而不是依赖 c.Error() 自动响应

最易被忽略的是：结构体字段导出性（首字母大小写）和 c.JSON() 调用时机。前者决定字段能否进 JSON，后者决定服务会不会 panic。两者不解决，光调函数没用。