errors

package module
v1.2.3 Latest Latest
Warning

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

Go to latest
Published: May 31, 2021 License: Apache-2.0 Imports: 13 Imported by: 5

README

Errors

codecov Go Report Card Go Reference license

Package errors implements custom functions to manipulate errors.

In this package uses the strategy accepted in the github.com/pkg/errors and in the whole of golang. It is compatible with the standard `errors ' package.

See README russian.

Documentation

Overview

Package errors кастомная реализация жизненного цикла ошибки. Кроме стандартных свойств и методов реализовано логгирование и перевод сообщения. В сообщение об ошибке можно также добавить Тип, Уровень важности, Информационный контекст, Операции.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// DefaultFormatFn функция форматирования, используемая по-умолчанию
	DefaultFormatFn FormatFn //nolint:gochecknoglobals

	// DefaultMultierrFormatFunc функция форматирования для multierr ошибок.
	DefaultMultierrFormatFunc MultierrFormatFn //nolint:gochecknoglobals

)
View Source
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.

View Source
var DefaultLocalizer *i18n.Localizer //nolint:gochecknoglobals

DefaultLocalizer локализатор по-умолчанию. Для каждой ошибки можно переопределить локализатор.

View Source
var ErrNotValidSeverity = origerrors.New("not a valid severity")

ErrNotValidSeverity ошибка валидации типа Severuty.

Functions

func As

func As(err error, target interface{}) bool

As обнаруживает ошибку err, соответствующую типу target и устанавливает target в найденное значение.

func Caller

func Caller(depth int) func() string

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

func Combine(errors ...error) error

Combine создаст цепочку ошибок из ошибок ...errors. Допускается использование `nil` в аргументах.

func CombineWithLog

func CombineWithLog(errs ...error) error

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

func Contains(err error, id string) bool

Contains проверит есть ли в цепочке ошибка с указанным ID. Допускается в качестве аргумента err указывать одиночную ошибку.

func ErrorOrNil

func ErrorOrNil(err error) error

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

func Errors(err error) []error

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

func GetErrorType(err error) string

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 GetID

func GetID(err error) (id string)

GetID возвращает ID ошибки. Для НЕ *Error всегда будет "".

func Is

func Is(err, target error) bool

Is сообщает, соответствует ли ошибка err target-ошибке. Для multierr будет производится поиск в цепочке.

func JSONFormat

func JSONFormat(buf io.Writer, e *Error)

JSONFormat функция форматирования вывода сообщения *Error в JSON.

func JSONMultierrFuncFormat

func JSONMultierrFuncFormat(w io.Writer, es []error)

JSONMultierrFuncFormat функция форматирования вывода сообщения для multierr в виде JSON.

func Log

func Log(err error, l ...multilog.Logger)

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

func StringFormat(buf io.Writer, e *Error)

StringFormat функция форматирования вывода сообщения *Error в виде строки. Используется по-умолчанию.

func StringMultierrFormatFunc

func StringMultierrFormatFunc(w io.Writer, es []error)

StringMultierrFormatFunc функция форматирования вывода сообщения для multierr в виде строки. Используется по-умолчанию.

func Unwrap

func Unwrap(err error) error

func Wrap

func Wrap(left error, right error) error

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

func WrapWithLog(olderr error, err error) error

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

func Cast(err error) *Error

Cast преобразует тип error в *Error Если error не соответствует *Error, то будет создан *Error с сообщением err.Error(). Для err == nil, вернется nil.

func New

func New(msg string, ops ...Options) *Error

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

func NewWithLog(msg string, ops ...Options) *Error

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

func UnwrapByID(err error, id string) *Error

UnwrapByID вернет ошибку (*Error) с указанным ID. Если ошибка с указанным ID не найдена, вернется nil.

func (*Error) As

func (e *Error) As(target interface{}) bool

func (*Error) ContextInfo

func (e *Error) ContextInfo() CtxMap

ContextInfo вернет контекст CtxMap ошибки.

func (*Error) Error

func (e *Error) Error() string

Error возвращает строковое представление ошибки. Метод для реализации интерфейса error. Метод произволит перевод сообщения об ошибки, если localizer != nil. Для идентификации сообщения перевода используется ID ошибки.

func (*Error) ErrorOrNil

func (e *Error) ErrorOrNil() error

ErrorOrNil вернет ошибку или nil. ошибкой считается *Error != nil и Severity == SeverityError т.е. SeverityWarn НЕ ошибка

func (*Error) ErrorType

func (e *Error) ErrorType() Objecter

ErrorType вернет тип ошибки. Это безопасный метод, всегда возвращает не nil.

func (*Error) Format

func (e *Error) Format(s fmt.State, verb rune)

Format производит форматирование строки, для поддержки fmt.Printf().

func (*Error) ID

func (e *Error) ID() Objecter

ID возвращает ID ошибки. Это безопасный метод, всегда возвращает не nil.

func (*Error) Is

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

func (*Error) Localizer

func (e *Error) Localizer() *i18n.Localizer

Localizer вернет локализатор *i18n.Localizer.

func (*Error) Log

func (e *Error) Log(l ...multilog.Logger)

Log выполнит логгирование ошибки с ипользованием логгера l[0]. Если l не указан, то в качестве логгера будет использоваться логгер по-умолчанию.

func (*Error) Msg

func (e *Error) Msg() Objecter

Msg возвращает исходное сообщение об ошибке. Это безопасный метод, всегда возвращает не nil.

func (*Error) Operations

func (e *Error) Operations() Objects

Operations вернет список операций. Это безопасный метод, всегда возвращает не nil.

func (*Error) Sdump

func (e *Error) Sdump() string

Sdump вернет текстовый дамп ошибки *Error.

func (*Error) Severity

func (e *Error) Severity() Severity

Severity возвращает критичность ошибки

func (*Error) TranslateContext

func (e *Error) TranslateContext() *TranslateContext

TranslateContext вернет *TranslateContext.

func (*Error) TranslateMsg

func (e *Error) TranslateMsg() string

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) Unwrap

func (e *Error) Unwrap() error

func (*Error) WithOptions

func (e *Error) WithOptions(ops ...Options) *Error

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

func (*Error) WriteTranslateMsg

func (e *Error) WriteTranslateMsg(w io.Writer) (int, error)

WriteTranslateMsg запишет перевод сообщения ошибки в буфер. Если не удастся выполнить перевод в буфер w будет записано оригинальное сообщение.

type FormatFn

type FormatFn func(w io.Writer, e *Error)

FormatFn тип функции форматирования.

type MultierrFormatFn

type MultierrFormatFn func(w io.Writer, es []error)

MultierrFormatFn типу функции морматирования для multierr.

type Multierror

type Multierror interface {
	Errors() []error
	Error() string
	Format(f fmt.State, c rune)
}

type Objecter

type Objecter interface {
	String() string
	Bytes() []byte
	Buffer() *bytes.Buffer
}

func NewObjectEmpty

func NewObjectEmpty() Objecter

func NewObjectFromBytes

func NewObjectFromBytes(v []byte) Objecter

func NewObjectFromString

func NewObjectFromString(s string) Objecter

type Objects

type Objects []Objecter

func NewObjects

func NewObjects(oo ...Objecter) Objects

func NewObjectsFromBytes

func NewObjectsFromBytes(vv ...[]byte) Objects

func NewObjectsFromString

func NewObjectsFromString(ss ...string) Objects

func (Objects) Append

func (os Objects) Append(oo ...Objecter) Objects

func (Objects) AppendBytes

func (os Objects) AppendBytes(vv ...[]byte) Objects

func (Objects) AppendString

func (os Objects) AppendString(ss ...string) Objects

type Options

type Options func(e *Error)

Options опции из параметра ошибки.

func AppendContextInfo

func AppendContextInfo(key string, value interface{}) Options

AppendContextInfo добавить в имеющийся CtxMap значение value по ключу key. Если CtxMap в *Error не установлен, то он будет предварительно установлен.

func AppendOperations

func AppendOperations(o ...string) Options

AppendOperations добавить операции, указанные как строки. Можно указать произвольное количество. Если в *Error уже были записаны операции, то указанные в аргументе будет добавлены к уже имеющимся.

func AppendOperationsBytes

func AppendOperationsBytes(o ...[]byte) Options

AppendOperationsBytes добавить операции, указанные как []byte. Можно указать произвольное количество. Если в *Error уже были записаны операции, то указанные в аргументе будет добавлены к уже имеющимся.

func SetContextInfo

func SetContextInfo(ctxinf CtxMap) Options

SetContextInfo установить CtxMap.

func SetErrorType

func SetErrorType(etype string) Options

SetErrorType установит тип ошибки.

func SetErrorTypeBytes

func SetErrorTypeBytes(etype []byte) Options

SetErrorTypeBytes установит тип ошибки.

func SetFormatFn

func SetFormatFn(fn FormatFn) Options

SetFormatFn установит пользовательскую функцию-форматирования.

func SetID

func SetID(id string) Options

SetID установит ID ошибки.

func SetIDBytes

func SetIDBytes(id []byte) Options

SetIDBytes установит ID ошибки.

func SetLocalizer

func SetLocalizer(localizer *i18n.Localizer) Options

SetLocalizer установит локализатор. Этот локализатор будет использован для данной ошибки даже, если был установлен DefaultLocalizer.

func SetMsg

func SetMsg(msg string) Options

SetMsg установит сообщение об ошибке, указанное в виде строки.

func SetMsgBytes

func SetMsgBytes(msg []byte) Options

SetMsgBytes установит сообщение об ошибке, указаннов в виде []byte.

func SetOperations

func SetOperations(o ...string) Options

SetOperations установить операции, указанные как строки. Можно указать произвольное количество. Если в *Error уже были записаны операции, то они будут заменены на указанные в аргументе ops.

func SetOperationsBytes

func SetOperationsBytes(o ...[]byte) Options

SetOperationsBytes установить операции, указанные как []byte. Можно указать произвольное количество. Если в *Error уже были записаны операции, то они будут заменены на указанные в аргументе ops.

func SetSeverity

func SetSeverity(severity Severity) Options

SetSeverity устновит Severity.

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

func ParseSeverityString(v string) (s Severity, err error)

ParseSeverityString парсит severity по строке. В случае ошибки парсинга, функция вернет SeverityUnknown и ошибку.

func ParseSeverityUint

func ParseSeverityUint(v uint32) (s Severity, err error)

ParseSeverityUint парсит severity по uint32. В случае ошибки парсинга, функция вернет SeverityUnknown и ошибку.

func (Severity) Bytes

func (s Severity) Bytes() (buf []byte)

Bytes получить представление типа Severity в []byte. Для не корректных значение будет возвращено UNKNOWN.

func (Severity) String

func (s Severity) String() (str string)

String получить строчное представление типа Severity. Для не корректных значение будет возвращено UNKNOWN.

func (Severity) Uint32

func (s Severity) Uint32() uint32

Uint32 конвертор в uint32

func (Severity) Valid

func (s Severity) Valid() bool

Valid проверка на валидность ENUM

type TranslateContext

type TranslateContext struct {
	// TemplateData - map для замены в шаблоне
	TemplateData map[string]interface{}
	// PluralCount признак множественности.
	// Может иметь значение nil или число.
	PluralCount interface{}
	// DefaultMessage сообщение, которое будет использовано при ошибке перевода.
	DefaultMessage *i18n.Message
}

TranslateContext контекст перевода. Не является обязательным для корректного перевода.

Directories

Path Synopsis
internal
examples/log command
examples/multi command
examples/simple command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL