在常规错误处理中,使用 errors.New() 和 fmt.Errorf() 创建的错误只包含一段简单的文字描述。但在项目开发里,我们经常还需要在错误中附带业务状态码(如 401、500)或出错字段名,方便调用方根据不同情况做针对性处理。
那在 Go 语言中,怎么让一个错误同时保存多个属性呢?这就要从 error 类型的底层定义说起了。
error 接口是什么?
在 Go 语言中,error 并不是什么特殊的语法结构,它本质上只是一个内置的普通接口。在 Go 标准库的源码中,error 接口的定义只有短短 3 行:
type error interface {
Error() string
}看到这 3 行代码,小伙伴们是不是觉得很眼熟?它跟我们前面学过的普通接口一模一样,里面只声明了一个无参数、返回值为 string 的 Error() 方法。
Go 语言的接口采用隐式实现机制。只要我们自己定义一个结构体,并为它绑定 Error() string 方法,这个结构体就自动实现了 error 接口,可以直接当作 error 类型返回。
定义结构体实现自定义错误
在 Go 语言中,编写自定义错误一般只需要两步:① 定义一个结构体,用来存放所需的错误信息(如错误码、错误描述);② 为该结构体绑定 Error() string 方法,返回格式化后的错误提示文本。
语法:
type 错误结构体名 struct {
字段1 类型1
字段2 类型2
}
func (e *错误结构体名) Error() string {
return "错误描述字符串"
}说明:
按照 Go 语言的命名习惯,自定义错误结构体的名称一般以 Error 结尾。比如项目中常用来表示业务错误的 BizError,就是英文 “Business Error(业务错误)” 的缩写。
示例 1:定义带状态码的错误
package main
import "fmt"
// 1. 定义自定义错误结构体
type BizError struct {
Code int
Msg string
}
// 2. 实现 Error() string 方法
func (e *BizError) Error() string {
return fmt.Sprintf("错误码:%d,原因:%s", e.Code, e.Msg)
}
// 模拟登录校验
func login(pwd string) error {
if pwd != "123456" {
return &BizError{
Code: 401,
Msg: "密码错误",
}
}
return nil
}
func main() {
err := login("000000")
if err != nil {
fmt.Println(err)
}
}运行结果如下。
错误码:401,原因:密码错误分析:
在这个例子中,我们先定义了包含 Code(错误码)和 Msg(错误消息)两个字段的 BizError 结构体,接着通过 (e *BizError) 为它实现了 Error() string 方法。
当我们在 main() 函数中调用 fmt.Println(err) 打印错误变量时,fmt 包会自动调用它的 Error() 方法,把拼好的字符串打印到屏幕上。
这里小伙伴们要特别注意:Error() 使用的是指针接收者 *BizError,只有 *BizError 指针才算实现了 error 接口。所以在 login() 返回错误时必须加上 &,下面这种漏写 & 的写法会报错。
return BizError{Code: 401, Msg: "密码错误"}如果漏掉 &,编译器会直接报错 BizError does not implement error (method Error has pointer receiver),意思是值类型的 BizError 并没有实现 error 接口。
注意: 在为自定义错误结构体绑定 Error() string 方法时,实际开发中统一推荐使用 *BizError 这样的指针接收者。这样在多层函数间传递错误时只需要复制一个内存地址,不用拷贝整个结构体,同时也与 Go 标准库自身的错误实现方式保持一致。
除了保存错误码之外,我们还可以根据业务需要,在自定义错误结构体里自由添加任意多个字段。下面我们再来看一个记录商品价格校验详情的例子。
示例 2:记录非法参数详情
package main
import "fmt"
// 记录参数错误详情的结构体
type ArgError struct {
Field string
Value float64
Reason string
}
func (e *ArgError) Error() string {
return fmt.Sprintf("参数 %s 的值 %.1f 不合法:%s", e.Field, e.Value, e.Reason)
}
func checkPrice(price float64) error {
if price < 0 {
return &ArgError{
Field: "price",
Value: price,
Reason: "不能小于 0",
}
}
return nil
}
func main() {
err := checkPrice(-19.8)
if err != nil {
fmt.Println(err)
}
}运行结果如下。
参数 price 的值 -19.8 不合法:不能小于 0分析:
ArgError 结构体同时记录了出错的参数名 Field、传入的错误数值 Value 以及具体原因 Reason。直接打印 err 时会输出拼好的完整提示语,而这 3 个原始字段也完好地保存在结构体内部,随时可以供上层代码单独读取。
返回自定义错误指针时,还有一个很隐蔽的新手大坑一定要避开:函数正常执行、没有出错时,应该直接写 return nil。千万不要先声明一个空的自定义错误指针变量,再把它作为 error 返回。
// 正确方式
func checkPrice(price float64) error {
if price < 0 {
return &ArgError{Field: "price", Value: price, Reason: "不能小于 0"}
}
return nil
}
// 错误方式
func checkPrice(price float64) error {
var err *ArgError
if price < 0 {
err = &ArgError{Field: "price", Value: price, Reason: "不能小于 0"}
}
return err
}在 Go 语言中,接口变量内部由 “具体类型” 和 “具体值” 两部分组成。只有这两部分同时为空时,接口变量才等于 nil。
在上面的错误方式中,哪怕传入合法价格 12.5,err 本身的值虽然是 nil。但把它装进 error 接口返回后,接口里依然记录着 *ArgError 这个类型信息。外层执行 if err != nil 时条件居然会成立,把正常结果误判成出错。因此只要没出错,直接写 return nil 就可以了。
提取自定义错误中的字段
当我们把 &BizError{...} 作为 error 类型返回给调用者后,调用者拿到的变量 err 表面上是 error 接口类型。此时直接写 err.Code 是无法通过编译的,因为 error 接口本身只定义了 Error() 方法,并没有声明 Code 字段。
如果想要读取结构体内部的字段,我们可以使用前面学过的类型断言,先把 error 接口变量还原为具体的 *BizError 指针(如下图所示)。

示例 3:提取自定义错误字段
package main
import "fmt"
type BizError struct {
Code int
Msg string
}
func (e *BizError) Error() string {
return fmt.Sprintf("错误码:%d,原因:%s", e.Code, e.Msg)
}
func login(pwd string) error {
if pwd != "123456" {
return &BizError{Code: 401, Msg: "密码错误"}
}
return nil
}
func main() {
err := login("000000")
if err != nil {
// 使用安全类型断言还原为 *BizError
if bizErr, ok := err.(*BizError); ok {
fmt.Printf("状态码:%d\n", bizErr.Code)
fmt.Printf("提示语:%s\n", bizErr.Msg)
}
}
}运行结果如下。
状态码:401
提示语:密码错误分析:
bizErr, ok := err.(*BizError) 表示判断 err 底层是不是 *BizError 指针。如果匹配成功,ok 为 true,bizErr 就能拿到还原后的指针。随后我们便可以通过 bizErr.Code 和 bizErr.Msg 单独读取字段。
如果不先做类型断言,而是直接在 main() 函数中访问 err.Code,下面这句代码就会编译失败。
fmt.Println(err.Code)编译器会直接报错 err.Code undefined (type error has no field or method Code),提示 error 类型没有名为 Code 的字段或方法。
另外要留意,普通类型断言 err.(*BizError) 只适用于错误被直接返回的简单场景。如果错误在多层调用中被二次包装过,实际项目中通常会改用 errors.As() 函数来提取。
自定义错误的选型建议
平时写代码时,到底什么时候用 errors.New(),什么时候才需要自定义错误结构体呢?这主要取决于调用方拿到错误后打算怎么处理它。
如果调用方只需要打印日志或向用户展示一段提示文字,直接使用 errors.New() 或 fmt.Errorf() 就完全够用了,写起来最省事。
只有当调用方需要读取错误内部携带的具体字段时,我们才需要定义自定义错误结构体。比如需要根据 Code 状态码返回不同的接口响应,或者读取 Field 字段判断哪一个表单项填错了。
