README
¶
customerror
customerror provides the base block to create custom errors. It also provides built-in custom errors covering some common cases. A Custom Error provides context - a Message to an optionally wrapped Err. Additionally a Code - for example "E1010", and StatusCode can be provided. Both static (pre-created), and dynamic (in-line) errors can be easily created. Code helps a company build a catalog of errors, which helps, and improves customer service.
Install
$ go get github.com/saucelabs/customerror@vX.Y.Z
Usage
See example_test.go, and customerror_test.go file.
Documentation
Run $ make doc or check out online.
Development
Check out CONTRIBUTION.
Release
- Update CHANGELOG accordingly.
- Once changes from MR are merged.
- Tag and release.
Roadmap
Check out CHANGELOG.
Documentation
¶
Overview ¶
Package customerror provides the base block to create custom errors. It also provides built-in custom errors covering some common cases. A Custom Error provides context - a `Message` to an optionally wrapped `Err`. Additionally a `Code` - for example "E1010", and `StatusCode` can be provided. Both static (pre-created), and dynamic (in-line) errors can be easily created. `Code` helps a company build a catalog of errors, which helps, and improves customer service.
Examples:
See `example_test.go` or the Example section of the GoDoc documention.
Index ¶
- func NewFailedToError(message string, code string, err error) error
- func NewInvalidError(message string, code string, err error) error
- func NewMissingError(message string, code string, err error) error
- func NewRequiredError(message string, code string, err error) error
- func Wrap(customError error, errors ...error) error
- type CustomError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewFailedToError ¶
NewFailedToError is the building block for errors usually thrown when some action failed, e.g: "Failed to create host". Default status code is `500`.
Note: Status code can be redefined, call `SetStatusCode`.
func NewInvalidError ¶
NewInvalidError is the building block for errors usually thrown when something fail validation, e.g: "Invalid port". Default status code is `400`.
Note: Status code can be redefined, call `SetStatusCode`.
func NewMissingError ¶
NewMissingError is the building block for errors usually thrown when required information is missing, e.g: "Missing host". Default status code is `400`.
Note: Status code can be redefined, call `SetStatusCode`.
func NewRequiredError ¶
NewRequiredError is the building block for errors usually thrown when required information is missing, e.g: "Port is required". Default status code is `400`.
Note: Status code can be redefined, call `SetStatusCode`.
Types ¶
type CustomError ¶
type CustomError struct {
// Code can be any custom code, e.g.: E1010.
Code string `json:"code" validate:"omitempty,startswith=E,gte=2"`
// Err optionally wraps the original error.
Err error `json:"-"`
// Human readable message. Minimum length: 3.
Message string `json:"message" validate:"required,gte=3"`
// StatusCode is a valid HTTP status code, e.g.: 404.
StatusCode int `json:"-" validate:"omitempty,gte=100,lte=511"`
}
CustomError is the base block to create custom errors. It provides context - a `Message` to an optional `Err`. Additionally a `Code` - for example "E1010", and `StatusCode` can be provided.
func New ¶
func New(message, code string, statusCode int, err error) *CustomError
New creates custom errors. `message` is required. Failing to satisfy that will throw a fatal error.
Example ¶
Demonstrates how to create static, and dynamic custom errors, also how to check, and instrospect custom errors.
// Custom static error definition.
ErrMissingID := NewMissingError("id", "E1010", nil)
// Some function, for demo purpose.
SomeFunc := func(id string) error {
if id == "" {
// Usage of the custom static error.
return ErrMissingID
}
// Dynamic custom error.
return NewFailedToError("write to disk", "E1523", nil)
}
// Case: Without `id`, returns `ErrMissingID`.
if err := SomeFunc(""); err != nil {
fmt.Println(errors.Is(err, ErrMissingID)) // true
var cE *CustomError
if errors.As(err, &cE) {
fmt.Println(cE.StatusCode) // 400
}
fmt.Println(err) // E1010: missing id (400 - Bad Request)
}
// Case: With `id`, returns dynamic error.
if err := SomeFunc("12345"); err != nil {
var cE *CustomError
if errors.As(err, &cE) {
fmt.Println(cE.StatusCode) // 500
}
fmt.Println(err) // E1523: failed to write to disk (500 - Internal Server Error)
}
Output: true 400 E1010: missing id (400 - Bad Request) 500 E1523: failed to write to disk (500 - Internal Server Error)
func (*CustomError) Error ¶
func (cE *CustomError) Error() string
Error interface implementation returns the properly formatted error message.
func (*CustomError) SetStatusCode ¶
func (cE *CustomError) SetStatusCode(code int) *CustomError
SetStatusCode sets the status code.
Note: Calling this on a static error is dangerous as it will change the status code of all its references!
func (*CustomError) Unwrap ¶
func (cE *CustomError) Unwrap() error
Unwrap interface implementation returns inner error.
Source Files