如何在 Gin 中间件中检测后续处理器的执行失败状态

如何在 Gin 中间件中检测后续处理器的执行失败状态

在 Gin 框架中，可通过 c.Errors 获取中间件链中后续处理器（如路由处理函数或 NoRoute/NoMethod 处理器）主动设置的错误，从而在 c.Next() 之后判断请求是否失败（如 404 路由未命中），实现统一错误响应、日志记录或降级逻辑。

在 Gin 框架中，可以通过 `c.Errors` 来获取中间件链中后续处理器（比如路由处理函数，或者 NoRoute/NoMethod 处理器）主动设置的错误。这样一来，在 `c.Next()` 执行之后，你就能判断请求是否失败了（例如遇到了 404 路由未命中的情况），从而实现统一的错误响应、日志记录或者降级逻辑。

Gin 的 c.Next() 是同步调用的，它会阻塞当前执行，直到整个中间件链（包括最终匹配到的路由处理器）全部完成。但这里有个关键点：c.Next() 本身并不会返回状态码或者错误。Gin 框架将错误处理设计成了一种“累积式”的机制：通过调用 c.Error(err) 方法，可以将错误追加到上下文的 c.Errors 中（其底层类型是 []error）。而框架内置的 NoRoute 或 NoMethod 处理器，恰恰是我们捕获“未匹配路由”这类失败场景的关键入口。

所以，正确的做法应该是：

1. 在 NoRoute / NoMethod 处理器中显式调用 c.Error()，将语义明确的错误信息注入上下文；
2. 在自定义中间件的 c.Next() 之后检查 c.Errors，而不是依赖 c.Writer.Status()（因为响应可能已经被写入，而且 HTTP 状态码并不完全等同于业务逻辑的失败）。

下面是一个完整的代码示例：

func RecoveryWithLogging() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 请求前可执行预处理（如日志、指标）
        startTime := time.Now()
        c.Next() // 执行后续中间件及路由处理器

        // c.Next() 返回后，检查是否有累积错误
        if len(c.Errors) > 0 {
            err := c.Errors.Last() // 获取最后添加的错误（通常最具代表性）
            statusCode := http.StatusInternalServerError
            if strings.Contains(err.Error(), "not allowed") ||
                strings.Contains(err.Error(), "Failed to find route") {
                statusCode = http.StatusNotFound
            }
            // 统一记录失败日志
            log.Printf("[ERROR] %s %s → %d (%v)", c.Request.Method, c.Request.URL.Path, statusCode, err)
            // 可选择在此终止响应（若尚未写入）
            if !c.IsAborted() {
                c.AbortWithStatusJSON(statusCode, gin.H{
                    "success": false,
                    "message": "Request failed",
                    "error":   err.Error(),
                })
            }
            return
        }
        // 无错误时记录成功耗时
        log.Printf("[INFO] %s %s → %d (%v)", c.Request.Method, c.Request.URL.Path, c.Writer.Status(), time.Since(startTime))
    }
}

// 必须注册 NoRoute 处理器并调用 c.Error()
r := gin.New()
r.Use(RecoveryWithLogging)
r.NoRoute(func(c *gin.Context) {
    c.Error(fmt.Errorf("route not found: %s %s", c.Request.Method, c.Request.URL.Path))
    c.JSON(http.StatusNotFound, gin.H{
        "error": "API endpoint not found",
    })
})
r.NoMethod(func(c *gin.Context) {
    c.Error(fmt.Errorf("method not allowed: %s %s", c.Request.Method, c.Request.URL.Path))
    c.JSON(http.StatusMethodNotAllowed, gin.H{
        "error": "HTTP method not supported",
    })
})

⚠️ 需要特别注意的几点：

• c.Errors 仅包含通过显式调用 c.Error() 注入的错误，它不会自动捕获 panic 或者根据 HTTP 状态码生成错误；因此，务必在 NoRoute/NoMethod 处理器中主动调用 c.Error()；
• 如果下游处理器已经调用了 c.Abort() 或者写入了响应（例如使用了 c.JSON），那么 c.IsAborted() 将返回 true，此时就不应该再次写入响应体，以避免触发 `http: multiple response.WriteHeader calls` 错误；
• 使用 c.Errors.Last() 是安全获取最终错误的方式（c.Errors.Error() 方法已被弃用，应避免使用）；
• 这种模式非常适用于业务层失败感知，比如权限拒绝、参数校验失败等场景，你也可以在对应的业务处理器中调用 c.Error()，从而实现统一的错误兜底处理。

通过这套机制，你可以在任意一个中间件里，可靠地感知整个请求处理链的成功与否，从而构建出更加健壮的可观测性与错误处理体系。