README
¶
errors
A golang package to extend standard golang error mechanism, tracks who caused the error, helps error display and error report.
Documentation
¶
Overview ¶
Package errors Enhanced errors package, add CausedBy information. Can replace standard errors package.
Error classified by who caused the error:
- Bug: we programmers are the one responsible for the error.
- Runtime: OS, hardware, golang, code libraries, normally can be fixed by DevOp.
- External: caused by external service, or network connection.
- Input: caused by bad input.
The first two kinds can be fixed by ourself, and the last two we can not fixed must report back.
Index ¶
- Constants
- func Close(c io.Closer)
- func ForLog(v interface{}) string
- func Handle(ctx context.Context, err interface{})
- func SetHandler(h Handler)
- type CausedBy
- type CausedByError
- type Code
- type Error
- func Bug(text string) *Error
- func Bugf(text string, a ...interface{}) *Error
- func Caused(causedBy CausedBy, text string) *Error
- func Causedf(causedBy CausedBy, text string, a ...interface{}) *Error
- func ClientBug(text string) *Error
- func ClientBugf(text string, a ...interface{}) *Error
- func External(text string) *Error
- func Externalf(text string, a ...interface{}) *Error
- func Input(text string) *Error
- func Inputf(text string, a ...interface{}) *Error
- func New(text string) *Error
- func NewBug(e error) *Error
- func NewCaused(causedBy CausedBy, err error) *Error
- func NewClientBug(e error) *Error
- func NewExternal(e error) *Error
- func NewInput(e error) *Error
- func NewRuntime(e error) *Error
- func Runtime(text string) *Error
- func Runtimef(text string, a ...interface{}) *Error
- func Wrap(causedBy CausedBy, err interface{}, text string) *Error
- func Wrapf(causedBy CausedBy, err interface{}, text string, a ...interface{}) *Error
- type Handler
- type StackFrame
Constants ¶
const ( // NotError returned by GetCode() if value is nil. NotError = Code(0) // GeneralByBug generic ByBug error code GeneralByBug = Code(ByBug) // GeneralByRuntime general ByRuntime error code GeneralByRuntime = Code(ByRuntime) // GeneralByExternal general ByExternal error code GeneralByExternal = Code(ByExternal) // GeneralByInput general ByInput error code GeneralByInput = Code(ByInput) // GeneralByClientBug general ByClientBug error code GeneralByClientBug = Code(ByClientBug) )
Variables ¶
This section is empty.
Functions ¶
func Close ¶
Close close an IO closer, handle by errors.Handle() on failed.
It is very often to forget to close a closer, such as file, net connection, and very annoying to handle this kind normally won't failed error.
func ForLog ¶
func ForLog(v interface{}) string
ForLog convert value to string for better logging:
- if v is *Error, use .ErrorStack
- if v is error, use .Error()
- otherwise, use fmt.Sprint(v)
func Handle ¶
Handle use handler to handle non-nil err value. Use SetHandler() to switch handler, default handler is a plain log.Print(), if ctx is nil, pass context.Background() to error handler.
func SetHandler ¶
func SetHandler(h Handler)
SetHandler switch error handler, NOTE: no sync lock to internal handler variable, only call SetHandler in application initialization code, to prevent data race. If h is nil, reset to default handler, this feature only available in test mode for unit tests to override error handler.
Types ¶
type CausedBy ¶
type CausedBy uint32
CausedBy describe who caused this error.
const ( // ByBug error caused by a bug. This kind of error normally logged and/or // report to error report service, notify to developer. Did not show detail // error to end-user, it is not their fault, do not blame them, and apologize // for this internal error. ByBug CausedBy = (iota + 1) << 24 // ByRuntime error caused by golang runtime, such as run out of memory, file // read/write error. Any error caused by OS, or hardware. Network interface // error is caused by Runtime, error caused by network cable is not. Report // this kind of error to health monitor service, notify maintains team as // fast as possible. It not need to report to error service. ByRuntime // ByExternal error caused by depended external service, such as a Database // or other app services. Or network environment, such as lost network // connection. This kind of error is can not fixed by patching code, patching // OS, upgrade or replace hardware, they are not our error, nothing we can // do. Report to health monitor service, notify maintains team to contact // people who can fix this. // Give end-user a brief message that who caused this error that they can // understand, such as payment service, and user know this error is not // caused by us. ByExternal // ByInput error caused by bad input. A program always dealing with input, // such as user input, or a request for a service daemon. When the input is // not expected, return error with detail and precise reason. Of course, do // not need report to error report service or health monitor service. ByInput // ByClientBug error caused by wrong implemented client software, such as // wrong argument. ByInput is error caused by user. Normally ByClientBug not // report to health/crash report service. ByClientBug // NoError is a special value returned by GetPanicCausedBy() to indicate no // error happened NoError )
func GetCausedBy ¶
GetCausedBy from any error. If the error is Error interface, call its CausedBy() method. Then all considered as ByBug.
If the error is not a bug, wrap it use NewXXX() function before return:
if err := os.Open("file"); err != nil {
return errors.NewRuntime(err)
}
func GetPanicCausedBy ¶
func GetPanicCausedBy(v interface{}) CausedBy
GetPanicCausedBy resolve caused for recover() return value, if the value is nil, return NoError. For error value use GetCausedBy() to resolve, other value return ByBug.
type CausedByError ¶
type CausedByError interface {
error
// Inner error maybe nil
Inner() error
Code() Code
// ErrorStack returns a string that contains both the
// error message and the callstack.
ErrorStack() string
}
CausedByError is interface provided CausedBy info. CausedByError make custom Error implementation possible.
type Code ¶
type Code uint32
Code each code is an error, first 8 bit is CausedBy.
type Error ¶
type Error struct {
Err error
// contains filtered or unexported fields
}
Error contains error, causedBy, and stack.
func ClientBugf ¶
ClientBugf sprintf version of ClientBug.
func NewBug ¶
NewBug wrap an exist error to ByBug. If e is nil, return nil. If e is already an Error, wrap it to ByBug.
func NewCaused ¶
NewCaused wraps an exist error to specified causedBy Error, If e is nil, return nil. If already an Error, returned directly if causedBy matches, re-wrap with specific causedBy if not matched.
func NewClientBug ¶
NewClientBug wrap an exist error to ByRuntime. If e is nil, return nil. If e is already an Error, wrap it to ByClientBug.
func NewExternal ¶
NewExternal wrap an exist error to ByRuntime. If e is nil, return nil. If e is already an Error, wrap it to ByExternal.
func NewInput ¶
NewInput wrap an exist error to ByRuntime. If e is nil, return nil. If e is already an Error, wrap it to ByInput.
func NewRuntime ¶
NewRuntime wrap an exist error to ByRuntime. If e is nil, return nil. If e is already an Error, wrap it to ByRuntime.
func (*Error) ErrorStack ¶
ErrorStack returns a string that contains both the error message and the callstack, and inner Error's ErrorStack().
func (*Error) Stack ¶
Stack returns the callstack formatted the same way that go does in runtime/debug.Stack()
func (*Error) StackFrames ¶
func (err *Error) StackFrames() []StackFrame
StackFrames returns an array of frames containing information about the stack.
type StackFrame ¶
type StackFrame struct {
// The path to the file containing this ProgramCounter
File string
// The LineNumber in that file
LineNumber int
// The Name of the function that contains this ProgramCounter
Name string
// The Package that contains this function
Package string
// The underlying ProgramCounter
ProgramCounter uintptr
}
A StackFrame contains all necessary information about to generate a line in a callstack.
func NewStackFrame ¶
func NewStackFrame(pc uintptr) (frame StackFrame)
NewStackFrame popoulates a stack frame object from the program counter.
func (*StackFrame) Func ¶
func (frame *StackFrame) Func() *runtime.Func
Func returns the function that contained this frame.
func (*StackFrame) SourceLine ¶
func (frame *StackFrame) SourceLine() (string, error)
SourceLine gets the line of code (from File and Line) of the original source if possible.
func (*StackFrame) String ¶
func (frame *StackFrame) String() string
String returns the stackframe formatted in the same way as go does in runtime/debug.Stack()
Source Files
Directories