如何在Golang中实现Web应用错误处理_统一返回错误信息_技术教程

统一错误处理需拦截业务错误、标准化响应结构、防止信息泄露并正确映射HTTP状态码；通过ErrorResponse结构定义业务码与消息，用中间件捕获panic和error，handler返回(interface{}, error)，由ResultHandler统一渲染，并按AppError.Code映射合理HTTP状态码。

在 Golang Web 开发中，统一错误处理的核心是拦截业务错误、标准化响应结构、避免敏感信息泄露，并保持 HTTP 状态码语义正确。不推荐直接在每个 handler 里写 if err != nil + json.NewEncoder(w).Encode(...)，那样重复且易出错。

定义统一错误响应结构

先设计一个前端友好的 JSON 错误格式，包含状态码、错误码、消息和可选的详情：

type ErrorResponse struct {
    Code    int    `json:"code"`    // 业务错误码，如 1001
    Message string `json:"message"` // 用户可见提示
    TraceID string `json:"trace_id,omitempty` // 用于日志追踪（可选）
}

注意：HTTP 状态码（如 400、500）由 w.WriteHeader() 控制，不要和 Code 字段混淆。前者告诉客户端“请求是否成功”，后者告诉前端“具体哪类业务失败”。

封装中间件统一捕获 panic 和错误

用中间件包裹 handler，集中处理两类异常：

显式返回的 error（例如校验失败、DB 查询为空）
未捕获的 panic（如空指针、数组越界）

func ErrorHandler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                http.Error(w, "Internal Server Error", http.StatusInternalServerError)
                log.Printf("PANIC: %v, trace: %s", err, debug.Stack())
            }
        }()

        // 包装 ResponseWriter，捕获 WriteHeader 调用（可选：用于日志或重写状态码）
        rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
        next.ServeHTTP(rw, r)

        // 如果 handler 显式返回了 error（需配合自定义 context 或返回值约定），此处可扩展处理
        // 更推荐：handler 返回 (interface{}, error)，由中间件判断并渲染
    })
}

让 handler 返回 error 并交由中间件渲染

修改 handler 签名，使其返回 (interface{}, error)，再用中间件做最终响应：

type Result struct {
    Data  interface{} `json:"data,omitempty"`
    Error *ErrorResponse `json:"error,omitempty"`
}

func UserHandler(w http.ResponseWriter, r *http.Request) (interface{}, error) {
    id := chi.URLParam(r, "id")
    if id == "" {
        return nil, &AppError{Code: 1001, Message: "用户 ID 不能为空"}
    }
    user, err := db.GetUser(id)
    if err != nil {
        return nil, &AppError{Code: 1002, Message: "用户不存在"}
    }
    return user, nil
}

// 中间件解析 result 并写入响应
func ResultHandler(handler func(http.ResponseWriter, *http.Request) (interface{}, error)) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        data, err := handler(w, r)
        if err != nil {
            // 假设 AppError 实现了 error 接口，并携带 Code/Message
            appErr, ok := err.(*AppError)
            if !ok {
                appErr = &AppError{Code: 5000, Message: "未知错误"}
            }
            w.Header().Set("Content-Type", "application/json; charset=utf-8")
            w.WriteHeader(appErr.HTTPStatus()) // 如 400 → 400，500 → 500
            json.NewEncoder(w).Encode(Result{Error: &ErrorResponse{
                Code:    appErr.Code,
                Message: appErr.Message,
                TraceID: getTraceID(r),
            }})
            return
        }
        w.Header().Set("Content-Type", "application/json; charset=utf-8")
        w.WriteHeader(http.StatusOK)
        json.NewEncoder(w).Encode(Result{Data: data})
    })
}

区分错误类型，合理设置 HTTP 状态码

不同错误应映射到不同 HTTP 状态码，帮助前端做差异化处理：

客户端错误（参数缺失、格式错误、权限不足）→ 400 Bad Request / 401 Unauthorized / 403 Forbidden
资源未找到 → 404 Not Found
服务端内部错误（DB 挂了、第三方超时）→ 500 Internal Server Error 或 503 Service Unavailable

建议封装一个 AppError 类型，内置 HTTPStatus() 方法，避免硬编码状态码：

type AppError struct {
    Code    int
    Message string
    status  int // 对应 HTTP 状态码
}

func (e *AppError) HTTPStatus() int {
    switch e.Code {
    case 1001, 1002:
        return http.StatusBadRequest
    case 1003:
        return http.StatusForbidden
    case 1004:
        return http.StatusNotFound
    default:
        return http.StatusInternalServerError
    }
}