Go结构体字段需大写且加json tag才能被c.JSON序列化；Data字段须传可序列化类型；Code应为int以保证前后端严格相等；Success函数必须return终止执行流。
为什么直接用 c.JSON 返回结构体切片会丢字段
常见现象是响应里看不到 ID 或 CreatedAt 字段，只显示部分小写字母开头的字段（如 name）。这不是 Gin 的问题，而是 Go 的 encoding/json 序列化规则在起作用：只有首字母大写的导出字段才能被序列化，且必须显式带 json tag 控制键名。小写字段（如 id int64）会被完全忽略。
解决办法很简单：
- 结构体字段名必须大写（
ID、Name），否则无法导出 - 每个字段都加
json:"xxx"tag，比如ID int64 `json:"id"` - 避免混用
db、form等其他 tag 覆盖json行为（除非你明确知道影响） - 切片本身不用额外处理：
c.JSON(http.StatusOK, []MyStruct{...})是完全合法的
Response 结构体中 Data 字段为什么不能裸传 interface{}
很多人定义 Data interface{} 后，直接传 func() {} 或未初始化的 map[string]any，结果运行时报 panic: json: unsupported type: func()。这是因为 encoding/json 在运行时才检查类型合法性，而 interface{} 不做任何约束。
实际使用时要守住两条线：
-
Data字段接收值必须是可序列化的具体类型：结构体指针、map[string]any、[]any、基础类型（string、int等） - 禁止传函数、channel、unsafe.Pointer、未导出 struct 实例等不可序列化类型
- 如果不确定来源，先做类型断言或用
json.Marshal预检：_, err := json.Marshal(data) - 别依赖
omitempty来“掩盖”空值问题——空 map 和 nil map 行为不同，前端解析可能出错
为什么 Code 必须是 int 而不是 string
前端同学反馈 “code === '0' 判断总失败”，根源就是后端用了 Code string。JavaScript 的 === 严格比较类型，'0' !== 0，导致所有状态码判断失效。
更深层的问题是语义混乱：code 是状态标识符，不是描述性文本。统一用 int 能带来确定性：
- 约定
0成功，非零为错误码（如1001参数错误、2001权限不足） - Go 中
int可直接参与 switch/case，无类型转换开销 - 数据库存码、日志打点、监控告警都基于整数，字符串反而增加解析成本
- 千万别加
json:",string"tag 强制转字符串——这是前端兼容性灾难的源头
封装 Success 函数时最容易漏掉的 return
现象是 handler 执行完 response.Success(c, data) 还继续往下跑，接着又调一次 c.JSON，触发 http: multiple response.WriteHeader calls panic。
根本原因是封装函数内部没终止执行流。正确写法必须带 return：
func Success(c *gin.Context, data any) {
c.JSON(http.StatusOK, Response{
Code: 0,
Message: "success",
Data: data,
Timestamp: time.Now().UnixMilli(),
})
return // ← 这行不能少
}
还要注意两个边界：
- 别在
defer里调用任何响应函数——响应头已 flush，再写就 panic - 中间件中若已调用
c.Abort()（如鉴权失败），后续 handler 不会执行；但你自己写的Fail函数也得return，否则可能干扰 recovery 中间件逻辑 - 如果 handler 里有 DB 查询，
sql.ErrNoRows不能原样透传，必须转成业务语义（如"用户不存在"），否则前端无法友好提示
真正难的不是写对一个 Response 结构，而是让整个团队在所有 handler 里一致地用对它——字段大小写、tag 写法、return 位置、错误码映射，每一处松动都会在联调时暴露出来。
