Beego 中统一返回 JSON 需结合 ServeJSON()、首字母大写+json tag 的结构体字段、共用 Response 结构体及 BaseController 封装 SuccessJson/ErrorJson 并调用 StopRun()。

ServeJSON() 是 Beego 返回 JSON 的标准方式,但要实现「统一格式」,不能只靠它——必须配合结构体设计、字段导出规则和控制器基类封装。否则每次都要手写 Data["json"] = map[string]interface{},很快就会失控。
结构体字段必须首字母大写 + json tag
Beego 序列化时用的是 Go 原生 json.Marshal,它只会导出首字母大写的字段。小写字段(如 name string)直接被忽略,返回空对象或报错。
- ✅ 正确写法:
Name string `json:"name"` - ❌ 错误写法:
name string `json:"name"`(字段不导出,JSON 里消失) - 字段值为零值(
""、0、nil)时,加omitempty可自动剔除:Data interface{} `json:"data,omitempty"` - 不要用
map[string]interface{}当主力响应类型——类型不安全,IDE 无法跳转,前端也难推断结构
定义统一响应结构体,别每个接口都 new 一个
重复定义 SuccessResponse、UploadResp、ListResp 是典型反模式。所有接口共用一个 Response 结构体,靠字段是否为空控制输出内容。
type Response struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
Timestamp int64 `json:"timestamp"`
}
-
Code用业务码(如200、4001),不是 HTTP 状态码 -
Data类型是interface{},但调用时传具体 struct 指针,例如&user或users,避免运行时 panic -
Timestamp写死time.Now().Unix(),比字符串时间省带宽、无时区歧义 - 不用
Success bool字段——前端判断res.code === 200就够了
在 BaseController 里封装 SuccessJson / ErrorJson
所有 Controller 继承自 BaseController,把 JSON 构造和发送逻辑收口,避免每个方法里重复写 this.Data["json"] = ...; this.ServeJSON()。
将包含oralBroadcastingList、materialList、bgmInfo等字段的JSON视频素材转换为剪映API可用的自然语言描述,用于生成视频制作指令,包括素材匹配、时间轴计算、字幕同步、特殊效果处理等。
- 必须调用
this.StopRun(),否则后续代码仍会执行,可能造成重复写响应或 panic - 错误响应也要设
Data字段(哪怕为nil),保持结构一致,前端不用做分支判断 - 状态码通过
this.Ctx.ResponseWriter.WriteHeader(500)手动设,ServeJSON()默认发 200,不覆盖它 - 示例:
func (c *BaseController) ErrorJson(code int, msg string, data interface{}) { c.Ctx.ResponseWriter.WriteHeader(code); c.Data["json"] = Response{Code: code, Message: msg, Data: data, Timestamp: time.Now().Unix()}; c.ServeJSON(); c.StopRun() }
注意 ServeJSON 的默认行为和陷阱
ServeJSON() 看似简单,但几个默认行为容易踩坑:
立即学习“go语言免费学习笔记(深入)”;
- 它默认设置
Content-Type: application/json; charset=utf-8,但如果你之前手动写了c.Ctx.ResponseWriter.Header().Set("Content-Type", "..."),可能冲突 - 它不会自动处理
error——如果json.Marshal失败(比如结构体含不可序列化的字段),会 panic,不返回任何响应 - 不支持流式响应或大文件 JSON;数据量大时建议改用
json.NewEncoder(c.Ctx.ResponseWriter).Encode(...)并手动设 header - 调试时想看原始 JSON 内容?加一行
beego.Debug("resp:", res),但别打fmt.Printf("%+v"),因为interface{}里的 struct 指针会打印地址
code 含义一致、data 结构可预测、错误时字段不突然消失——这得靠结构体约定和基类强制,而不是靠某次 ServeJSON() 调用。

















