response —— 统一响应体:成功 / 失败 / 分页三种形状
后端所有接口返同一种形状,前端只写一套解析。
{
"code": 0,
"data": { },
"message": "ok",
"timestamp": 1730000000000,
"trace_id": "abc123"
}
功能
response 解决三件事:
- 统一响应体(
Response)——code/data/message/timestamp/trace_id。 - 三种成功形状 + 三种失败写法 —— 见「使用方法」。
- TraceID 回传 —— 响应体里的
trace_id与日志里的同一个 id, 用户截图里一个 id 就能定位到那条日志。
不解决:错误码本身(在 errcode)、分页参数解析(在 pagination)、鉴权。
配置
本包无 yaml 配置 —— 响应体形状是跨模块契约,写死在代码里。
使用方法
三种成功
response.OK(c) // 无数据
response.OKWithData(c, map[string]any{"id": 8801}) // 带数据
response.OKWithMessage(c, data, "共 3 条") // 带数据 + 自定义文案
分页
response.Page(c, list, total, page, size)
// data = {"list": [...], "total": 137, "page": 2, "size": 20}
三种失败
response.Fail(c, errcode.InvalidParam, "手机号不合法")
response.FailWithData(c, errcode.InvalidParam, "手机号不合法",
map[string]any{"field": "phone", "value": "1380000"})
response.FailError(c, err) // 从 error 里抽 code + msg
业务代码里推荐直接用 handler.BaseHandler 的封装(OK / Fail / FailCode / Page),
它会 errors.As 解包 *errcode.Error 并自动带上 Detail。
TraceID
tid := response.TraceIDFrom(c) // 优先 X-Trace-Id,其次 X-Request-Id,都没有返 ""
两个 header 常量:response.HeaderTraceID(X-Trace-Id)、
response.HeaderRequestID(X-Request-Id)。写入方是 middleware/trace.go
与 middleware/otel.go。
不起 HTTP 服务就能看输出
c := app.NewContext(0)
response.OKWithData(c, map[string]any{"id": 8801})
fmt.Println(string(c.Response.Body()))
完整示例见 examples/response/main.go。
注意事项
- ⚠️ HTTP 状态码与 body 里的
code是两回事。HTTP 说"请求成不成功",code说"为什么"。网关 / 监控看前者,前端分支看后者。 失败响应的 HTTP 状态由errcode.HTTPStatus(code)推导 —— 不要在 handler 里手写c.JSON(400, …),那会让同一类错误在不同接口上状态码不一致。 - ⚠️
FailError的 message 是err.Error(),不是纯文案。*errcode.Error.Error()渲染成"[40003] 参数无效"—— 带方括号和数字前缀。 前端会原样弹出来。要干净文案,用handler.BaseHandler.Fail(它解包后取e.Message),或自己errcode.New(code, msg)。 - ⚠️
FailError会丢Detail—— 它只传 code + msg,不带字段级明细。 校验错误要用FailWithData/BaseHandler.Fail。 - ⚠️
Data字段带omitempty—— 成功且无数据时,JSON 里没有data键 (不是"data": null)。前端取res.data.data拿到的是undefined, 写res.data.data.length会炸。前端要么用可选链,要么后端该给数据就给数据。 - ⚠️
timestamp是毫秒(time.Now().UnixMilli()),不是秒。 注释与示例里出现过的1730000000那种 10 位数是秒 —— 传前端算时间差会差 1000 倍。 - ⚠️
trace_id也是omitempty——TraceIDFrom拿不到就是空串, 于是响应体里整个trace_id键消失。它依赖middleware/trace.go/middleware/otel.go已挂载并写回了请求头;自己 new 一个 ctx 不带 header 时必然没有。 - ⚠️
TraceIDFrom读的是请求头,不是响应头。otel.go在收尾时才把X-Trace-Id写进响应头 —— 响应体里的trace_id取的是请求进来时就有的那个值。 - ⚠️ HTTP 状态码映射只存在于
errcode.HTTPStatus一处。response包原来有一份私有拷贝,cmd/gen-errcode-doc里还有第三份,三份各错各的 (413 桶、501/503/504 都对不上)。M98 已合并成一份 —— 新增码只改errcode一处。 - ⚠️
time.go里的nowMilli()是零调用方的死函数(与Now()重复)。 改时间戳口径时改Now(),别改它。
相关
- 源码:
internal/pkg/response/(response.go响应体 /time.go时间戳) - 可运行示例:
examples/response/main.go——go run ./examples/response - 错误码与 HTTP 映射 → errcode
- 分页参数 → pagination