Golang通用API响应封装统一前端返回规范格式-Golang-PHP中文网

统一响应封装必须卡死结构体、调用习惯与错误路径三处边界：code为http状态码（非业务码），message为用户提示字符串，data为可序列化接口类型，timestamp为毫秒时间戳；success/ error函数需显式return且禁止混用abortwitherror。

golang通用api响应封装统一前端返回规范格式

直接用 c.JSON(200, map[string]interface{}{"code": 0, "msg": "ok", "data": user}) 写接口，上线两周后你就会在日志里看到 17 个不同格式的 {"code":200}、{"status":1}、{"success":true,"result":{}} —— 前端同学已经提了三次“能不能别改返回字段名了”。真正能落地的统一封装，不是加个中间件自动包，而是从结构体定义、handler 调用习惯、错误路径三处卡死边界。

Response 结构体字段必须严格按语义拆分

别抄网上“万能 struct”，字段一多就失控。只保留四个字段，少一个难维护，多一个易误用：

Code：必须是 HTTP 状态码（http.StatusOK、http.StatusBadRequest），不是业务码。Nginx 缓存、CDN 判断、浏览器重试全靠它
Message：纯 string 类型，非指针；空值用 ""，不是 nil；生产环境只传用户可见提示，别塞 "pq: duplicate key"
Data：类型为 interface{}，但实际只允许传可序列化类型（User{}、[]Post、map[string]string），且所有字段首字母大写；禁止传 func、chan、未导出字段的 struct
Timestamp：用 time.Now().UnixMilli()，不是 time.Time 或 Format()；前端直接用 Date.now() 对齐，避免时区/解析歧义

分页字段（total、page、page_size）绝对不塞进 Data —— 它是传输元信息，不是业务数据。要么单独提一层字段，要么由前端按 header 或约定路径解析。

Gin 中 Success / Error 函数必须显式 return

最常见 panic 是封装函数里没 return，导致 c.JSON() 后继续执行，触发 http: multiple response.WriteHeader call。正确姿势是收口 + 强制终止：

Success(c *gin.Context, data interface{}) 末尾必须跟 return，且只设 http.StatusOK；不要在里面写 if err != nil { Error() } —— 错误分支该由 handler 自己控制
Error(c *gin.Context, statusCode int, message string) 内部固定用 c.JSON(statusCode, Response{...})，不硬编码 200；statusCode 必须是真实 HTTP 码（400、401、500）
禁用 AbortWithError 这类混合函数 —— c.Abort() 和 c.JSON() 是两件事，混用极易漏响应
所有封装函数签名统一为 func(c *gin.Context)，不接收 *http.Request 或全局 w，避免 goroutine 竞态

示例：

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

func Success(c *gin.Context, data interface{}) {
	c.JSON(http.StatusOK, Response{
		Code:      http.StatusOK,
		Message:   "success",
		Data:      data,
		Timestamp: time.Now().UnixMilli(),
	})
	return
}

为什么不能依赖中间件自动包装返回体

中间件拦截 Write 看似省事，实际踩坑率极高：

handler 里调了 http.Error(w, "", 400)，中间件仍尝试读取空 body 并 marshal，结果返回 {"code":200,"msg":"success","data":null} —— 错误被吞掉
handler panic 了，中间件还没来得及 wrap 就已崩溃，日志里看不到原始 panic 位置和堆栈
多个中间件叠加时，header 可能被重复设置，触发 http: superfluous response.WriteHeader call panic
Swagger 文档和 TypeScript 类型推导失效 —— 中间件返回的 JSON 结构无法静态分析，生成的 client 代码不可靠

真正稳妥的方式是每个 handler 显式构造 Response{} 并调用 c.JSON()，所有分支（成功、校验失败、DB error、not found）都走同一结构体路径。

Code 字段到底该放 HTTP 状态码还是业务码

放业务码（比如 Code: 1001）是高频翻车点。后果很直接：Nginx 把 Code: 1001 + HTTP 200 当作缓存友好响应，把错误接口也缓存了。

正确解法是解耦：

Code 严格对应 HTTP 状态码语义（200、400、404、500）
真要传业务码？加一个独立字段：BusinessCode int `json:"biz_code,omitempty"`，和 Code 并列
前端通过 response.Code 控制 loading / retry / toast 类型，通过 response.BusinessCode 做具体业务跳转或提示