errorKit

Documentation

Overview

Package errorKit

极客时间的"Go error处理最佳实践": https://u.geekbang.org/lesson/376?article=513711

输出带有堆栈的error时，建议使用: logrusKit.PrintError 或 logrusKit.PrintErrorWithLogger.

使用时的注意点: (a) 在应用代码（业务代码）中，使用 errorKit.New 返回错误； (b) 在项目工程里面，如果调用其它包内的函数，通常简单的直接返回error，即向上抛; (c) 如果和其它库（第三方库、标准库）进行协作，考虑使用 errorKit.Wrap 保存堆栈信息； (d) 不要到处打日志（比如每个错误产生的地方），直接往上抛的情况不需要打日志； (e) 在 程序的顶部 或 工作的goroutine顶部（请求入口），使用 %+v 输出堆栈详情. (f) 使用 errorKit.Cause 获取root error，再和sentinel error判定. (g) 如果你的函数不打算处理这个错误，你没法处理，那么应该携带上足够多的上下文，然后往上抛；（Wrap errors） (h) 如果错误被处理了，那么它就不应该被往上抛并且记日志，

如果是 第三方库 或 基础库（被很多人使用并且是跨很多项目的）， (a) 应该返回 root error，它的原始错误是什么就是什么； (b) 如果返回的新的error，应该使用 errorKit.Simple 来创建error； (c) errorKit.New、errorKit.Wrap 和 errorKit.WithMessage: 业务代码可以使用，第三方库和基础库不应该使用（以避免保存多次堆栈信息，太冗余了）；

Index

• Variables
• func New(format string, args ...interface{}) error
• func NewSkip(skip int, format string, args ...interface{}) error
• func Wrap(err error, format string, args ...interface{}) error

Variables

var (
	// Is 传参err 的错误链中，是否存在和 传参target 匹配的error实例？
	/*
		reports whether any error in err's tree matches target.

		PS: 支持第三方依赖 "github.com/gogf/gf/v2/errors/gerror".
	*/
	Is func(err, target error) bool = errors.Is

	// As
	/*
		查找 传参err 的错误链中与 传参target 匹配的第一个错误，
		(1) 如果找到，则 将 传参target 设置为该错误值 && 返回true
		(2) 否则 返回false。

		finds the first error in err's tree that matches target, and if one is found, sets
		target to that error value and returns true. Otherwise, it returns false.

		PS: 支持第三方依赖 "github.com/gogf/gf/v2/errors/gerror".

		@param target 	(1) 不能为nil，否则会 panic
						(2) 必须是指针类型，否则会 panic
	*/
	As func(err error, target any) bool = errors.As

	// Equal 错误比较
	Equal func(err, target error) bool = gerror.Equal

	// HasStack 判断错误是否带堆栈
	HasStack func(err error) bool = gerror.HasStack

	// Stack 获取堆栈信息
	Stack func(err error) string = gerror.Stack

	// Current 获取当前error
	Current func(err error) error = gerror.Current

	// Unwrap 获取层级错误的下一级错误error接口对象(当下一层级不存在时，返回nil)
	Unwrap func(err error) error = gerror.Unwrap

	// Cause 获取根错误error
	Cause func(err error) error = gerror.Cause
)

Functions

func New

func New(format string, args ...interface{}) error

New 用于创建一个自定义错误信息的error对象，并包含堆栈信息.

func NewSkip

func NewSkip(skip int, format string, args ...interface{}) error

NewSkip 用于创建一个自定义错误信息的error对象，并且忽略部分堆栈信息（按照当前调用方法位置往上忽略）。高级功能，一般开发者很少用得到.

@param skip (1) >=0
			(2) 0: 等价于 New || New
			(2) 1: 跳过1层（e.g. assert工具类）

func Wrap

func Wrap(err error, format string, args ...interface{}) error

Wrap 用于包裹其他错误error对象，构造成多级的错误信息，包含堆栈信息.