Documentation
¶
Overview ¶
Package apperror provides a custom error type that enhances standard Go errors with stack traces and support for additional nested errors.
It is designed to improve error handling in Go applications by offering contextual information such as call location and related errors, especially useful for debugging and logging in production environments.
Features:
- Attaches a lightweight stack trace to each error
- Supports wrapping and chaining of multiple related errors
- Automatically includes detailed trace and error info when debug mode is enabled
- Implements the standard error interface
Usage:
// Create a new application error
err := apperror.NewError("something went wrong")
// Wrap an existing error to capture a new stack trace point
err = apperror.Wrap(err)
// Add related errors for context
err = err.(apperror.Error).AddError(io.EOF)
// Print with trace and nested errors if debug mode is enabled
fmt.Println(err)
To enable debug output (stack traces), set `flag.Debug = true` before printing errors.
Note: If you're wrapping errors that are already of type `apperror.Error`, prefer `Wrap` over creating a new instance to preserve the trace history.
Index ¶
- Variables
- func Anonymous(enable bool)
- func Catch(f func() error, msg string)
- func CatchCustom(f func() error, msg string, handler func(error, string))
- func Handle(err error, msg string)
- func HandleCustom(err error, msg string, handler func(error, string))
- func Split(err error) (string, []string, []error)
- func Where(level int) string
- func Wrap(err error) error
- type Error
- func (e Error) AddDetail(key string, value interface{}) Error
- func (e Error) AddDetails(details map[string]interface{}) Error
- func (e Error) AddError(err error) Error
- func (e Error) AddErrors(errs []error) Error
- func (e Error) Error() string
- func (e Error) GetContext() map[string]interface{}
- func (e Error) GetDetail(key string) interface{}
- func (e Error) Is(target error) bool
- func (e Error) Unwrap() error
Constants ¶
This section is empty.
Variables ¶
var ( // TraceDelimiter is used to separate trace entries TraceDelimiter = " -> " // ErrorDelimiter is used to separate multiple errors ErrorDelimiter = " => " // TraceFormat is the format for displaying trace entries TraceFormat = "%v+%v" // ErrorFormat is the format for displaying the error message and additional errors ErrorFormat = "%s [%s]" // ErrorTraceFormat is the format for displaying the error message with a stack trace ErrorTraceFormat = "%s | %s" // FullFormat is the format for displaying the error message with a stack trace and additional errors FullFormat = "%s | %s [%s]" // WithDetails is a flag to control whether additional details should be included in the error output WithDetails = false // FormatDetails is a function that formats additional details for the error FormatDetails = func(details map[string]interface{}) string { if len(details) == 0 { return "" } var sb strings.Builder for key, value := range details { if sb.Len() > 0 { sb.WriteString(", ") } sb.WriteString(fmt.Sprintf("%s: %v", key, value)) } return sb.String() } // ErrorHandler is a function that handles deferred error checks ErrorHandler = func(err error, msg string) { if flag.Debug { panic(fmt.Sprintf(FullFormat, strings.Join(trace(Error{Message: msg}), TraceDelimiter), msg, err.Error())) } panic(fmt.Sprintf(ErrorFormat, msg, err.Error())) } )
Functions ¶
func Anonymous ¶
func Anonymous(enable bool)
Anonymous enables or disables anonymous caller tracking When enabled, the trace will use package name and line number instead of full file path This can help reduce noise in logs while still providing useful context
func Catch ¶
Catch is a utility function to handle error checks for example in deferred functions It takes an error and a message, and if the error is not nil, it formats the message and panics with the error details. defer apperror.Catch(funcWithError(), "an error occurred")
func CatchCustom ¶
CatchCustom is a utility function to handle deferred error checks with a custom handler It takes a function that returns an error, a message, and a custom handler.
func Handle ¶
Handle is a utility function to handle error checks It takes an error and a message, and if the error is not nil, it formats the message and panics with the error details.
func HandleCustom ¶
HandleCustom is a utility function to handle error checks with a custom handler It takes an error, a message, and a custom handler.
func Split ¶
Split separates the error into its components: message, trace, and additional errors It returns the message, a slice of trace strings, and a slice of additional errors
Types ¶
type Error ¶
type Error struct {
Trace []string
Errors []error
Context map[string]interface{} // Additional context for the error
Message string
}
Error represents an application error with a stack trace and additional errors It implements the error interface and can be used to wrap other errors
func NewError ¶
NewError creates a new Error instance with the given message If the error is already of type Error you should use Wrap instead
func NewErrorf ¶
NewErrorf creates a new Error instance with the formatted message If the error is already of type Error you should use Wrap instead
func Parse ¶
Parse takes a string representation of an error and returns an Error instance The string should be formatted with TraceDelimiter to separate the trace entries
func (Error) AddDetail ¶
AddDetail adds a key-value pair to the error context This can be used to provide additional information about the error For example, you can add user IDs, request IDs, or any other relevant data
func (Error) AddDetails ¶
AddDetails adds multiple key-value pairs to the error context This can be used to provide additional information about the error
func (Error) Error ¶
Error implements the error interface and returns the error message If debug mode is enabled, it includes the stack trace and additional errors
func (Error) GetContext ¶
GetContext returns the context map of the error This can be used to retrieve additional information that was added to the error
func (Error) GetDetail ¶
GetDetail retrieves a value from the error context by key If the key does not exist, it returns nil
Source Files