Golang中使用Gin框架自定义错误输出-Golang-PHP中文网

gin默认错误响应缺乏统一结构，无法满足生产需求。其abortwithstatusjson或panic时返回裸json/html，缺少状态码、错误码、时间戳、trace_id等字段，且默认recovery中间件仅打印日志而不返回结构化响应；需自定义recovery中间件捕获panic并构造标准响应体，配合abort()终止流程，并区分http状态码与业务错误码，避免双写响应。

golang中使用gin框架自定义错误输出

为什么 Gin 的默认错误响应不符合生产需求

Gin 默认的 AbortWithStatusJSON 或 panic 时返回的错误格式是裸 JSON 或 HTML 页面，比如 {"message":"Internal Server Error"}，没有统一的状态码、错误码、时间戳或 trace_id，前端难解析，运维难追踪。更麻烦的是，中间件 panic 后的 recovery 默认只打日志，不返回结构化错误体。

用自定义 Recovery 中间件接管 panic 错误

别直接改 Gin 内置的 recovery，它硬编码了错误输出逻辑。自己写一个替代中间件，核心是捕获 recover()，判断 panic 值类型，再统一构造响应：

若 panic 是 error 类型（如 errors.New("db timeout")），提取其消息，设状态码为 500
若 panic 是字符串，直接用作 message，避免 panic("xxx") 导致接口返回 500 但无提示
务必调用 c.Abort() 阻止后续 handler 执行，否则可能重复写 response
响应体建议固定字段：code（业务错误码）、message、timestamp、trace_id（从 context 取或生成）

示例片段：

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

func CustomRecovery() gin.HandlerFunc {
	return func(c *gin.Context) {
		defer func() {
			if err := recover(); err != nil {
				var msg string
				switch e := err.(type) {
				case error:
					msg = e.Error()
				case string:
					msg = e
				default:
					msg = "unknown error"
				}
				c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{
					"code":    50001,
					"message": msg,
					"timestamp": time.Now().UnixMilli(),
					"trace_id":  getTraceID(c),
				})
			}
		}()
		c.Next()
	}
}

在 handler 里主动返回业务错误用 `ctx.Error()` + `ctx.Abort()`

Gin 的 c.Error() 不会自动终止流程，只是把 error 存到上下文里；真正中断执行并写响应得靠 c.Abort() 和手动 c.JSON()。常见误区是只调 c.Error(err) 就以为完事了，结果后续代码继续跑，甚至返回 200 成功响应。

推荐封装一个 ErrorResponse(c *gin.Context, code int, msg string, errCode int) 函数，内部调 c.Abort() + c.JSON()
不要在中间件里用 c.Error() 代替响应，它只是日志/调试辅助，不参与 HTTP 输出
如果用了 gin.ErrorType（如 gin.ErrorTypePrivate），记得配 gin.DefaultErrorWriter 才能生效，但多数场景没必要

全局错误码与 HTTP 状态码别混用

HTTP 状态码（如 400、404、500）决定客户端重试策略和浏览器行为；业务错误码（如 1001 表示“用户不存在”）供前端展示或埋点。两者必须分开设计，不能用业务码直接当 HTTP 码返回。

例如：用户未登录应返回 http.StatusUnauthorized (401)，但 code 字段填 2001
数据库查不到记录用 http.StatusOK (200) + code: 3001，而不是 http.StatusNotFound (404) —— 后者会让前端缓存或触发重定向逻辑
所有 5xx 错误建议统一走 CustomRecovery，避免 handler 里漏写 Abort() 导致双写 response 报错