2019.09.03日,Golang 1.13版本发布,这次更新算是比较大的了,有大家期待的GOPROXY和GOPRIVATE等,具体的可以去看这个版本的 Go 1.13 Release Notes

Go 1.13发布的功能还有一个值得深入研究的,就是对Error的增强,也是今天我们要分析的 Error Wrapping.

背景

做Go语言开发的,肯定经常用error,但是我们也知道error非常弱,只能自带一串文本其他什么都做不了,比如给已经存在的error增加一些附加文本,增加堆栈信息等都做不了。如果我们想给error增加一些附加文本怎么做呢?有两种办法:

第一种:

1
newErr:=fmt.Errorf("数据上传问题: %v", err)

通过fmt.Errorf函数,基于已经存在的err再生成一个新的newErr,然后附加上我们想添加的文本信息。这种办法比较方便,但是问题也很明显,我们丢失了原来的err,因为它已经被我们的fmt.Errorf函数转成一个新的字符串了。

第二种:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
func main() {
	newErr := MyError{err, "数据上传问题"}
}

type MyError struct {
	err error
	msg string
}

func (e *MyError) Error() string {
	return e.err.Error() + e.msg
}

这种方式就是我们自定义自己的struct,添加用于存储我们需要额外信息的字段,我这里是errmsg,分别存储原始err和新附加的出错信息。然后这个MyError还会实现error接口,表示他是一个error,这样我们就可以自由的使用了。

这种方式有点很明显,大家可以看到了。缺点呢,就是我们要自定义很多struct,而且我们自己定义的,和第三方的可能还不太一样,无法统一和兼容。基于这个背景,Golang 1.13 为我们提供了Error Wrapping,翻译过来我更愿意叫Error嵌套。

如何生成一个Wrapping Error

Error Wrapping,顾名思义,就是为我们提供了,可以一个error嵌套另一个error功能,好处就是我们可以根据嵌套的error序列,生成一个error错误跟踪链,也可以理解为错误堆栈信息,这样可以便于我们跟踪调试,哪些错误引起了什么问题,根本的问题原因在哪里。

因为error可以嵌套,所以每次嵌套的时候,我们都可以提供新的错误信息,并且保留原来的error。现在我们看下如何生成一个嵌套的error

1
2
e := errors.New("原始错误e")
w := fmt.Errorf("Wrap了一个错误%w", e)

Golang并没有提供什么Wrap函数,而是扩展了fmt.Errorf函数,加了一个%w来生成一个可以Wrapping Error,通过这种方式,我们可以创建一个个以Wrapping Error。

Wrapping Error原理

按照这种不丢失原error的思路,那么Wrapping Error的实现原理应该类似我们上面的自定义error.我们看下fmt.Errorf函数的源代码验证下我们的猜测是否正确。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
func Errorf(format string, a ...interface{}) error {
	//省略无关代码
	var err error
	if p.wrappedErr == nil {
		err = errors.New(s)
	} else {
		err = &wrapError{s, p.wrappedErr}
	}
	p.free()
	return err
}

这里的关键核心代码就是p.wrappedErr的判断,这个值是否存在,决定是否要生成一个wrapping error。这个值是怎么来的呢?就是根据我们设置的%w解析出来的。

有了这个值之后,就生成了一个&wrapError{s, p.wrappedErr}返回了,这里有个结构体wrapError

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
type wrapError struct {
	msg string
	err error
}

func (e *wrapError) Error() string {
	return e.msg
}

func (e *wrapError) Unwrap() error {
	return e.err
}

如上所示,和我们想的一样。实现了Error方法说明它是一个errorUnwrap方法是一个特别的方法,所有的wrapping error 都会有这么一个方法,用于获得被嵌套的error。

Unwrap 函数

Golang 1.13引入了wrapping error后,同时为errors包添加了3个工具函数,他们分别是UnwrapIsAs,先来聊聊Unwrap

顾名思义,它的功能就是为了获得被嵌套的error。

1
2
3
4
5
func main() {
	e := errors.New("原始错误e")
	w := fmt.Errorf("Wrap了一个错误%w", e)
	fmt.Println(errors.Unwrap(w))
}

以上这个例子,通过errors.Unwrap(w)后,返回的其实是个e,也就是被嵌套的那个error。 这里需要注意的是,嵌套可以有很多层,我们调用一次errors.Unwrap函数只能返回最外面的一层error,如果想获取更里面的,需要调用多次errors.Unwrap函数。最终如果一个error不是warpping error,那么返回的是nil

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
func Unwrap(err error) error {
    //先判断是否是wrapping error
	u, ok := err.(interface {
		Unwrap() error
	})
	//如果不是,返回nil
	if !ok {
		return nil
	}
	//否则则调用该error的Unwrap方法返回被嵌套的error
	return u.Unwrap()
}

看看该函数的的源代码吧,这样就会理解的更深入一些,我加了一些注释。

Is 函数

在Go 1.13之前没有wrapping error的时候,我们要判断error是不是同一个error可以使用如下办法:

1
if err == os.ErrExist

这样我们就可以通过判断来做一些事情。但是现在有了wrapping error后这样办法就不完美的,因为你根本不知道返回的这个err是不是一个嵌套的error,嵌套了几层。所以基于这种情况,Golang为我们提供了errors.Is函数。

1
func Is(err, target error) bool
  1. 如果errtarget是同一个,那么返回true
  2. 如果err 是一个wrap error,target也包含在这个嵌套error链中的话,那么也返回true

很简单的一个函数,要么咱俩相等,要么err包含target,这两种情况都返回true,其余返回false

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
func Is(err, target error) bool {
	if target == nil {
		return err == target
	}

	isComparable := reflectlite.TypeOf(target).Comparable()
	
	//for循环,把err一层层剥开,一个个比较,找到就返回true
	for {
		if isComparable && err == target {
			return true
		}
		//这里意味着你可以自定义error的Is方法,实现自己的比较代码
		if x, ok := err.(interface{ Is(error) bool }); ok && x.Is(target) {
			return true
		}
		//剥开一层,返回被嵌套的err
		if err = Unwrap(err); err == nil {
			return false
		}
	}
}

Is函数源代码如上,其实就是一层层反嵌套,剥开然后一个个的和target比较,相等就返回true。

As 函数

在Go 1.13之前没有wrapping error的时候,我们要把error转为另外一个error,一般都是使用type assertion 或者 type switch,其实也就是类型断言。

1
2
3
if perr, ok := err.(*os.PathError); ok {
	fmt.Println(perr.Path)
}

比如例子中的这种方式,但是现在给你返回的err可能是已经被嵌套了,甚至好几层了,这种方式就不能用了,所以Golang为我们在errors包里提供了As函数,现在我们把上面的例子,用As函数实现一下。

1
2
3
4
var perr *os.PathError
if errors.As(err, &perr) {
	fmt.Println(perr.Path)
}

这样就可以了,就可以完全实现类型断言的功能,而且还更强大,因为它可以处理wrapping error。

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

从功能上来看,As所做的就是遍历err嵌套链,从里面找到类型符合的error,然后把这个error赋予target,这样我们就可以使用转换后的target了,这里有值得赋予,所以target必须是一个指针。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
func As(err error, target interface{}) bool {
    //一些判断,保证target,这里是不能为nil
	if target == nil {
		panic("errors: target cannot be nil")
	}
	val := reflectlite.ValueOf(target)
	typ := val.Type()
	
	//这里确保target必须是一个非nil指针
	if typ.Kind() != reflectlite.Ptr || val.IsNil() {
		panic("errors: target must be a non-nil pointer")
	}
	
	//这里确保target是一个接口或者实现了error接口
	if e := typ.Elem(); e.Kind() != reflectlite.Interface && !e.Implements(errorType) {
		panic("errors: *target must be interface or implement error")
	}
	targetType := typ.Elem()
	for err != nil {
	    //关键部分,反射判断是否可被赋予,如果可以就赋值并且返回true
	    //本质上,就是类型断言,这是反射的写法
		if reflectlite.TypeOf(err).AssignableTo(targetType) {
			val.Elem().Set(reflectlite.ValueOf(err))
			return true
		}
		//这里意味着你可以自定义error的As方法,实现自己的类型断言代码
		if x, ok := err.(interface{ As(interface{}) bool }); ok && x.As(target) {
			return true
		}
		//这里是遍历error链的关键,不停的Unwrap,一层层的获取err
		err = Unwrap(err)
	}
	return false
}

这是As函数的源代码,看源代码比较清晰一些,我在代码里做了注释,这里就不一一分析了,大家可以结合注释读一下。

旧工程迁移

新特性的更新,如果要使想使用,不免会有旧项目的迁移,现在我们就针对几种常见的情况看如何进行迁移。 如果你以前是直接返回err,或者通过如下方式给err增加了额外信息。

1
2
3
return err

return fmt.Errorf("more info: %v", err)

这2种情况你直接切换即可。

1
return fmt.Errorf("more info: %w", err)

切换后,如果你有==的error判断,那么就用Is函数代替,比如:

旧工程

1
if err == os.ErrExist

新工程

1
if errors.Is(err, os.ErrExist)

同理,你旧的代码中,如果有对error进行类型断言的转换,就要用As函数代替,比如:

旧工程

1
2
3
if perr, ok := err.(*os.PathError); ok {
	fmt.Println(perr.Path)
}

新工程

1
2
3
4
var perr *os.PathError
if errors.As(err, &perr) {
	fmt.Println(perr.Path)
}

如果你自己自定义了一个struct实现了error接口,而且还嵌套了error,这个时候该怎么适配新特性呢?也就是我们上面举例的情况:

1
2
3
4
5
6
7
8
type MyError struct {
	err error
	msg string
}

func (e *MyError) Error() string {
	return e.err.Error() + e.msg
}

其实对于这种方式很简单,只需要给他添加一个Unwrap方法就可以了,让它变成一个wrap error。

1
2
3
func (e *MyError) Unwrap() error {
	return e.err
}

这样就可以了。

结语

这篇文章深度剖析了Error Wrapping的背景、实现原理以及工程迁移的注意事项,这个新特性是很值得使用的,毕竟增强了error,提供了强大的跟踪能力,再结合一些额外的数据,可以让我们调试、变成会更方便。

本文为原创文章,转载注明出处,欢迎扫码关注公众号flysnow_org或者网站asf http://www.flysnow.org/ ,第一时间看后续精彩文章。觉得好的话,请猛击文章右下角「在看」,感谢支持。

扫码关注