Beego中Response结构体必须严格限定为Code（HTTP状态码）、Msg（非指针string，空值为""）、Data（可序列化interface{}，字段首字母大写）、Timestamp（time.Now().UnixMilli()），禁用业务码混入Code，分页字段不得塞入Data。
Beego 中 Response 结构体字段怎么定才不翻车
Beego 没有 Gin 那种默认的 c.JSON() 封装习惯，但也不意味着可以随意返回 map[string]interface{}。结构体字段一旦混乱，Swagger 文档生成、前端 TypeScript 类型推导、错误码统一治理就全崩了。
必须只保留四个核心字段，且语义严格对齐 HTTP 协议层与业务层：
-
Code：HTTP 状态码（200、401、500），不是业务码；CDN 缓存、浏览器重试逻辑都依赖它 -
Msg：非指针string，空值用""；生产环境禁止出现sql: no rows这类底层错误 -
Data：类型为interface{}，但实际只接受可 JSON 序列化的值（struct、map[string]any、[]T），且所有字段首字母大写 -
Timestamp：固定用time.Now().UnixMilli()，不转字符串，避免时区和 GC 压力
分页字段（Total、Page、PageSize）绝对不能塞进 Data —— 它是传输元信息，不是业务数据。要么提成顶层字段，要么由前端从 Header 解析（如 X-Total-Count）。
Beego Controller 里 Success / Error 函数为什么必须显式 return
Beego 的 this.ServeJSON() 不会自动终止执行，这是和 Gin c.JSON() + return 组合最本质的区别。漏写 return 就会触发 http: multiple response.WriteHeader call panic。
正确封装示例（放在 common/app/response.go）：
func Success(this *context.Context, data interface{}) {
this.Data["json"] = Response{
Code: http.StatusOK,
Msg: "success",
Data: data,
Timestamp: time.Now().UnixMilli(),
}
this.ServeJSON()
return // 必须有！否则后续代码继续执行
}
func Error(this *context.Context, statusCode int, msg string) {
this.Data["json"] = Response{
Code: statusCode,
Msg: msg,
Data: nil,
Timestamp: time.Now().UnixMilli(),
}
this.Ctx.Output.SetStatus(statusCode)
this.ServeJSON()
return // 同样必须
}
常见错误：
- 在
Error()里调用this.Abort()后没跟ServeJSON()，导致响应为空 - 把
Success()当作“打印日志”用，忘记return，结果接口返回两遍 JSON 或直接 panic - 混用
this.Ctx.Output.Body([]byte(...))和ServeJSON()，造成 header 冲突
Beego 为什么不能靠中间件自动包装响应
Beego 的中间件（BeforeExec、FinishRouter）无法可靠判断 controller 是否已写响应、是否已 panic、是否调用了 this.Abort()。强行加一层“统一包装中间件”，会导致：
- 成功路径返回
{"code":200,"msg":"success","data":{}}，错误路径却走this.Ctx.Output.SetStatus(400)+ 原始 panic 错误文本，结构撕裂 - Swagger 文档里
responses只能推导出200分支，400/500分支全丢 - 前端 SDK 自动类型映射失效，因为
Response结构在不同状态码下不一致
Beego 的路由和 controller 生命周期比 Gin 更“显式”，反而更适合手动控制。每个 handler 显式调用 Success() 或 Error()，多写一行，换来的是可测、可文档化、可调试。
Beego 里业务码和 HTTP 状态码怎么解耦
很多团队把业务码（比如 1001 表示“用户不存在”）硬塞进 Code 字段，再让前端 switch 判断 —— 这会让 Nginx 缓存策略、CDN 回源逻辑、浏览器离线 fallback 全部失效。
正确做法是双字段并存：
-
Code：始终是 HTTP 状态码（200、404、400） - 新增
BusinessCode字段（int类型），专门放1001、2002这类业务标识
这样前端可以用 HTTP 状态码做通用处理（如 4xx 弹登录框、5xx 上报监控），再用 BusinessCode 做具体业务分支（如 BusinessCode == 1001 提示“账号未注册”）。
注意：BusinessCode 不参与 HTTP 协议层流转，不要试图用它控制缓存或重定向 —— 那是 Code 的事。
