errors

README

errors

errors with stack, supports multi-cause error format as tree, inspired by cockroachdb/errors

博客：造一个 Go 语言错误库的轮子

Example

package main

import (
	stdErr "errors"
	"fmt"
	"testing"

	"code.gopub.tech/errors"
	cdbErr "github.com/cockroachdb/errors"
	pkgErr "github.com/pkg/errors"
)

func TestErrors(t *testing.T) {
	var (
		errStd  = stdErr.New("err-std\nnew\nline")
		errPkg  = pkgErr.New("err-pkg\nnew\nline")
		errCdb  = cdbErr.New("err-cdb\nnew\nline")
		errThis = errors.New("err-this\nnew\nline")
	)
	fmt.Printf("%+v\n", errors.Wrap(errors.Join(errStd, errPkg, errCdb, errThis), "prefix"))
}

Output

prefix: err-std
new
line
err-pkg
new
line
err-cdb
new
line
err-this
new
line
(1) attached stack trace
 │ -- stack trace:
 │ code.gopub.tech/example.TestErrors
 │ 	/go/src/code.gopub.tech/example/main_test.go:20
 │ [...repeated from below...]
Next: (2) prefix
Next: (3) attached stack trace
 │ -- stack trace:
 │ code.gopub.tech/example.TestErrors
 │ 	/go/src/code.gopub.tech/example/main_test.go:20
 │ [...repeated from below...]
Next: (4) err-std
 │ new
 │ line
 │ err-pkg
 │ new
 │ line
 │ err-cdb
 │ new
 │ line
 │ err-this
 │ new
 │ line
 ├─ Wraps: (5) err-std
 │  │  new
 │  └─ line
 ├─ Wraps: (6) err-pkg
 │  │  new
 │  │  line
 │  │  -- stack trace:
 │  │  code.gopub.tech/example.TestErrors
 │  │  	/go/src/code.gopub.tech/example/main_test.go:16
 │  └─ [...repeated from below...]
 ├─ Wraps: (7) attached stack trace
 │  │ -- stack trace:
 │  │ code.gopub.tech/example.TestErrors
 │  │ 	/go/src/code.gopub.tech/example/main_test.go:17
 │  │ [...repeated from below...]
 │ Next: (8) err-cdb
 │  │  new
 │  └─ line
 └─ Wraps: (9) err-this
    │  new
    │  line
    │  -- stack trace:
    │  code.gopub.tech/example.TestErrors
    │  	/go/src/code.gopub.tech/example/main_test.go:18
    │  testing.tRunner
    │  	/sdk/go1.21.6/src/testing/testing.go:1595
    │  runtime.goexit
    └─ 	/sdk/go1.21.6/src/runtime/asm_amd64.s:1650
Error types: (1) *errors.withStack (2) *errors.withPrefix (3) *errors.withStack (4) *errors.joinError (5) *errors.errorString (6) *errors.fundamental (7) *withstack.withStack (8) *errutil.leafError (9) *errors.fundamental

License

Documentation

Index

• func As(err error, target any) bool
• func Cause(err error) error
• func Detail(err error) string
• func ElideSharedStackTraceSuffix(prevStack, newStack []uintptr) ([]uintptr, bool)
• func Errorf(format string, args ...any) error
• func FormatError(err error, s fmt.State, verb rune)
• func GetStackTrace(err error) (st []uintptr, ok bool)
• func Is(err, target error) bool
• func Join(errs ...error) error
• func New(msg string) error
• func StackDetail(st []uintptr) string
• func Unwrap(err error) error
• func UnwrapAll(err error) error
• func UnwrapMulti(err error) []error
• func UnwrapOnce(err error) error
• func WithMessage(err error, msg string) error
• func WithMessagef(err error, format string, args ...any) error
• func WithSecondary(err, secondary error) error
• func WithStack(err error) error
• func Wrap(err error, msg string) error
• func Wrapf(err error, format string, args ...any) error
• type ErrorPrinter
• type FormattableError
  • func F(err error) FormattableError
  • func Formattable(err error) FormattableError
• type Printer

Functions

func As

func As(err error, target any) bool

func Cause

func Cause(err error) error

Cause 获取最内层错误

func Detail

func Detail(err error) string

Detail 先将 err 包装为 Formattable 再使用 %+v 格式化为字符串

func ElideSharedStackTraceSuffix

func ElideSharedStackTraceSuffix(prevStack, newStack []uintptr) ([]uintptr, bool)

ElideSharedStackTraceSuffix 省略共同的堆栈

func Errorf

func Errorf(format string, args ...any) error

Errorf 按指定格式新建一个错误实例，带堆栈

func FormatError

func FormatError(err error, s fmt.State, verb rune)

FormatError 能够识别格式化动词智能打印。 当一个错误类型在实现 fmt.Formatter 接口时，可以直接转发给本函数。

如果传入的错误类型实现了 errors.Formatter 接口， FormatError 会使用‘按 s, verb 配置好的 Printer’ 调用它的 FormatError 方法。

否则，如果错误类型是一个包装类型（实现了 Cause/Unwrap） FormatError 会输出包装错误的附加信息，并递归地处理其内部错误。

其他情况，直接打印 Error() 文本。

func GetStackTrace

func GetStackTrace(err error) (st []uintptr, ok bool)

GetStackTrace 获取错误上附加的堆栈 兼容 pkg/errors, cockroachdb/errors (通过反射)

func Is

func Is(err, target error) bool

func Join

func Join(errs ...error) error

Join 聚合多个错误

func New

func New(msg string) error

New 新建一个错误实例，带堆栈

func StackDetail

func StackDetail(st []uintptr) string

StackDetail 获取堆栈详情

func Unwrap

func Unwrap(err error) error

Unwrap 获取内层错误

func UnwrapAll

func UnwrapAll(err error) error

func UnwrapMulti

func UnwrapMulti(err error) []error

func UnwrapOnce

func UnwrapOnce(err error) error

func WithMessage

func WithMessage(err error, msg string) error

WithMessage 给错误添加一个前缀注解信息

func WithMessagef

func WithMessagef(err error, format string, args ...any) error

WithMessagef 给错误添加一个指定格式的前缀注解信息

func WithSecondary

func WithSecondary(err, secondary error) error

WithSecondary 给错误附加一个次要错误。 次要错误仅在使用 %+v 格式化动词时才会打印

func WithStack

func WithStack(err error) error

WithStack 为错误添加堆栈信息

func Wrap

func Wrap(err error, msg string) error

Wrap 使用指定的前缀信息包装一个错误，带堆栈

func Wrapf

func Wrapf(err error, format string, args ...any) error

Wrapf 使用指定格式的前缀信息包装一个错误，带堆栈

Types

type ErrorPrinter

type ErrorPrinter interface {
	error
	// PrintError 输出错误信息.
	// 使用 Print, Printf 输出的错误信息总是可见;
	// 使用 PrintDetail, PrintDetailf 输出错误信息仅在 %+v 格式下可见.
	//
	// 返回的 next error 如果为 nil 代表在拼接简单消息时，仅输出本 error 而忽略 cause.
	//
	// 如一个 withPrefix 结构的错误实例，应在 Print 自身消息后，再返回 cause;
	// 而一个 withNewMessage 结构的错误实例，在 Print 自身消息后，会返回 nil.
	//
	// 在 %+v 详细格式下，不管返回的 next error 是否为 nil，都会输出其 cause.
	PrintError(p Printer) (next error)
}

type FormattableError

type FormattableError interface {
	error
	fmt.Formatter
}

func F

func F(err error) FormattableError

F is alias of Formattable 将一个错误包装为 fmt.Formatter

func Formattable

func Formattable(err error) FormattableError

Formattable 将一个错误包装为 fmt.Formatter 标准库中的 wrapErrors, joinerrors 并没有实现 fmt.Formatter 接口 使用这个帮助函数可以让那些错误类型也支持智能打印功能（自动解析 cause 等）

type Printer

type Printer interface {
	Print(args ...any)
	Printf(format string, args ...any)
	PrintDetail(args ...any)
	PrintDetailf(format string, args ...any)
}