如何在Golang中实现统一错误处理_封装函数返回统一格式

Go中统一错误处理需定义AppError结构体封装状态码、业务码、消息等，业务函数返回*AppError，HTTP层用中间件拦截并序列化为标准JSON响应，兼顾安全与日志可追溯性。

在 Go 中实现统一错误处理并封装函数返回统一格式，核心是定义清晰的错误结构、规范错误创建方式、统一响应体，并在 HTTP 层或业务入口处集中拦截和转换错误。不依赖框架也能做到简洁可控。

定义统一错误类型与错误码

避免直接返回 error 接口导致信息丢失，自定义结构体携带状态码、业务码、消息和可选详情：

type AppError struct {
    Code    int    `json:"code"`    // HTTP 状态码（如 400、500）
    ErrCode int    `json:"err_code"` // 业务错误码（如 1001 表示用户不存在）
    Msg     string `json:"msg"`
    Details []string `json:"details,omitempty"`
}

func (e *AppError) Error() string {
    return fmt.Sprintf("[%d]%s", e.ErrCode, e.Msg)
}

// 快捷构造函数
func NewBadRequest(errCode int, msg string, details ...string) *AppError {
    return &AppError{Code: 400, ErrCode: errCode, Msg: msg, Details: details}
}

func NewInternalError(errCode int, msg string, details ...string) *AppError {
    return &AppError{Code: 500, ErrCode: errCode, Msg: msg, Details: details}
}

业务函数统一返回 (data, error)

所有服务层函数遵循相同签名，错误一律用 *AppError，不混用标准 errors.New 或 fmt.Errorf：

成功时返回数据和 nil
失败时返回零值和具体 *AppError，不 panic，不裸露底层错误（如数据库驱动错误）
例如：user, err := userService.GetUserByID(ctx, id)，err 类型为 error，但实际应为 *AppError

HTTP 层统一拦截并序列化响应

在 handler 中用 defer 或中间件捕获错误，转为标准 JSON 响应：

func jsonHandler(f func() (interface{}, error)) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json; charset=utf-8")

        data, err := f()
        if err != nil {
            var appErr *AppError
            if errors.As(err, &appErr) {
                w.WriteHeader(appErr.Code)
                json.NewEncoder(w).Encode(map[string]interface{}{
                    "success": false,
                    "data":    nil,
                    "error":   appErr,
                })
                return
            }
            // 非 AppError，兜底为 500
            w.WriteHeader(500)
            json.NewEncoder(w).Encode(map[string]interface{}{
                "success": false,
                "data":    nil,
                "error":   &AppError{Code: 500, ErrCode: 9999, Msg: "Unknown server error"},
            })
            return
        }

        w.WriteHeader(200)
        json.NewEncoder(w).Encode(map[string]interface{}{
            "success": true,
            "data":    data,
            "error":   nil,
        })
    }
}

// 使用示例
http.HandleFunc("/api/user/:id", jsonHandler(func() (interface{}, error) {
    id := chi.URLParam(r, "id")
    user, err := userService.GetUserByID(r.Context(), id)
    if err != nil {
        return nil, err // 直接返回 *AppError
    }
    return user, nil
}))