如何在Golang中实现Web API统一错误处理_Golang Web API错误管理方法_技术教程

统一错误处理提升Golang Web API可维护性与一致性，含结构化响应、中间件panic捕获、自定义AppError、封装响应函数及日志集成。

在构建 Golang Web API 时，统一错误处理能提升代码可维护性、增强接口一致性，并让前端更容易解析错误信息。通过集中管理错误，你可以避免重复的错误判断和响应逻辑，同时便于记录日志、追踪问题。

定义统一的错误响应格式

为了前后端协作顺畅，所有 API 接口应返回结构一致的错误响应体。通常包含状态码、错误消息和可选的详细信息。

{
  "success": false,
  "message": "资源未找到",
  "error": {
    "code": "NOT_FOUND",
    "details": "用户ID不存在"
  }
}

对应 Go 结构体可以这样定义：

type ErrorResponse struct {
    Success bool        `json:"success"`
    Message string      `json:"message"`
    Error   ErrorDetail `json:"error,omitempty"`
}

type ErrorDetail struct {
    Code    string `json:"code"`
    Details string `json:"details,omitempty"`
}

使用中间件捕获和处理错误

Go 的 net/http 不自带异常机制，但可以通过中间件配合 panic 和 recover 实现全局错误拦截。你也可以在 handler 中主动调用统一响应函数。

创建一个错误处理中间件：

func ErrorHandler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                log.Printf("Panic recovered: %v", err)
                w.Header().Set("Content-Type", "application/json")
                w.WriteHeader(http.StatusInternalServerError)
                json.NewEncoder(w).Encode(ErrorResponse{
                    Success: false,
                    Message: "服务器内部错误",
                    Error: ErrorDetail{
                        Code:    "INTERNAL_ERROR",
                        Details: fmt.Sprintf("%v", err),
                    },
                })
            }
        }()
        next.ServeHTTP(w, r)
    })
}

将中间件应用到路由：

mux := http.NewServeMux()
mux.Handle("/api/user/", ErrorHandler(http.HandlerFunc(getUserHandler)))

log.Fatal(http.ListenAndServe(":8080", mux))

自定义错误类型与主动返回错误

除了捕获 panic，你还需要在业务逻辑中主动返回语义清晰的错误。为此可以定义应用级错误类型。

type AppError struct {
    Code    string
    Message string
    Err     error
}

func (e AppError) Error() string {
    return e.Message
}

在 handler 中使用：

func getUserHandler(w http.ResponseWriter, r *http.Request) {
    userID := r.URL.Query().Get("id")
    if userID == "" {
        respondWithError(w, http.StatusBadRequest, "MISSING_USER_ID", "用户ID不能为空")
        return
    }

    user, err := db.GetUser(userID)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            respondWithError(w, http.StatusNotFound, "USER_NOT_FOUND", "指定用户不存在")
            return
        }
        respondWithError(w, http.StatusInternalServerError, "DB_ERROR", "数据库查询失败")
        return
    }

    respondWithJSON(w, http.StatusOK, map[string]interface{}{
        "success": true,
        "data":    user,
    })
}

封装响应函数：

func respondWithError(w http.ResponseWriter, status int, code, message string) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(ErrorResponse{
        Success: false,
        Message: message,
        Error: ErrorDetail{
            Code:    code,
            Details: message,
        },
    })
}

func respondWithJSON(w http.ResponseWriter, status int, payload interface{}) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(payload)
}

集成日志与监控

统一错误处理不仅是返回客户端信息，还应记录关键错误用于排查。可以在 respondWithError 或中间件中加入日志输出。

例如使用 zap 或 logrus 记录错误堆栈和请求上下文：

logger.Error("Request failed",
    zap.String("method", r.Method),
    zap.String("url", r.URL.String()),
    zap.String("error_code", code),
    zap.Error(appErr.Err))

结合 tracing ID 可进一步提升调试效率。

基本上就这些。通过结构化错误响应、中间件拦截、自定义错误类型和统一响应函数，你能有效管理 Golang Web API 中的所有错误路径。不复杂但容易忽略细节，比如状态码映射和日志上下文。做好了，API 会更健壮、更易维护。