如何在Gin中间件中统一处理HTTP错误 避免各路由重复判断状态码

当前实现的合理性评估 #

你当前的实现可以正常运行，属于手动封装统一错误处理的可行方案，但存在两个明显短板：

• 每个路由遇到错误都需要手动调用ErrorHandler并执行return，一旦漏写就会出现响应异常，代码冗余度高
• 仅通过==匹配全局错误变量的逻辑兼容性差，如果错误被外层包装过（比如用fmt.Errorf加%w参数包装错误上下文），就会匹配失败，无法正确识别错误类型

Gin 原生的统一错误处理方案 #

Gin 完全支持类似 Express 的全局错误处理机制，核心依赖Context.Error()方法和全局中间件实现，整体逻辑和你在 Node.js 中用到的错误中间件完全对应，实现步骤如下：

1. 自定义带状态码的错误类型

首先定义承载HTTP错误信息的结构体，实现error接口：

type HttpError struct {
    StatusCode int    // HTTP状态码
    Message    string // 错误提示
}

// 实现error接口
func (e *HttpError) Error() string {
    return e.Message
}

// 可以按需封装快捷构造方法
func NewHttpError(code int, msg string) *HttpError {
    return &HttpError{
        StatusCode: code,
        Message:    msg,
    }
}

var (
    ErrNotFound         = NewHttpError(http.StatusNotFound, http.StatusText(http.StatusNotFound))
    ErrInternalServerError = NewHttpError(http.StatusInternalServerError, http.StatusText(http.StatusInternalServerError))
)

2. 路由层只需抛出错误

路由处理逻辑中遇到错误时，不需要手动调用错误处理方法，只需要调用c.Error()把错误存入上下文即可：

func (h *Handler) List(c *gin.Context) {
    movies, err := h.service.ListService()
    if err != nil {
        // 把错误存入上下文，后续由全局中间件统一处理
        _ = c.Error(err)
        return
    }
    c.JSON(http.StatusOK, movies)
}

3. 实现全局错误处理中间件

写一个中间件，等所有路由处理逻辑执行完成后，统一读取上下文中的错误并返回响应：

func ErrorHandlerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 先执行后续所有路由处理逻辑
        c.Next()

        // 检查是否存在错误
        if len(c.Errors) > 0 {
            err := c.Errors[0].Err
            var httpErr *HttpError
            // 匹配自定义错误类型，支持被包装过的错误
            if errors.As(err, &httpErr) {
                c.JSON(httpErr.StatusCode, gin.H{"error": httpErr.Message})
                return
            }
            // 未知错误统一返回500
            c.JSON(http.StatusInternalServerError, gin.H{"error": "内部服务器错误"})
        }
    }
}

4. 注册中间件

注意中间件要在所有路由注册之前注册，确保可以捕获所有路由的错误：

func main() {
    r := gin.Default()
    // 第一个注册错误处理中间件
    r.Use(ErrorHandlerMiddleware())
    // 后续注册其他路由和中间件
    r.GET("/movies", handler.List)
    // ...其他路由
    r.Run(":8080")
}

方案优势 #

• 完全消除路由层的重复错误处理代码，只需统一抛出错误即可
• 基于错误类型匹配的逻辑兼容性更强，支持嵌套包装的错误场景
• 错误处理逻辑完全收敛在中间件中，后续修改错误返回格式、增加错误日志等操作不需要修改任何路由代码

内容的提问来源于stack exchange，提问作者John