cloudnest/internal/pkg/errors/errors.go

package errors

import "net/http"

// AppError represents an application-specific error.
// AppError 表示应用程序特定的错误。
//
// This struct extends the standard error interface with additional fields
// for HTTP status codes and custom error codes.
//
// 此结构体扩展了标准的 error 接口，添加了 HTTP 状态码和自定义错误码字段。
type AppError struct {
	StatusCode int
	Code       int
	Message    string
	Err        error
}

// Error implements the error interface.
// Error 实现了 error 接口。
//
// Returns:
//   - string: The error message, including the wrapped error if present.
//
// 返回值:
//   - string: 错误消息，如果存在包装的错误则包含该错误。
func (e *AppError) Error() string {
	if e.Err != nil {
		return e.Message + ": " + e.Err.Error()
	}
	return e.Message
}

// New creates a new AppError with the specified code and message.
// New 创建一个具有指定代码和消息的新 AppError。
//
// Parameters:
//   - code: The custom error code.
//   - message: The error message.
//
// Returns:
//   - *AppError: A pointer to the new AppError instance.
//
// 参数:
//   - code: 自定义错误代码。
//   - message: 错误消息。
//
// 返回值:
//   - *AppError: 新创建的 AppError 实例指针。
func New(code int, message string) *AppError {
	return &AppError{
		StatusCode: http.StatusOK,
		Code:       code,
		Message:    message,
	}
}

// NewWithErr creates a new AppError with the specified code, message, and wrapped error.
// NewWithErr 创建一个具有指定代码、消息和包装错误的新 AppError。
//
// Parameters:
//   - code: The custom error code.
//   - message: The error message.
//   - err: The wrapped error.
//
// Returns:
//   - *AppError: A pointer to the new AppError instance.
//
// 参数:
//   - code: 自定义错误代码。
//   - message: 错误消息。
//   - err: 包装的错误。
//
// 返回值:
//   - *AppError: 新创建的 AppError 实例指针。
func NewWithErr(code int, message string, err error) *AppError {
	return &AppError{
		StatusCode: http.StatusOK,
		Code:       code,
		Message:    message,
		Err:        err,
	}
}

// BadRequest creates an AppError for 400 Bad Request.
// BadRequest 创建一个 400 Bad Request 的 AppError。
//
// Parameters:
//   - message: The error message.
//
// Returns:
//   - *AppError: A pointer to the BadRequest AppError.
//
// 参数:
//   - message: 错误消息。
//
// 返回值:
//   - *AppError: BadRequest AppError 的指针。
func BadRequest(message string) *AppError {
	return &AppError{
		StatusCode: http.StatusBadRequest,
		Code:       400,
		Message:    message,
	}
}

// Unauthorized creates an AppError for 401 Unauthorized.
// Unauthorized 创建一个 401 Unauthorized 的 AppError。
//
// Parameters:
//   - message: The error message.
//
// Returns:
//   - *AppError: A pointer to the Unauthorized AppError.
//
// 参数:
//   - message: 错误消息。
//
// 返回值:
//   - *AppError: Unauthorized AppError 的指针。
func Unauthorized(message string) *AppError {
	return &AppError{
		StatusCode: http.StatusUnauthorized,
		Code:       401,
		Message:    message,
	}
}

// Forbidden creates an AppError for 403 Forbidden.
// Forbidden 创建一个 403 Forbidden 的 AppError。
//
// Parameters:
//   - message: The error message.
//
// Returns:
//   - *AppError: A pointer to the Forbidden AppError.
//
// 参数:
//   - message: 错误消息。
//
// 返回值:
//   - *AppError: Forbidden AppError 的指针。
func Forbidden(message string) *AppError {
	return &AppError{
		StatusCode: http.StatusForbidden,
		Code:       403,
		Message:    message,
	}
}

// Conflict creates an AppError for 409 Conflict.
// Conflict 创建一个 409 Conflict 的 AppError。
//
// Parameters:
//   - message: The error message.
//
// Returns:
//   - *AppError: A pointer to the Conflict AppError.
//
// 参数:
//   - message: 错误消息。
//
// 返回值:
//   - *AppError: Conflict AppError 的指针。
func Conflict(message string) *AppError {
	return &AppError{
		StatusCode: http.StatusConflict,
		Code:       409,
		Message:    message,
	}
}

// NotFound creates an AppError for 404 Not Found.
// NotFound 创建一个 404 Not Found 的 AppError。
//
// Parameters:
//   - message: The error message.
//
// Returns:
//   - *AppError: A pointer to the NotFound AppError.
//
// 参数:
//   - message: 错误消息。
//
// 返回值:
//   - *AppError: NotFound AppError 的指针。
func NotFound(message string) *AppError {
	return &AppError{
		StatusCode: http.StatusNotFound,
		Code:       404,
		Message:    message,
	}
}

// InternalError creates an AppError for 500 Internal Server Error.
// InternalError 创建一个 500 Internal Server Error 的 AppError。
//
// Parameters:
//   - message: The error message.
//   - err: The wrapped error (typically the underlying cause).
//
// Returns:
//   - *AppError: A pointer to the InternalError AppError.
//
// 参数:
//   - message: 错误消息。
//   - err: 包装的错误（通常是根本原因）。
//
// 返回值:
//   - *AppError: InternalError AppError 的指针。
func InternalError(message string, err error) *AppError {
	return &AppError{
		StatusCode: http.StatusInternalServerError,
		Code:       500,
		Message:    message,
		Err:        err,
	}
}

// IsAppError checks if an error is an AppError.
// IsAppError 检查错误是否是 AppError。
//
// Parameters:
//   - err: The error to check.
//
// Returns:
//   - bool: true if the error is an AppError, false otherwise.
//
// 参数:
//   - err: 要检查的错误。
//
// 返回值:
//   - bool: 如果错误是 AppError 则返回 true，否则返回 false。
func IsAppError(err error) bool {
	_, ok := err.(*AppError)
	return ok
}

// AsAppError attempts to convert an error to an AppError.
// AsAppError 尝试将错误转换为 AppError。
//
// Parameters:
//   - err: The error to convert.
//
// Returns:
//   - *AppError: The converted AppError if successful.
//   - bool: true if the conversion was successful, false otherwise.
//
// 参数:
//   - err: 要转换的错误。
//
// 返回值:
//   - *AppError: 如果转换成功则返回转换后的 AppError。
//   - bool: 如果转换成功则返回 true，否则返回 false。
func AsAppError(err error) (*AppError, bool) {
	e, ok := err.(*AppError)
	return e, ok
}