errorKit

Documentation

Overview

Package errorKit

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

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

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

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

Index

• Variables
• func Newf(format string, args ...interface{}) error
• func NewfWithSkip(skip int, format string, args ...interface{}) error
• func Wrapf(err error, format string, args ...interface{}) error

Variables

var (
	// Is 传参err 的错误链中，是否存在和 传参target 匹配的error实例？
	/*
		Deprecated: 建议直接使用 errors.Is().

		reports whether any error in err's tree matches target.

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

		@param target 可以为nil
	*/
	Is func(err, target error) bool = errors.Is

	// As
	/*
		Deprecated: 建议直接使用 errors.As().

		!!!:
		对于传参target，
		(1) 如果 Error() 绑定在结构体上（receiver为"值类型"），需要 1个 '&';
		(2) 如果 Error() 绑定在结构体指针上（receiver为"指针类型"），需要 2个 '&'.

		查找 传参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 Newf

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

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

@param format !!!: 类似于fmt.Errorf()， (1) 不应该首字母大写;

(2) 不应该以标点符号结尾.

func NewfWithSkip

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

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

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

func Wrapf

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

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

@param format !!!: 类似于fmt.Errorf()， (1) 不应该首字母大写;

(2) 不应该以标点符号结尾.