errorsx

README

This package provides a convenient way to map custom errors to both HTTP and gRPC status codes. This helps in ensuring consistency in error handling across different service architectures.

Documentation

Index

• Variables
• func As(err error, target interface{}) bool
• func Code(err error) int
• func Is(err, target error) bool
• func Reason(err error) string
• func Unwrap(err error) error
• type ErrorX
  • func FromError(err error) *ErrorX
  • func New(code int, reason string, format string, args ...any) *ErrorX
  • func (err *ErrorX) Error() string
  • func (err *ErrorX) GRPCStatus() *status.Status
  • func (err *ErrorX) Is(target error) bool
  • func (err *ErrorX) KV(kvs ...string) *ErrorX
  • func (err *ErrorX) WithMessage(format string, args ...any) *ErrorX
  • func (err *ErrorX) WithMetadata(md map[string]string) *ErrorX
  • func (err *ErrorX) WithRequestID(requestID string) *ErrorX

Variables

var (
	// OK 代表请求成功.
	OK = &ErrorX{Code: http.StatusOK, Message: ""}

	// ErrInternal 表示所有未知的服务器端错误.
	ErrInternal = &ErrorX{Code: http.StatusInternalServerError, Reason: "InternalError", Message: "Internal server error."}

	// ErrNotFound 表示资源未找到.
	ErrNotFound = &ErrorX{Code: http.StatusNotFound, Reason: "NotFound", Message: "Resource not found."}

	// ErrBind 表示请求体绑定错误.
	ErrBind = &ErrorX{Code: http.StatusBadRequest, Reason: "BindError", Message: "Error occurred while binding the request body to the struct."}

	// ErrInvalidArgument 表示参数验证失败.
	ErrInvalidArgument = &ErrorX{Code: http.StatusBadRequest, Reason: "InvalidArgument", Message: "Argument verification failed."}

	// ErrUnauthenticated 表示认证失败.
	ErrUnauthenticated = &ErrorX{Code: http.StatusUnauthorized, Reason: "Unauthenticated", Message: "Unauthenticated."}

	// ErrPermissionDenied 表示请求没有权限.
	ErrPermissionDenied = &ErrorX{Code: http.StatusForbidden, Reason: "PermissionDenied", Message: "Permission denied. Access to the requested resource is forbidden."}

	// ErrOperationFailed 表示操作失败.
	ErrOperationFailed = &ErrorX{Code: http.StatusConflict, Reason: "OperationFailed", Message: "The requested operation has failed. Please try again later."}
)

errorsx 预定义标准的错误.

Functions

func As

func As(err error, target interface{}) bool

As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.

As will panic if target is not a non-nil pointer to either a type that implements error, or to any interface type. As returns false if err is nil.

func Code

func Code(err error) int

Code 返回错误的 HTTP 代码.

func Is

func Is(err, target error) bool

Is reports whether any error in err's chain matches target.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.

func Reason

func Reason(err error) string

Reason 返回特定错误的原因.

func Unwrap

func Unwrap(err error) error

Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.

Types

type ErrorX

type ErrorX struct {
	// Code 表示错误的 HTTP 状态码，用于与客户端进行交互时标识错误的类型.
	Code int `json:"code,omitempty"`

	// Reason 表示错误发生的原因，通常为业务错误码，用于精准定位问题.
	Reason string `json:"reason,omitempty"`

	// Message 表示简短的错误信息，通常可直接暴露给用户查看.
	Message string `json:"message,omitempty"`

	// Metadata 用于存储与该错误相关的额外元信息，可以包含上下文或调试信息.
	Metadata map[string]string `json:"metadata,omitempty"`
}

ErrorX 定义了项目体系中使用的错误类型，用于描述错误的详细信息.

func FromError

func FromError(err error) *ErrorX

FromError 尝试将一个通用的 error 转换为自定义的 *ErrorX 类型.

func New

func New(code int, reason string, format string, args ...any) *ErrorX

New 创建一个新的错误.

func (*ErrorX) Error

func (err *ErrorX) Error() string

Error 实现 error 接口中的 `Error` 方法.

func (*ErrorX) GRPCStatus

func (err *ErrorX) GRPCStatus() *status.Status

GRPCStatus 返回 gRPC 状态表示.

func (*ErrorX) Is

func (err *ErrorX) Is(target error) bool

Is 判断当前错误是否与目标错误匹配. 它会递归遍历错误链，并比较 ErrorX 实例的 Code 和 Reason 字段. 如果 Code 和 Reason 均相等，则返回 true；否则返回 false.

func (*ErrorX) KV

func (err *ErrorX) KV(kvs ...string) *ErrorX

KV 使用 key-value 对设置元数据.

func (*ErrorX) WithMessage

func (err *ErrorX) WithMessage(format string, args ...any) *ErrorX

WithMessage 设置错误的 Message 字段.

func (*ErrorX) WithMetadata

func (err *ErrorX) WithMetadata(md map[string]string) *ErrorX

WithMetadata 设置元数据.

func (*ErrorX) WithRequestID

func (err *ErrorX) WithRequestID(requestID string) *ErrorX

WithRequestID 设置请求 ID.