最近项目中为了将具体出错信息向前端暴露出来，所以需要定义具体的错误码格式，主要有如下几个问题需要解决。

1. 错误码的定义。
2. 因为错误码是分布在代码的各个模块中，因此最好使用自动化代码生成工具将错误码收集起来，类似与K8S中的根据相应的tag来生成代码。
3. 由于底层很多命令是通过gRPC调用来完成的，如何将错误码和错误信息返回给客户端也是需要解决的问题。默认情况下client端返回给server端的错误码是经过封装处理的。

错误码的定义

• 错误码是按照各组件来划分的，其格式为：AA-BB-CCCC

  • A: 项目或模块名称; 比如rbd, ceph, docker, disk等。
  • B: 具体子模块；比如rbd中的volume，snapshot, volume migration等等。
  • C: 具体错误编号；自增且唯一表示具体某一种错误。

• 注意以下规范：

  1. 错误码的格式为16进制大写，例如1A-F3-001C
  2. AA-BB-CCCC中子模块BB如果为01则表示common的部分。例如02-01-XXXX表示一些通用的rbd错误码。
  3. 0000保留不使用，0001统一表示unspecified error。每个子模块有自己的0001编码，代表属于这个子模块的unspecified error。

错误码

错误码分散于各模块中，错误码定义在xxx_error.go文件中，其中xxx代表对应的模块。其格式如下：

// ErrCodeRbd defines the id of rbd module
// +ErrCode
const ErrCodeRbd = 0x02
 
// the sub module of rbd
// +ErrCode=Rbd
const (
    ErrCodeRbdCommon = iota + 1
    ErrCodeRbdVolume
    ErrCodeRbdSnapshot
    ErrCodeRbdVolumeMigration
    ErrCodeRbdReplication
    ErrCodeRbdTrash
)
 
// list of rbd common error codes
// +ErrCode=Rbd,Common
const (
    ErrCodeRbdCommonUnspecifiedError = iota + 1
)
 
// ErrCodeRbdCommonToMessage is map of common error code to their messages
var ErrCodeRbdCommonToMessage = map[int]string{
    ErrCodeRbdCommonUnspecifiedError: "the %s operation failed due to unspecified error",
}
......

错误码文件中的内容大致如下：

1. 首先定义的是模块ID，其为常量类型，命名时以ErrCode开头，后面跟着模块名，例如Rbd。命名格式为：ErrCodeAA。 value部分为16进制值。
2. 接着是子模块的定义，01代表common，然后根据各子模块进行扩展即可。命名格式为：ErrCodeAABB
3. 接着是各子模块对应的具体错误ID。命名格式为：ErrCodeAABBCC
4. 接着是错误ID对应的message信息。命名格式为：ErrCodeAABBToMessage

错误码中Tag的设置

由于错误码分散在代码的各个模块中，为了更好的收集所有的错误码并生成对应的json文件供前端使用，所以采用的是k8s方案中的gengo自动化代码生成。代码分支见microyahoo/gengo

Tag的定义

如上面的代码片段所示，tag紧挨着const定义，以+ErrCode开头。
例如上面定义了三个tag

// +ErrCode  加在模块的上面，代表这是具体的一个模块。
// +ErrCode=Rbd 加在具体的子模块上面，代表这是模块下的子模块信息，可能有多个。
// +ErrCode=Rbd,Common 加在具体子模块对应的错误信息上面，代表子模块有很多具体的错误信息

其中第二个tag以+ErrCode开头，后面跟着具体的模块，是以键值对的形式展示的。第三个tag也是以+ErrCode开头，后面跟着具体的模块以及子模块，其中模块和子模块之间以逗号分隔，中间没有空格。

自动化生成的json文件如下：

{
    "01-01-0001": {
        "desc": "CommonUnspecifiedError"
    },
    "01-01-0002": {
        "desc": "CommonJSONUnmarshalError"
    },
    "01-01-0003": {
        "desc": "CommonJSONMarshalError"
    },
    "02-01-0001": {
        "desc": "RbdCommonUnspecifiedError"
    },
    "02-02-0001": {
        "desc": "RbdVolumeUnknownParameter"
    },
    "02-02-0002": {
        "desc": "RbdVolumeNoEntry"
    }
}

gRPC error处理

由于代码中运用了很多gRPC调用去其他节点执行相应的命令，而gRPC server会将我们执行命令返回结果的错误信息封装成statusError，这样客户端拿到的error是处理之后的，不是我们上述自定义的error，因此也就无法获取定义的错误码和其他自定义的错误信息。具体可以参见google.golang.org/grpc/status/status.go文件。

 41 // statusError is an alias of a status proto.  It implements error and Status,
 42 // and a nil statusError should never be returned by this package.
 43 type statusError spb.Status
 44
 45 func (se *statusError) Error() string {
 46     p := (*spb.Status)(se)
 47     return fmt.Sprintf("rpc error: code = %s desc = %s", codes.Code(p.GetCode()), p.GetMessage())
 48 }
 49
 50 func (se *statusError) GRPCStatus() *Status {
 51     return &Status{s: (*spb.Status)(se)}
 52 }

此问题可以通过分别在server和client端添加自定义的一元拦截器进行处理。过程大致如下：

1. client端发起gRPC调用，server接收请求后执行相应的命令，如果执行失败将错误信息中的错误码和错误信息进行封装成可序列化的。error.proto文件定义如下所示，这样生成的error.pb.go中的Error实现了proto.Message接口，可被序列化之后被client接收并解析。

  1 syntax = "proto3";
  2
  3 package pb;
  4
  5 message Error {
  6   string code = 1;
  7   string message = 2;
  8   string details = 3;
  9 }

server端一元拦截器如下所示：

// ServerErrorInterceptor transfer a error to status error
func ServerErrorInterceptor(ctx context.Context, req interface{},
    info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
    resp, err := handler(ctx, req)
    return resp, toStatusError(err)
}

func toStatusError(err error) error {
    if err == nil {
        return nil
    }
    cause := errors.Cause(err)
    pbErr := &pb.Error{
        Details: cause.Error(),
    }
    if coder, ok := cause.(errors.Coder); ok {
        pbErr.Code = coder.Code()
        pbErr.Message = coder.Message()
        pbErr.Details = coder.Details()
    }
    st := status.New(codes.Internal, cause.Error())
    st, e := st.WithDetails(pbErr)
    if e != nil {
        // make sure pbErr implements proto.Message interface
        return errors.NewCommonError(errors.ErrCodeCommonJSONMarshalError, e, pbErr.String())
    }
    return st.Err()
}

Server端的拦截器主要是将我们定义的带错误码的error转化为可被序列化的rpc pb.Error，然后调用Status.WithDetails()进行序列化，这样client端拦截器拿到序列化后的pb.Error，返回我们一个实现了errors.Coder接口的error。这样client就能获取定义的错误码，错误信息等等。

2. client一元拦截器收到server端返回的错误信息后进行解析。

func ClientErrorInterceptor(ctx context.Context, method string, req, reply interface{},
    cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
    err := invoker(ctx, method, req, reply, cc, opts...)
    if err == nil {
        return nil
    }
    cause := errors.Cause(err)
    st, ok := status.FromError(cause)
    if ok {
        details := st.Details()
        if details != nil && len(details) > 0 {
            if pbErr, ok := details[0].(*pb.Error); ok {
                return newRPCClientError(pbErr.Code, pbErr.Message, pbErr.Details)
            }
        }
    }
    return err
}

一元拦截器在执行完调用后对错误信息进行处理，其中status.FromError从错误信息中获取Status，而Status.Details()方法会将错误信息反序列化成我们前面定义的pb.Error，这样我们就能拿到定义的错误码，错误信息，以及details了。

References

• gengo
• k8s code generator
• Kubernetes Deep Dive: Code Generation for CustomResources
• [k8s源码分析][code-generator] crd代码生成之list分析
• astexplorer
• Advanced gRPC Error Usage
• The ultimate guide to writing a Go tool
• Reading Go's AST