errors

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 27, 2026 License: MIT Imports: 5 Imported by: 0

README

errors — 错误类型系统

提供结构化错误类型，支持错误码、HTTP 状态码映射、堆栈追踪与错误链包装，统一全框架的错误处理模式。

错误分类

类型常量 含义
ErrorTypeValidation 数据校验失败
ErrorTypeRequired 必填字段缺失
ErrorTypeInvalid 非法值/格式
ErrorTypeNotFound 资源不存在
ErrorTypeConflict 资源冲突
ErrorTypeUnauthorized 未认证
ErrorTypeForbidden 无权限
ErrorTypeDatabase 数据库错误
ErrorTypeInternal 内部错误
ErrorTypeTimeout 超时
ErrorTypeRateLimit 限流

快速开始

创建错误
import framerrors "github.com/leeforge/framework/errors"

// 业务错误（带错误码）
err := framerrors.New(framerrors.ErrorTypeNotFound, "用户不存在")

// 带 HTTP 状态码
err := framerrors.NewWithStatus(framerrors.ErrorTypeUnauthorized, "Token 已过期", http.StatusUnauthorized)

// 包装下层错误（保留堆栈）
err := framerrors.Wrap(dbErr, framerrors.ErrorTypeDatabase, "查询用户失败")
错误判断
var fe *framerrors.FrameworkError
if errors.As(err, &fe) {
    httpStatus := fe.HTTPStatus()
    code := fe.Code()
    msg := fe.Message()
}

// 快捷判断
if framerrors.IsNotFound(err) {
    responder.NotFound(w, r, "资源不存在")
    return
}

if framerrors.IsValidation(err) {
    res.ValidationError(err)
    return
}
错误包装（与标准库兼容）
// 使用 fmt.Errorf 包装（推荐用于内部传递）
err = fmt.Errorf("createUser: %w", framerrors.New(framerrors.ErrorTypeConflict, "邮箱已存在"))

// 使用框架 Wrap（携带堆栈）
err = framerrors.Wrap(originalErr, framerrors.ErrorTypeInternal, "保存媒体失败")

在 Handler 中使用

func (h *Handler) CreateUser(w http.ResponseWriter, r *http.Request) {
    user, err := h.svc.Create(ctx, dto)
    if err != nil {
        var fe *framerrors.FrameworkError
        if errors.As(err, &fe) {
            res := responder.New(w, r, nil)
            res.Error(fe.Code(), fe.Message(), nil)
            return
        }
        res.InternalError(err)
        return
    }
    responder.Created(w, r, user)
}

注意事项

  • 错误包装使用 %w，确保 errors.Is / errors.As 能正常工作
  • 禁止在 handler 中直接返回原始数据库错误，必须通过 framerrors.Wrap 包装后再传递
  • 堆栈追踪仅在 Wrap 时生成，New 不自动附加堆栈（避免性能开销）

Documentation

Index

Constants

View Source 
const (
	CodeValidationFailed   = "VALIDATION_FAILED"
	CodeRequiredField      = "REQUIRED_FIELD"
	CodeInvalidField       = "INVALID_FIELD"
	CodeNotFound           = "NOT_FOUND"
	CodeConflict           = "CONFLICT"
	CodeUnauthorized       = "UNAUTHORIZED"
	CodeForbidden          = "FORBIDDEN"
	CodeRateLimit          = "RATE_LIMIT"
	CodeInternalError      = "INTERNAL_ERROR"
	CodeServiceUnavailable = "SERVICE_UNAVAILABLE"
)

Error codes for specific scenarios

Variables

This section is empty.

Functions

func ErrorRecover 

func ErrorRecover() (err error)

ErrorRecover recovers from panics and converts them to errors

func ErrorRecoverWithHandler 

func ErrorRecoverWithHandler(handler func(*AppError))

ErrorRecoverWithHandler recovers from panics and handles them

Types

type AppError 

type AppError struct {
	Type       ErrorType              `json:"type"`
	Code       string                 `json:"code"`
	Message    string                 `json:"message"`
	Details    map[string]interface{} `json:"details,omitempty"`
	InnerError error                  `json:"-"`
	Stack      []string               `json:"-"`
	HTTPStatus int                    `json:"-"`
}

AppError represents a structured application error

func FromError 

func FromError(err error) *AppError

FromError converts a standard error to AppError

func New 

func New(errType ErrorType, message string) *AppError

New creates a new AppError

func NewBusiness 

func NewBusiness(message string) *AppError

Business errors

func NewConflict 

func NewConflict(resource string, id interface{}) *AppError

func NewDatabase 

func NewDatabase(message string) *AppError

Database errors

func NewExternal 

func NewExternal(message string) *AppError

func NewForbidden 

func NewForbidden(message string) *AppError

func NewInternal 

func NewInternal(message string) *AppError

System errors

func NewInvalid 

func NewInvalid(field string, value interface{}, reason string) *AppError

func NewNotFound 

func NewNotFound(resource string, id interface{}) *AppError

func NewRateLimit 

func NewRateLimit(message string) *AppError

func NewRequired 

func NewRequired(field string) *AppError

func NewTimeout 

func NewTimeout(message string) *AppError

func NewUnauthorized 

func NewUnauthorized(message string) *AppError

Authorization errors

func NewValidation 

func NewValidation(message string) *AppError

Validation errors

func Wrap 

func Wrap(err error, message string) *AppError

Wrap wraps an error with additional context

func WrapWithType 

func WrapWithType(err error, errType ErrorType, message string) *AppError

WrapWithType wraps an error with a specific type

func (*AppError) Error 

func (e *AppError) Error() string

Error implements the error interface

func (*AppError) Is 

func (e *AppError) Is(target error) bool

Is checks if this error is of a specific type

func (*AppError) Unwrap 

func (e *AppError) Unwrap() error

Unwrap returns the inner error

func (*AppError) WithCode 

func (e *AppError) WithCode(code string) *AppError

WithCode adds a code to the error

func (*AppError) WithDetail 

func (e *AppError) WithDetail(key string, value interface{}) *AppError

WithDetail adds a detail to the error

func (*AppError) WithDetails 

func (e *AppError) WithDetails(details map[string]interface{}) *AppError

WithDetails adds multiple details to the error

func (*AppError) WithHTTPStatus 

func (e *AppError) WithHTTPStatus(status int) *AppError

WithHTTPStatus sets the HTTP status code

func (*AppError) WithInnerError 

func (e *AppError) WithInnerError(err error) *AppError

WithInnerError sets the inner error

func (*AppError) WithMessage 

func (e *AppError) WithMessage(msg string) *AppError

WithMessage adds a message to the error

func (*AppError) WithStack 

func (e *AppError) WithStack() *AppError

WithStack captures the call stack

type ErrorChain 

type ErrorChain struct {
	// contains filtered or unexported fields
}

ErrorChain represents a chain of errors

func NewErrorChain 

func NewErrorChain() *ErrorChain

NewErrorChain creates a new error chain

func (*ErrorChain) Add 

func (c *ErrorChain) Add(err *AppError) *ErrorChain

Add adds an error to the chain

func (*ErrorChain) Error 

func (c *ErrorChain) Error() string

Error returns the combined error message

func (*ErrorChain) Errors 

func (c *ErrorChain) Errors() []*AppError

Errors returns all errors in the chain

func (*ErrorChain) Filter 

func (c *ErrorChain) Filter(errType ErrorType) *ErrorChain

Filter filters errors by type

func (*ErrorChain) First 

func (c *ErrorChain) First() *AppError

First returns the first error in the chain

func (*ErrorChain) HasErrors 

func (c *ErrorChain) HasErrors() bool

HasErrors checks if the chain has errors

func (*ErrorChain) HasType 

func (c *ErrorChain) HasType(errType ErrorType) bool

HasType checks if the chain has an error of the specified type

func (*ErrorChain) Last 

func (c *ErrorChain) Last() *AppError

Last returns the last error in the chain

func (*ErrorChain) ToHTTPStatus 

func (c *ErrorChain) ToHTTPStatus() int

ToHTTPStatus converts the error chain to an HTTP status code

type ErrorConverter 

type ErrorConverter struct {
	// contains filtered or unexported fields
}

ErrorConverter converts errors to HTTP responses

func NewErrorConverter 

func NewErrorConverter(errorHandler *ErrorHandler) *ErrorConverter

NewErrorConverter creates a new error converter

func (*ErrorConverter) ToHTTPResponse 

func (c *ErrorConverter) ToHTTPResponse(err error) HTTPErrorResponse

ToHTTPResponse converts an error to an HTTP response

type ErrorFormatter 

type ErrorFormatter struct {
	// contains filtered or unexported fields
}

ErrorFormatter formats errors for display

func NewErrorFormatter 

func NewErrorFormatter(showStack bool, showInner bool) *ErrorFormatter

NewErrorFormatter creates a new error formatter

func (*ErrorFormatter) Format 

func (f *ErrorFormatter) Format(err error) string

Format formats an error as a string

type ErrorHandler 

type ErrorHandler struct {
	// contains filtered or unexported fields
}

ErrorHandler handles errors in a standardized way

func NewErrorHandler 

func NewErrorHandler(registry *ErrorRegistry) *ErrorHandler

NewErrorHandler creates a new error handler

func (*ErrorHandler) Handle 

func (h *ErrorHandler) Handle(err error) *AppError

Handle handles an error

func (*ErrorHandler) HandleFunc 

func (h *ErrorHandler) HandleFunc(errType ErrorType, fn func(*AppError) *AppError)

HandleFunc registers a handler for a specific error type

func (*ErrorHandler) Wrap 

func (h *ErrorHandler) Wrap(err error, message string) *AppError

Wrap wraps an error with context

type ErrorLogger 

type ErrorLogger struct {
	// contains filtered or unexported fields
}

ErrorLogger logs errors with context

func NewErrorLogger 

func NewErrorLogger(logger ErrorLoggerInterface) *ErrorLogger

NewErrorLogger creates a new error logger

func (*ErrorLogger) Log 

func (l *ErrorLogger) Log(err error, context map[string]interface{})

Log logs an error with context

type ErrorLoggerInterface 

type ErrorLoggerInterface interface {
	Error(msg string, fields ...interface{})
	Errorf(format string, args ...interface{})
	WithField(key string, value interface{}) interface{}
}

ErrorLoggerInterface defines the interface for logging

type ErrorRegistry 

type ErrorRegistry struct {
	// contains filtered or unexported fields
}

ErrorRegistry manages error definitions

func DefaultErrorRegistry 

func DefaultErrorRegistry() *ErrorRegistry

DefaultErrorRegistry creates a default error registry with common errors

func NewErrorRegistry 

func NewErrorRegistry() *ErrorRegistry

NewErrorRegistry creates a new error registry

func (*ErrorRegistry) Create 

func (r *ErrorRegistry) Create(code string, details map[string]interface{}) *AppError

Create creates a new error from a registered template

func (*ErrorRegistry) Get 

func (r *ErrorRegistry) Get(code string) *AppError

Get retrieves a registered error template

func (*ErrorRegistry) Register 

func (r *ErrorRegistry) Register(code string, err *AppError)

Register registers an error template

type ErrorResponse 

type ErrorResponse struct {
	Type    string                 `json:"type"`
	Code    string                 `json:"code"`
	Message string                 `json:"message"`
	Details map[string]interface{} `json:"details,omitempty"`
}

ErrorResponse represents the error part of an HTTP response

type ErrorRetryer 

type ErrorRetryer struct {
	// contains filtered or unexported fields
}

ErrorRetryer retries operations that may fail

func NewErrorRetryer 

func NewErrorRetryer(maxAttempts int) *ErrorRetryer

NewErrorRetryer creates a new error retryer

func (*ErrorRetryer) Do 

func (r *ErrorRetryer) Do(fn func() error) error

Do executes a function with retry logic

func (*ErrorRetryer) WithRetryDelay 

func (r *ErrorRetryer) WithRetryDelay(fn func(int) int64) *ErrorRetryer

WithRetryDelay sets the retry delay function

func (*ErrorRetryer) WithRetryable 

func (r *ErrorRetryer) WithRetryable(fn func(error) bool) *ErrorRetryer

WithRetryable sets the retryable function

type ErrorType 

type ErrorType string

ErrorType represents the type of error 

const (
	// Validation errors
	ErrorTypeValidation ErrorType = "validation"
	ErrorTypeRequired   ErrorType = "required"
	ErrorTypeInvalid    ErrorType = "invalid"

	// Database errors
	ErrorTypeDatabase ErrorType = "database"
	ErrorTypeNotFound ErrorType = "not_found"
	ErrorTypeConflict ErrorType = "conflict"

	// Authorization errors
	ErrorTypeUnauthorized ErrorType = "unauthorized"
	ErrorTypeForbidden    ErrorType = "forbidden"

	// Business errors
	ErrorTypeBusiness  ErrorType = "business"
	ErrorTypeRateLimit ErrorType = "rate_limit"
	ErrorTypeTimeout   ErrorType = "timeout"

	// System errors
	ErrorTypeInternal ErrorType = "internal"
	ErrorTypeExternal ErrorType = "external"
	ErrorTypeUnknown  ErrorType = "unknown"
)

type ErrorValidator 

type ErrorValidator struct {
	// contains filtered or unexported fields
}

ErrorValidator validates errors

func NewErrorValidator 

func NewErrorValidator(allowedTypes ...ErrorType) *ErrorValidator

NewErrorValidator creates a new error validator

func (*ErrorValidator) IsAllowed 

func (v *ErrorValidator) IsAllowed(err error) bool

IsAllowed checks if an error type is allowed

func (*ErrorValidator) Validate 

func (v *ErrorValidator) Validate(err error) error

Validate validates an error against rules

type HTTPErrorResponse 

type HTTPErrorResponse struct {
	HTTPStatus int           `json:"-"`
	Error      ErrorResponse `json:"error"`
}

HTTPErrorResponse represents an HTTP error response

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.