Beego框架API响应格式标准化封装方法-Golang-PHP中文网

beego中response结构体必须严格限定为code（http状态码）、msg（非指针string，空值为""）、data（可序列化interface{}，字段首字母大写）、timestamp（time.now().unixmilli()），禁用业务码混入code，分页字段不得塞入data。

beego框架api响应格式标准化封装方法

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 // 同样必须
}

常见错误：

Beego框架 2.3.5

Beego框架 2.3.5 版本源码包下载，适合关注表单空值、函数注释名和 nil 返回值修复的 Go Web 开发者。

下载

在 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()，多写一行，换来的是可测、可文档化、可调试。