Go 自定义错误

在常规错误处理中,使用 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 指针(如下图所示)。

通过类型断言从 error 接口还原自定义错误结构体

示例 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 字段判断哪一个表单项填错了。

上一篇:

下一篇:

给站长反馈

绿叶网正在不断完善中,小伙伴们如果发现任何问题,还望多多给站长反馈,谢谢!

邮箱:lvyenet@vip.qq.com

「绿叶网」服务号
绿叶网服务号放大
关注服务号,微信也能看教程。
绿叶网服务号