如何在Golang中自定义错误码_Golang错误标识与HTTP响应映射_技术教程

自定义错误码并与HTTP状态码合理映射可提升API可维护性。通过定义ErrorCode类型和Error结构体，结合常量枚举实现清晰的错误体系；将不同业务错误如ErrInvalidParams、ErrUserNotFound分别映射为400、404等标准HTTP状态码，并在Handler中统一返回结构化JSON响应，确保前端处理一致性和调试效率。关键在于建立规范并全局复用。

在Go语言开发中，自定义错误码并将其与HTTP响应状态码进行合理映射，是构建清晰、可维护API的关键环节。直接使用标准错误或裸写字符串不利于前端处理和日志分析。通过统一的错误码体系，可以提升系统的可读性和调试效率。

定义错误码结构

建议使用常量或枚举方式定义业务错误码，每个错误码对应一个唯一的数字标识和描述信息。可以结合error接口实现自定义错误类型。

示例：

type ErrorCode int

const (
    Success           ErrorCode = 0
    ErrInvalidParams  ErrorCode = 1001
    ErrUserNotFound   ErrorCode = 1002
    ErrUnauthorized   ErrorCode = 1003
    ErrInternalServer ErrorCode = 5001
)

type Error struct {
    Code    ErrorCode `json:"code"`
    Message string    `json:"message"`
    Detail  string    `json:"detail,omitempty"`
}

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

// 全局错误变量，便于复用
var (
    ErrInvalidParamsErr = &Error{Code: ErrInvalidParams, Message: "请求参数无效"}
    ErrUserNotFoundErr  = &Error{Code: ErrUserNotFound, Message: "用户不存在"}
)

错误到HTTP状态码的映射策略

并非所有错误都应返回500。根据语义将自定义错误码映射为合适的HTTP状态码，有助于客户端正确理解响应含义。

常见映射方式：

400 Bad Request：用于参数校验失败（如ErrInvalidParams）
401 Unauthorized：认证失败（如ErrUnauthorized）
404 Not Found：资源未找到（如ErrUserNotFound）
500 Internal Server Error：系统内部错误（如ErrInternalServer）

可通过函数实现自动转换：

func HTTPStatusFromErrorCode(code ErrorCode) int {
    switch code {
    case Success:
        return 200
    case ErrInvalidParams:
        return 400
    case ErrUnauthorized:
        return 401
    case ErrUserNotFound:
        return 404
    case ErrInternalServer:
        return 500
    default:
        return 500
    }
}

在HTTP Handler中使用自定义错误

在实际处理请求时，捕获自定义错误并返回结构化JSON响应。

示例：

func GetUserHandler(w http.ResponseWriter, r *http.Request) {
    userId := r.URL.Query().Get("id")
    if userId == "" {
        respondWithError(w, ErrInvalidParamsErr)
        return
    }

    user, err := GetUserById(userId)
    if err != nil {
        if errors.Is(err, ErrUserNotFound) {
            respondWithError(w, ErrUserNotFoundErr)
            return
        }
        // 其他错误包装为内部错误
        log.Printf("get user failed: %v", err)
        respondWithError(w, &Error{Code: ErrInternalServer, Message: "服务器内部错误"})
        return
    }

    respondWithJSON(w, 200, map[string]interface{}{"data": user})
}

func respondWithError(w http.ResponseWriter, err *Error) {
    w.Header().Set("Content-Type", "application/json")
    status := HTTPStatusFromErrorCode(err.Code)
    respondWithJSON(w, status, err)
}

func respondWithJSON(w http.ResponseWriter, code int, payload interface{}) {
    w.WriteHeader(code)
    json.NewEncoder(w).Encode(payload)
}