Documentation
¶
Overview ¶
Package errors кастомная реализация жизненного цикла ошибки. Кроме стандартных свойств и методов реализовано логгирование и перевод сообщения. В сообщение об ошибке можно также добавить Тип, Уровень важности, Информационный контекст, Операции.
Index ¶
- Variables
- func As(err error, target interface{}) bool
- func Caller(depth int) func() string
- func Combine(errors ...error) error
- func CombineWithLog(errs ...error) error
- func Contains(err error, id string) bool
- func ErrorOrNil(err error) error
- func Errors(err error) []error
- func GetErrorType(err error) string
- func GetID(err error) (id string)
- func Is(err, target error) bool
- func JSONFormat(buf io.Writer, e *Error)
- func JSONMultierrFuncFormat(w io.Writer, es []error)
- func Log(err error, l ...multilog.Logger)
- func StringFormat(buf io.Writer, e *Error)
- func StringMultierrFormatFunc(w io.Writer, es []error)
- func Unwrap(err error) error
- func Wrap(left error, right error) error
- func WrapWithLog(olderr error, err error) error
- type CtxMap
- type Error
- func (e *Error) As(target interface{}) bool
- func (e *Error) ContextInfo() CtxMap
- func (e *Error) Error() string
- func (e *Error) ErrorOrNil() error
- func (e *Error) ErrorType() Objecter
- func (e *Error) Format(s fmt.State, verb rune)
- func (e *Error) ID() Objecter
- func (e *Error) Is(target error) bool
- func (e *Error) Localizer() *i18n.Localizer
- func (e *Error) Log(l ...multilog.Logger)
- func (e *Error) Msg() Objecter
- func (e *Error) Operations() Objects
- func (e *Error) Sdump() string
- func (e *Error) Severity() Severity
- func (e *Error) TranslateContext() *TranslateContext
- func (e *Error) TranslateMsg() string
- func (e *Error) Unwrap() error
- func (e *Error) WithOptions(ops ...Options) *Error
- func (e *Error) WriteTranslateMsg(w io.Writer) (int, error)
- type FormatFn
- type MultierrFormatFn
- type Multierror
- type Objecter
- type Objects
- type Options
- func AppendContextInfo(key string, value interface{}) Options
- func AppendOperations(o ...string) Options
- func AppendOperationsBytes(o ...[]byte) Options
- func SetContextInfo(ctxinf CtxMap) Options
- func SetErrorType(etype string) Options
- func SetErrorTypeBytes(etype []byte) Options
- func SetFormatFn(fn FormatFn) Options
- func SetID(id string) Options
- func SetIDBytes(id []byte) Options
- func SetLocalizer(localizer *i18n.Localizer) Options
- func SetMsg(msg string) Options
- func SetMsgBytes(msg []byte) Options
- func SetOperations(o ...string) Options
- func SetOperationsBytes(o ...[]byte) Options
- func SetSeverity(severity Severity) Options
- func SetSeverityErr() Options
- func SetSeverityWarn() Options
- func SetTranslateContext(tctx *TranslateContext) Options
- type Severity
- type TranslateContext
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultFormatFn функция форматирования, используемая по-умолчанию DefaultFormatFn FormatFn //nolint:gochecknoglobals // DefaultMultierrFormatFunc функция форматирования для multierr ошибок. DefaultMultierrFormatFunc MultierrFormatFn //nolint:gochecknoglobals )
var DefaultCaller = Caller(3) //nolint:gochecknoglobals
DefaultCaller is a Valuer that returns the file and line where the Log method was invoked. It can only be used with log.With.
var DefaultLocalizer *i18n.Localizer //nolint:gochecknoglobals
DefaultLocalizer локализатор по-умолчанию. Для каждой ошибки можно переопределить локализатор.
var ErrNotValidSeverity = origerrors.New("not a valid severity")
ErrNotValidSeverity ошибка валидации типа Severuty.
Functions ¶
func As ¶
As обнаруживает ошибку err, соответствующую типу target и устанавливает target в найденное значение.
func Caller ¶
Caller returns a Valuer that returns a file and line from a specified depth in the callstack. Users will probably want to use DefaultCaller.
func Combine ¶
Combine создаст цепочку ошибок из ошибок ...errors. Допускается использование `nil` в аргументах.
func CombineWithLog ¶
CombineWithLog как и Combine создаст или дополнит цепочку ошибок err с помощью errs, но при этом будет осуществлено логгирование с помощь логгера по-умолчанию.
Example ¶
Добавление ошибок в mutierror с логгированием тут изменена функция форматирования вывода -- испльзуется json
package main
import (
"log"
"os"
"github.com/ovsinc/errors"
"github.com/ovsinc/multilog"
"github.com/ovsinc/multilog/golog"
)
func itsOk() error {
return nil
}
func itsErr(s string) error {
return errors.New(s)
}
func main() {
multilog.DefaultLogger = golog.New(log.New(os.Stdout, "ovsinc/errors ", 0))
_ = errors.CombineWithLog(
nil,
itsOk(),
itsErr("one"),
itsErr("two"),
itsOk(),
)
}
Output: ovsinc/errors the following errors occurred: #0 one #1 two
func Contains ¶
Contains проверит есть ли в цепочке ошибка с указанным ID. Допускается в качестве аргумента err указывать одиночную ошибку.
func ErrorOrNil ¶
ErrorOrNil вернет ошибку или nil Возможна обработка multierror или одиночной ошибки (*Error, error). Если хотя бы одна ошибка в цепочке является ошибкой, то она будет возвращена в качестве результата. В противном случае будет возвращен nil. Важно: *Error c Severity Warn не является ошибкой.
Example ¶
Накопление результатов выполнения каких-либо функций спроверкой на НЕ nil
package main
import (
"fmt"
"github.com/ovsinc/errors"
)
func itsOk() error {
return nil
}
func itsErr(s string) error {
return errors.New(s)
}
func main() {
errors.DefaultMultierrFormatFunc = errors.StringMultierrFormatFunc
var err error
err = errors.Combine(
nil,
itsOk(),
itsErr("one"),
errors.New("two", errors.SetSeverity(errors.SeverityWarn)),
itsOk(),
)
err = errors.Wrap(err, errors.New("three", errors.SetSeverity(errors.SeverityWarn)))
fmt.Printf("%v\n", errors.ErrorOrNil(err))
}
Output: one
func Errors ¶
Errors returns a slice containing zero or more errors that the supplied error is composed of. If the error is nil, a nil slice is returned.
err := multierr.Append(r.Close(), w.Close()) errors := multierr.Errors(err)
If the error is not composed of other errors, the returned slice contains just the error that was passed in.
Callers of this function are free to modify the returned slice.
func GetErrorType ¶
GetErrorType возвращает тип ошибки. Для НЕ *Error всегда будет "".
Example ¶
package main
import (
"fmt"
"github.com/ovsinc/errors"
)
var UnknownErrorType = errors.NewObjectFromString("UNKNOWN_TYPE")
func someErrFunc() error {
return errors.New("connection error", errors.SetErrorType("NOT_FOUND"))
}
func main() {
errors.DefaultMultierrFormatFunc = errors.StringMultierrFormatFunc
err := someErrFunc()
switch errors.GetErrorType(err) {
case "NOT_FOUND":
fmt.Printf("Got error with type NOT_FOUND")
case UnknownErrorType.String():
fmt.Printf("Got error with type %s", UnknownErrorType.String())
default:
fmt.Printf("Got some unknown")
}
}
Output: Got error with type NOT_FOUND
func Is ¶
Is сообщает, соответствует ли ошибка err target-ошибке. Для multierr будет производится поиск в цепочке.
func JSONFormat ¶
JSONFormat функция форматирования вывода сообщения *Error в JSON.
func JSONMultierrFuncFormat ¶
JSONMultierrFuncFormat функция форматирования вывода сообщения для multierr в виде JSON.
func Log ¶
Log выполнить логгирование ошибки err с ипользованием логгера l[0]. Если l не указан, то в качестве логгера будет использоваться логгер по-умолчанию.
Example ¶
package main
import (
"log"
"os"
"time"
"github.com/ovsinc/errors"
"github.com/ovsinc/multilog"
"github.com/ovsinc/multilog/golog"
)
func someTimedCast() (err error) {
begin := time.Now()
defer func() {
err = errors.Cast(err).
WithOptions(errors.SetContextInfo(
errors.CtxMap{
"duration": time.Since(begin).Round(time.Second),
"call": errors.DefaultCaller(),
},
))
}()
err = errors.New("some call")
time.Sleep(1 * time.Second)
return err
}
func main() {
multilog.DefaultLogger = golog.New(log.New(os.Stdout, "ovsinc/errors ", 0))
errors.DefaultMultierrFormatFunc = errors.StringMultierrFormatFunc
errors.Log(someTimedCast())
}
Output: ovsinc/errors <call:example_test.go:165,duration:1s> -- some call
func StringFormat ¶
StringFormat функция форматирования вывода сообщения *Error в виде строки. Используется по-умолчанию.
func StringMultierrFormatFunc ¶
StringMultierrFormatFunc функция форматирования вывода сообщения для multierr в виде строки. Используется по-умолчанию.
func Wrap ¶
Wrap обернет ошибку `left` ошибкой `right`, получив цепочку. Допускается использование `nil` в одном из аргументов.
Example ¶
package main
import (
"fmt"
"github.com/ovsinc/errors"
)
func someFuncWithErr() error {
return errors.New(
"connection error",
errors.SetContextInfo(errors.CtxMap{"hello": "world"}),
errors.AppendOperations("write"),
errors.SetSeverity(errors.SeverityUnknown),
errors.SetErrorType(""),
)
}
func someFuncWithErr2() error {
return errors.New(
"connection error",
errors.SetSeverity(errors.SeverityUnknown),
errors.SetErrorType(""),
)
}
func main() {
errors.DefaultMultierrFormatFunc = errors.StringMultierrFormatFunc
err := someFuncWithErr()
err = errors.Wrap(err, someFuncWithErr2())
fmt.Printf("%v\n", err)
}
Output: the following errors occurred: #0 [write]<hello:world> -- connection error #1 connection error
func WrapWithLog ¶
WrapWithLog обернет ошибку olderr в err и вернет цепочку, но при этом будет осуществлено логгирование с помощь логгера по-умолчанию.
Types ¶
type CtxMap ¶
type CtxMap map[string]interface{}
CtxMap map контекста ошибки. В качестве ключа всегда должна быть строка, а значение - любой тип. При преобразовании ошибки в строку CtxMap может использоваться различные методы. Для функции JSONFormat CtxMap будет преобразовываться с помощью JSON marshall. Для функции StringFormat CtxMap будет преобразовываться с помощью fmt.Sprintf.
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error структура кастомной ошибки. Это потоко-безопасный объект.
func Cast ¶
Cast преобразует тип error в *Error Если error не соответствует *Error, то будет создан *Error с сообщением err.Error(). Для err == nil, вернется nil.
func New ¶
New конструктор на необязательных параметрах * ops ...Options -- параметризация через функции-парметры. См. options.go
** *Error
Example ¶
package main
import (
"fmt"
"github.com/ovsinc/errors"
)
func main() {
e := errors.New("hello world")
fmt.Println(e)
}
Output: hello world
func NewWithLog ¶
NewWithLog конструктор *Error, как и New, но при этом будет осуществлено логгирование с помощь логгера по-умолчанию.
Example ¶
package main
import (
"log"
"os"
"github.com/ovsinc/errors"
"github.com/ovsinc/multilog"
"github.com/ovsinc/multilog/golog"
)
func itsOk() error {
return nil
}
func main() {
multilog.DefaultLogger = golog.New(log.New(os.Stdout, "ovsinc/errors ", 0))
errors.DefaultMultierrFormatFunc = errors.StringMultierrFormatFunc
_ = errors.Combine(
nil,
itsOk(),
errors.NewWithLog("one"),
errors.NewWithLog("two"),
itsOk(),
)
_ = errors.NewWithLog("three")
}
Output: ovsinc/errors one ovsinc/errors two ovsinc/errors three
func UnwrapByID ¶
UnwrapByID вернет ошибку (*Error) с указанным ID. Если ошибка с указанным ID не найдена, вернется nil.
func (*Error) ContextInfo ¶
ContextInfo вернет контекст CtxMap ошибки.
func (*Error) Error ¶
Error возвращает строковое представление ошибки. Метод для реализации интерфейса error. Метод произволит перевод сообщения об ошибки, если localizer != nil. Для идентификации сообщения перевода используется ID ошибки.
func (*Error) ErrorOrNil ¶
ErrorOrNil вернет ошибку или nil. ошибкой считается *Error != nil и Severity == SeverityError т.е. SeverityWarn НЕ ошибка
func (*Error) ErrorType ¶
ErrorType вернет тип ошибки. Это безопасный метод, всегда возвращает не nil.
func (*Error) Log ¶
Log выполнит логгирование ошибки с ипользованием логгера l[0]. Если l не указан, то в качестве логгера будет использоваться логгер по-умолчанию.
func (*Error) Msg ¶
Msg возвращает исходное сообщение об ошибке. Это безопасный метод, всегда возвращает не nil.
func (*Error) Operations ¶
Operations вернет список операций. Это безопасный метод, всегда возвращает не nil.
func (*Error) TranslateContext ¶
func (e *Error) TranslateContext() *TranslateContext
TranslateContext вернет *TranslateContext.
func (*Error) TranslateMsg ¶
TranslateMsg вернет перевод сообщения ошибки. Если не удастся выполнить перевод, вернет оригинальное сообщение.
Example ¶
package main
import (
"fmt"
"github.com/BurntSushi/toml"
"github.com/nicksnyder/go-i18n/v2/i18n"
"github.com/ovsinc/errors"
"golang.org/x/text/language"
)
func localizePrepare() *i18n.Localizer {
bundle := i18n.NewBundle(language.English)
bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal)
bundle.MustLoadMessageFile("./internal/examples/translate/testdata/active.ru.toml")
return i18n.NewLocalizer(bundle, "es", "ru", "en")
}
func localTransContext() errors.TranslateContext {
var (
unreadEmailCount = 5
name = "John Snow"
)
return errors.TranslateContext{
TemplateData: map[string]interface{}{
"Name": name,
"PluralCount": unreadEmailCount,
},
PluralCount: unreadEmailCount,
}
}
func main() {
errEmailsUnreadMsg := localTransContext()
localizer := localizePrepare()
e1 := errors.New(
"fallback message",
errors.SetID("ErrEmailsUnreadMsg"),
errors.SetErrorType("not found"),
errors.SetTranslateContext(&errEmailsUnreadMsg),
errors.SetLocalizer(localizer),
)
fmt.Printf("%v\n", e1)
fmt.Println(e1.Error())
fmt.Print(e1.TranslateMsg())
}
Output: (not found) -- У John Snow имеется 5 непрочитанных сообщений. (not found) -- У John Snow имеется 5 непрочитанных сообщений. У John Snow имеется 5 непрочитанных сообщений.
func (*Error) WithOptions ¶
WithOptions производит параметризацию *Error с помощью функции-парметры Options. Допускается указывать произвольно количество ops. Возвращается новый экземпляр *Error.
Example ¶
package main
import (
"fmt"
"strconv"
"sync"
"github.com/ovsinc/errors"
)
func main() {
e1 := errors.New("hello")
wg := &sync.WaitGroup{}
for i := 0; i < 10; i++ {
wg.Add(1)
i := i
go func() {
defer wg.Done()
_ = e1.WithOptions(
errors.SetMsg("new error " + strconv.Itoa(i)),
)
}()
}
wg.Wait()
e2 := e1.WithOptions(
errors.AppendContextInfo("hello", "world"),
errors.AppendOperations("test op"),
errors.SetErrorType("test type"),
)
fmt.Println(e1.Error())
fmt.Println(e2.Error())
}
Output: hello (test type)[test op]<hello:world> -- hello
type MultierrFormatFn ¶
MultierrFormatFn типу функции морматирования для multierr.
type Multierror ¶
type Objecter ¶
func NewObjectEmpty ¶
func NewObjectEmpty() Objecter
func NewObjectFromBytes ¶
func NewObjectFromString ¶
type Objects ¶
type Objects []Objecter
func NewObjects ¶
func NewObjectsFromBytes ¶
func NewObjectsFromString ¶
func (Objects) AppendBytes ¶
func (Objects) AppendString ¶
type Options ¶
type Options func(e *Error)
Options опции из параметра ошибки.
func AppendContextInfo ¶
AppendContextInfo добавить в имеющийся CtxMap значение value по ключу key. Если CtxMap в *Error не установлен, то он будет предварительно установлен.
func AppendOperations ¶
AppendOperations добавить операции, указанные как строки. Можно указать произвольное количество. Если в *Error уже были записаны операции, то указанные в аргументе будет добавлены к уже имеющимся.
func AppendOperationsBytes ¶
AppendOperationsBytes добавить операции, указанные как []byte. Можно указать произвольное количество. Если в *Error уже были записаны операции, то указанные в аргументе будет добавлены к уже имеющимся.
func SetErrorTypeBytes ¶
SetErrorTypeBytes установит тип ошибки.
func SetFormatFn ¶
SetFormatFn установит пользовательскую функцию-форматирования.
func SetLocalizer ¶
SetLocalizer установит локализатор. Этот локализатор будет использован для данной ошибки даже, если был установлен DefaultLocalizer.
func SetMsgBytes ¶
SetMsgBytes установит сообщение об ошибке, указаннов в виде []byte.
func SetOperations ¶
SetOperations установить операции, указанные как строки. Можно указать произвольное количество. Если в *Error уже были записаны операции, то они будут заменены на указанные в аргументе ops.
func SetOperationsBytes ¶
SetOperationsBytes установить операции, указанные как []byte. Можно указать произвольное количество. Если в *Error уже были записаны операции, то они будут заменены на указанные в аргументе ops.
func SetSeverityErr ¶
func SetSeverityErr() Options
func SetSeverityWarn ¶
func SetSeverityWarn() Options
func SetTranslateContext ¶
func SetTranslateContext(tctx *TranslateContext) Options
SetTranslateContext установит контекст переревода
type Severity ¶
type Severity uint32
Severity ENUM тип определения Severity.
const ( // SeverityUnknown не инициализированное значение, использовать не допускается. SeverityUnknown Severity = iota // SeverityWarn - предупреждение. Не является ошибкой по факту. SeverityWarn // SeverityError - ошибка. SeverityError // SeverityEnds терминирующее значение, использовать не допускается. SeverityEnds )
func ParseSeverityString ¶
ParseSeverityString парсит severity по строке. В случае ошибки парсинга, функция вернет SeverityUnknown и ошибку.
func ParseSeverityUint ¶
ParseSeverityUint парсит severity по uint32. В случае ошибки парсинга, функция вернет SeverityUnknown и ошибку.
func (Severity) Bytes ¶
Bytes получить представление типа Severity в []byte. Для не корректных значение будет возвращено UNKNOWN.
type TranslateContext ¶
type TranslateContext struct {
// TemplateData - map для замены в шаблоне
TemplateData map[string]interface{}
// PluralCount признак множественности.
// Может иметь значение nil или число.
PluralCount interface{}
// DefaultMessage сообщение, которое будет использовано при ошибке перевода.
DefaultMessage *i18n.Message
}
TranslateContext контекст перевода. Не является обязательным для корректного перевода.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
examples/log
command
|
|
|
examples/multi
command
|
|
|
examples/simple
command
|
|
|
examples/translate
command
|