Golang错误拦截中间件实现教程

“纵有疾风来，人生不言弃”，这句话送给正在学习Golang的朋友们，也希望在阅读本文《Golang统一错误拦截中间件实现方法》后，能够真的帮助到大家。我也会在后续的文章中，陆续更新Golang相关的技术文章，有好的建议欢迎大家在评论留言，非常感谢！

统一错误拦截中间件通过defer+recover捕获panic并返回标准JSON错误响应，支持Gin、Echo、Chi及原生net/http框架，可结合AppError类型实现主动错误传递与统一处理。

在 Golang Web 开发中，统一错误拦截中间件用于捕获处理程序中未被处理的 panic 或自定义错误，避免服务崩溃并返回一致的错误响应格式。无论是使用 Gin、Echo、Chi 还是原生 net/http，都可以通过中间件机制实现这一目标。

1. 中间件基本原理

HTTP 中间件本质是一个函数，接收一个 http.HandlerFunc 并返回一个新的 http.HandlerFunc。它可以在请求进入实际处理逻辑前或后执行额外操作，比如日志记录、身份验证和错误恢复。

关键点在于使用 defer 和 recover() 捕获 panic，防止其向上蔓延导致程序终止。

func ErrorMiddleware(next http.HandlerFunc) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // 使用 defer + recover 捕获 panic
        defer func() {
            if err := recover(); err != nil {
                // 记录堆栈信息（可选）
                log.Printf("Panic recovered: %v\n", err)
                debug.PrintStack()

                // 返回统一错误响应
                w.Header().Set("Content-Type", "application/json")
                w.WriteHeader(http.StatusInternalServerError)
                json.NewEncoder(w).Encode(map[string]string{
                    "error": "Internal server error",
                })
            }
        }()

        // 调用下一个处理器，可能触发 panic
        next(w, r)
    }
}

2. 与主流框架集成方式

不同框架注册中间件的方式略有差异，但核心逻辑一致。

func ErrorHandler() gin.HandlerFunc {
    return func(c *gin.Context) {
        defer func() {
            if err := recover(); err != nil {
                log.Printf("Panic: %v", err)
                c.JSON(500, gin.H{"error": "Internal server error"})
                c.Abort()
            }
        }()
        c.Next()
    }
}

// 使用
r := gin.Default()
r.Use(ErrorHandler())
r.GET("/test", func(c *gin.Context) {
    panic("something went wrong")
})

e := echo.New()
e.Use(func(next echo.HandlerFunc) echo.HandlerFunc {
    return func(c echo.Context) error {
        defer func() {
            if r := recover(); r != nil {
                log.Printf("Panic: %v", r)
                c.JSON(500, map[string]string{"error": "Internal server error"})
            }
        }()
        return next(c)
    }
})

r := chi.NewRouter()
r.Use(ErrorMiddleware) // 使用前面定义的通用中间件

r.Get("/", func(w http.ResponseWriter, r *http.Request) {
    panic("oops")
})

3. 统一错误响应结构设计

建议定义标准错误格式，便于前端解析和日志分析。

type ErrorResponse struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Detail  string `json:"detail,omitempty"` // 可选详细信息（开发环境）
}

func sendError(w http.ResponseWriter, code int, message, detail string) {
    resp := ErrorResponse{
        Code:    code,
        Message: message,
    }
    if env == "dev" { // 根据环境决定是否暴露细节
        resp.Detail = detail
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(code)
    json.NewEncoder(w).Encode(resp)
}

在中间件中调用：sendError(w, 500, "Internal error", fmt.Sprintf("%v", err))

4. 主动错误传递与拦截

除了捕获 panic，还可设计应用级错误，通过 context 或返回值传递，在中间件中统一处理。

例如：

• 定义业务错误类型，如 AppError{Code, Message, Status}
• 处理函数返回 error，中间件判断是否为 AppError 并序列化输出
• 非预期错误（panic）仍由 recover 捕获，返回 500

这样既能控制流程，又能保证异常不遗漏。

基本上就这些。统一错误拦截的核心是利用 defer+recover 构建保护层，结合框架中间件机制注入到请求生命周期中。只要结构清晰，就能在任何 Go Web 项目中快速落地。

今天关于《Golang错误拦截中间件实现教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！