05使用 Go 定义错误码

• 简介
• 设计错误码
• 代码实现
• 常见的错误码
• 总结
• 当前部分的代码

简介

不管在什么系统中, 定义错误码都是必不可少的.

错误码可以帮助定义问题, 通常错误码设计为某种模式结构,
可以判断出错误的级别, 错误的模块和具体错误信息.

设计错误码

一个良好结构的错误码有助于简化问题描述,
当前设计的错误码共有五位, 结构如下:

1	00	01
服务级别	模块	具体错误

第一位是服务级别, 1 为系统错误, 2 为普通错误.

第二三位是模块, 模块不是指 Go 中的模块, 而是指代某个范围, 比如数据库错误, 认证错误.

第四五位是具体错误, 比如数据库错误中的插入错误, 找不到数据等.

定义错误码的时候不光有 Code 数字, 也会有对应的文本信息, 通常, 文本分为两类,
一类是给用户看的, 另一类是用于 debug 的.

代码实现

在 pkg 目录下新建一个 errno 目录, 并创建相应的模块.

package errno

import "fmt"

// 定义错误码
type Errno struct {
    Code    int
    Message string
}

func (err Errno) Error() string {
    return err.Message
}

// 定义错误
type Err struct {
    Code    int    // 错误码
    Message string // 展示给用户看的
    Errord  error  // 保存内部错误信息
}

func (err *Err) Error() string {
    return fmt.Sprintf("Err - code: %d, message: %s, error: %s", err.Code, err.Message, err.Errord)
}

上面定义了两种数据结构, 每一种都实现了 Error() 方法, 也就是继承了 error 接口.

Errno 定义了错误码的结构, 会在另一个文件中统一定义所有的错误码.
Err 定义了完整的错误的结构, 通常可以理解为 Errno 和一个内部错误的结合.

// 使用 错误码 和 error 创建新的 错误
func New(errno *Errno, err error) *Err {
    return &Err{
        Code:    errno.Code,
        Message: errno.Message,
        Errord:  err,
    }
}

New 函数从一个 Errno 和 error 中返回新的 Err, 这样就包装了内部错误.

另一个重要的方法是解码错误, 获取 Code 和 Message.

// 解码错误, 获取 Code 和 Message
func DecodeErr(err error) (int, string) {
    if err == nil {
        return OK.Code, OK.Message
    }
    switch typed := err.(type) {
    case *Err:
        if typed.Code == ErrBind.Code {
            typed.Message = typed.Message + " 具体是 " + typed.Errord.Error()
        }
        return typed.Code, typed.Message
    case *Errno:
        return typed.Code, typed.Message
    default:
    }

    return InternalServerError.Code, err.Error()
}

常见的错误码

在设计完成 errno 模块之后, 我们需要定义一些常见的错误码.

package errno

/*
错误码设计
第一位表示错误级别, 1 为系统错误, 2 为普通错误
第二三位表示服务模块代码
第四五位表示具体错误代码
*/

var (
    OK = &Errno{Code: 0, Message: "OK"}

    // 系统错误, 前缀为 100
    InternalServerError = &Errno{Code: 10001, Message: "内部服务器错误"}
    ErrBind             = &Errno{Code: 10002, Message: "请求参数错误"}
    ErrTokenSign        = &Errno{Code: 10003, Message: "签名 jwt 时发生错误"}
    ErrEncrypt          = &Errno{Code: 10004, Message: "加密用户密码时发生错误"}

    // 数据库错误, 前缀为 201
    ErrDatabase = &Errno{Code: 20100, Message: "数据库错误"}
    ErrFill     = &Errno{Code: 20101, Message: "从数据库填充 struct 时发生错误"}

    // 认证错误, 前缀是 202
    ErrValidation   = &Errno{Code: 20201, Message: "验证失败"}
    ErrTokenInvalid = &Errno{Code: 20202, Message: "jwt 是无效的"}

    // 用户错误, 前缀为 203
    ErrUserNotFound      = &Errno{Code: 20301, Message: "用户没找到"}
    ErrPasswordIncorrect = &Errno{Code: 20302, Message: "密码错误"}
)

总结

错误码是 API 服务中不可缺少的一环, 但错误码的结构设计却是千差万别,
这个时候还是要多参考一些大厂的开放 API 设计, 找出共性, 去粗取精.

当前部分的代码

作为版本 v0.5.0

说明, 当前分支下定义的错误码和上文中显示的不一样, 还是以文章为主,
因为写文章也是一个思考的过程, 所以有时会对代码做一点改动.