如何实现Golang统一错误拦截中间件_Golang Web框架通用做法-Golang-PHP中文网

如何实现Golang统一错误拦截中间件_Golang Web框架通用做法

P粉602998670

发布： 2025-12-20 19:05:04

原创

884人浏览过

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

如何实现golang统一错误拦截中间件_golang web框架通用做法

在 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. 与主流框架集成方式

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

立即学习“go语言免费学习笔记（深入）”；

Gin 框架

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")
})

登录后复制

Echo 框架

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)
    }
})

登录后复制

Chi 路由器（net/http 风格）

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

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

登录后复制

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

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

Phidata

Phidata是一个开源框架，可以快速构建和部署AI智能体应用

173

查看详情

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))