统一返回结构必须定义在presentation层,如handler中用c.JSON封装,code定义为常量,响应体结构(如APIResponse)不得侵入domain或usecase;HTTP状态码与业务code需分层,禁止中间件全局包装响应。

统一返回结构必须定义在 presentation 层,不能放在 domain 或 usecase
统一返回格式(如 { "code": 0, "message": "success", "data": {} })本质是 HTTP 协议层的胶水逻辑,和业务无关。一旦把它塞进 domain 层结构体或 usecase 返回值里,就等于把响应包装污染进了核心逻辑——比如 User 实体开始带 Code 字段,后续换 GraphQL 或 gRPC 就得重写整个 domain。
正确做法是在 handler 或紧邻 handler 的 adapter 文件里做封装,例如:
func (h *UserHandler) GetUser(c echo.Context) error {
id := c.Param("id")
user, err := h.usecase.GetUserByID(id)
if err != nil {
return c.JSON(http.StatusOK, map[string]interface{}{
"code": 4001,
"message": "user not found",
"data": nil,
})
}
return c.JSON(http.StatusOK, map[string]interface{}{
"code": 0,
"message": "success",
"data": user,
})
}
- 所有
code值应定义为常量(如const ErrUserNotFound = 4001),避免 magic number - 不要用 struct 做统一返回体并导出到 domain —— 它只属于 HTTP 层,命名建议带
HTTP或API前缀,如APIResponse - 如果项目有多个 handler,可抽成私有函数:
renderSuccess(c, data)和renderError(c, code, msg),但别做成跨层复用的“通用响应工具包”
c.JSON() 之前必须确保结构体字段可导出且有 json tag
常见现象是返回空 data: {} 或字段全丢,根本原因不是逻辑错,而是 Go 的序列化规则被忽略。
echo.Context.JSON() 底层调用 json.Marshal,它只会序列化首字母大写的导出字段,且依赖 json:"xxx" tag 控制 key 名。小写字段(如 name string)永远不出现。
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 错误示范:
type User struct { Name string `json:"name"`; age int }→age不会出现在 JSON 中 - 正确写法:
Age int `json:"age"`,且所有字段都需显式 tag,否则默认用大驼峰转 kebab-case(UserID→user_i_d) - 别依赖
json:",omitempty"隐藏零值字段——前端可能需要明确知道字段存在但为空,建议由业务逻辑决定是否写入
中间件里统一包装响应会破坏流式响应和文件下载
有人想“一劳永逸”,在中间件里拦截所有 c.Response().Write() 并套一层 {"code":0,"data":...}。这在绝大多数场景下是危险的。
因为 c.JSON()、c.File()、c.Stream() 等方法已直接写入 response body,中间件无法安全地二次包装——要么重复写入报错,要么覆盖原始内容,尤其影响 Excel 下载、图片流、SSE 等。
- 唯一安全的统一包装点是:每个 handler 显式调用
c.JSON(),且只在这里封装 - 若真要全局控制,只能用
e.HTTPErrorHandler处理错误路径,但注意它不接管正常响应 - 不要试图用
io.MultiWriter包裹ResponseWriter来劫持输出——Echo 的 writer 实现含 buffer 和状态管理,手动包裹极易触发http: superfluous response.WriteHeader
错误码分层设计:HTTP 状态码 ≠ 业务 code
前端需要区分“服务不可达”(503)、“参数错”(400)、“未登录”(401)和“余额不足”(200 + code=2003)。这两层必须分开,不能混用。
典型错误是把所有业务错误都返回 http.StatusOK,导致前端无法用 HTTP 状态做自动重试或鉴权跳转;或者反过来,用 http.StatusForbidden 表示“订单已取消”,违反语义。
- HTTP 状态码表达协议/传输层语义:
4xx是客户端问题,5xx是服务端问题,2xx表示请求已被接收并处理(无论业务成败) - 业务 code 放在响应体的
code字段里,用于前端路由判断或 toast 提示 - 例如:登录失败 →
http.StatusUnauthorized+{"code": 1002, "message": "invalid credentials"};支付超时 →http.StatusOK+{"code": 2005, "message": "payment timeout"}
renderJSON 函数,而是守住边界:让 HTTP 层只负责怎么传,不让它决定业务怎么走。一旦在 domain 里看到 APIResponse,或者 handler 里出现 if err != nil { return renderError(...) } 跨了三层调用栈,基本就埋下后期迁移成本了。

















