Golang Gin如何做统一错误返回_Golang Gin错误处理教程【收藏】

陆砚码

2026-10-23 • 👁 0人浏览过

Gin默认Recovery中间件仅捕获panic并打印日志，不返回JSON响应；需自定义中间件调用c.AbortWithStatusJSON()返回结构化错误，并统一处理业务错误与panic。默认的

gin.Recovery()

中间件只 recover panic 并打印日志，**不会返回 JSON 响应**，也不会修改响应体格式。你看到的 500 页面是浏览器原生 HTML，前端无法解析——这不是 bug，是 Gin 的设计：捕获和渲染解耦，留给你自定义空间。为什么默认 Recovery 不返回 JSON Gin 的

gin.Recovery()

是个“裸 recovery”，它只做三件事：defer 捕获 panic、调用

log.Printf

打印堆栈、调用

c.Abort()

终止流程。它压根不碰

c.JSON()

或

c.AbortWithStatusJSON()

，所以响应体仍是空的，最终走 Gin 底层 fallback，返回纯文本或 HTML（取决于 Accept 头）。别在

r.Use(gin.Recovery())

后就以为错误能被前端消费——那只是日志有了，响应还是裸的生产环境必须禁用默认 Recovery，否则会泄露 panic 详情（如文件路径、变量名） HTTP 状态码（如

http.StatusInternalServerError

）和业务错误码（如

5000

）要分开：前者控制客户端重试/跳转行为，后者供前端 UI 分支处理怎么写一个真正返回 JSON 的 Recovery 中间件核心就两步：recover 后构造结构化错误，再用

c.AbortWithStatusJSON()

写响应并终止流程。注意必须

return

，否则后续

c.Next()

可能二次写 header 导致 panic。不要用

http.Error()

或手动

w.WriteHeader()

——

c.AbortWithStatusJSON()

已自动设置

Content-Type: application/json

错误结构建议含

code

（int）、

message

（string）、

timestamp

（

time.Now().UnixMilli()

），避免嵌套过深或暴露敏感字段 panic 错误体必须脱敏：禁止透传

db.QueryRow failed: no rows in result set

这类原始信息，统一转成

"资源不存在"

func CustomRecovery() gin.HandlerFunc {
    return func(c *gin.Context) {
        defer func() {
            if err := recover(); err != nil {
                log.Printf("PANIC: %+v", err)
                c.AbortWithStatusJSON(http.StatusInternalServerError, map[string]interface{}{
                    "code":      5000,
                    "message":   "服务器内部错误",
                    "timestamp": time.Now().UnixMilli(),
                })
                return // ⚠️ 必须加！
            }
        }()
        c.Next()
    }
}

如何让业务错误（非 panic）也走同一套返回格式 Gin 的

c.Error(err)

是个信号机制：它把错误存进

c.Errors

队列，但**不会自动渲染**。你要在中间件末尾主动检查并格式化输出，否则这些错误就静默丢失了。 go语言参考手册中文CHM版 Go 是一个开源的编程语言，它能让构造简单、可靠且高效的软件变得容易。本文给大家带来Go参考手册，需要的可以来下载！ Go是从2007年末由Robert Griesemer, Rob Pike, Ken Thompson主持开发，后来还加入了Ian Lance Taylor, Russ Cox等人，并最终于2009年11月开源，在2012年早些时候发布了Go 1稳定版本。现在Go的开发已经是完全开放的，并且拥有一个活跃的社区。 Go 语言特色简洁、快速、安全并行、有趣、开源内存管理、v数组安全、编译下载立即学习 “ go语言免费学习笔记（深入） ”；在 handler 里别直接

c.JSON(400, ...)

，改用

c.Error(ErrInvalidParam)

（其中

ErrInvalidParam

是预定义的

*AppError

）全局中间件中加判断：

if len(c.Errors) > 0 { c.AbortWithStatusJSON(...); return }

用

errors.Is()

或类型断言区分错误类型（如

*biz.ValidationError

），别依赖

err.Error()

包含关键词来判断

c.AbortWithError(statusCode, err)

更适合需要立刻终止流程的场景（如参数校验失败），但第二个参数必须是

error

类型，传字符串会 panic 统一错误结构体该定义成什么样别用接口或嵌套 struct，用导出字段的 plain struct，确保 JSON 序列化稳定、字段可扩展、前端易解析。

code

用

int

，约定 0 表示成功，非 0 表示错误；避免用字符串码（如

"invalid_param"

），前端 switch 不友好必须包含

StatusCode

字段（如

http.StatusBadRequest

），和业务

code

分开管理——401/403 要带提示，500 必须脱敏，不能混用同一套 message 推荐预定义错误变量：

var ErrNotFound = NewAppError(1004, "资源未找到", http.StatusNotFound)

，便于类型断言和日志归类所有响应函数末尾必须加

return

，防止

c.Next()

后续逻辑继续执行导致重复写 response

type AppError struct {
    Code        int    `json:"code"`
    Message     string `json:"message"`
    StatusCode  int    `json:"status_code"`
    RequestID   string `json:"request_id,omitempty"`
}
func (e *AppError) Error() string {
    return fmt.Sprintf("code=%d message=%s", e.Code, e.Message)
}

最难的不是写中间件，而是让所有 handler 都习惯用

c.Error()

而不是裸

return err

，也不在业务层直接调

c.JSON()

。一旦漏掉一两个地方，统一格式就破了——得靠代码审查和单元测试卡住。

相关文章