概述

开发中经常有定义错误码这样的需求，错误码唯一标识具体的错误信息。另外还需要设置每个错误的具体描述。在 HTTP 协议中，200 表示 "OK"，404 表示"Not Found"。在 Linux 系统中，ENOENT 的值为 2，表示"No such file or directory"。syscall包中定义了Errno类型表示系统错误码，非常易用使用，建议去看看。

每次定义错误码的时候，同时需要添加描述信息。而且描述信息经常会忘。本文介绍go generate + stringer工具链优雅地解决这个问题。

这里顺带提一句，golang tools 是官方提供的工具集，是 Gophers 的工具宝库，值得好好探索一番，参见Github 地址，文档地址。里面有丰富的开发辅助工具，所有的 Go 开发插件都离不开这些工具的支持。例如goimports工具自动导入使用的包，去掉未使用的包；gorename用来重命名标识符。

今天要使用的stringer工具也在tools工具包中。

传统方式

定义错误码：

package errcode

import "fmt"

// 定义错误码
const (
    ERR_CODE_OK = 0 // OK
    ERR_CODE_INVALID_PARAMS = 1 // 无效参数
    ERR_CODE_TIMEOUT = 2 // 超时
    // ...
)

// 定义错误码与描述信息的映射
var mapErrDesc = map[int]string {
    ERR_CODE_OK: "OK",
    ERR_CODE_INVALID_PARAMS: "无效参数",
    ERR_CODE_TIMEOUT: "超时",
    // ...
}

// 根据错误码返回描述信息
func GetDescription(errCode int) string {
    if desc, exist := mapErrDesc[errCode]; exist {
        return desc
    }
    
    return fmt.Sprintf("error code: %d", errCode)
}

使用错误码：

package main

import (
    "github.com/darjun/errcode"
)

func main() {
    code := errcode.ERR_CODE_INVALID_PARAMS
    fmt.Println(code, errcode.GetDescription(errCode))
    
    // 输出: 1 无效参数
}

为了使用方便，我们可以为错误码定义一个新的类型，然后为该类型定义String()方法，这样就不用手动调用GetDescription函数了。修改如下：

type ErrCode int

const (
    ERR_CODE_OK ErrCode = 0 // OK
    ERR_CODE_INVALID_PARAMS ErrCode = 1 // 无效参数
    ERR_CODE_TIMEOUT ErrCode = 2 // 超时
)

func (e ErrCode) String() string {
    return GetDescription(e)
}

现在已经不需要在外部调用GetDescription函数了，从而不需要导出。将函数名改为getDescription即不导出。

这种方式有什么问题呢？

每次增加错误码时，都需要修改mapErrDesc，有时候可能会忘。另外，错误描述在注释和mapErrDesc都出现了。那么能不能只写注释，然后使用工具自动生成我们想要的代码呢？

接下我们看看如何通过go generate + stringer解决这个问题。

`go generate`

go generate是 Go 自带的工具。使用命令go generate执行。go generate是利用源代码中的注释工作的。格式如下：

//go:generate command arg1 arg2

这样在同一个目录下执行命令go generate就会自动运行命令command arg1 arg2。command可以是在PATH中的任何命令，应用非常广泛。官网提供了几种示例，见文档。

stringer命令可以为给定类型生成String方法。

安装`stringer`

stringer并不是 Go 自带的工具，需要手动安装。可以执行下面的命令安装：

$ go get golang.org/x/tools/cmd/stringer

上面的命令需要翻墙。也可以通过 Github 上的镜像来安装。假设你已经配置好 Go 的开发环境了，安装方法如下：

$ git clone https://github.com/golang/tools/ $GOPATH/src/golang.org/x/tools
$ go install golang.org/x/tools/cmd/stringer

安装好的stringer命令位于$GOPATH/bin目录下，强烈建议将这个目录加入系统PATH中。

使用

stringer有两种模式，默认是根据变量/常量名来生成字符串描述。我们在常量定义上增加注释：

//go:generate stringer -type ErrCode

选项-type指定stringer命令作用的类型名。

然后在同一个目录下执行：

$ go generate

会在同一个目录下生成一个文件errcode_string.go。文件名格式是类型名小写_string.go。也可以通过-output选项指定输出文件名，例如下面就是指定输出文件名为code_string.go：

//go:generate stringer -type ErrCode -output code_string.go

我们来看看这个文件的内容：

// Code generated by "stringer -type ErrCode -output errcode_string.go"; DO NOT EDIT.

package errcode

import "strconv"

const _ErrCode_name = "ERR_CODE_OKERR_CODE_INVALID_PARAMSERR_CODE_TIMEOUT"

var _ErrCode_index = [...]uint8{0, 11, 34, 50}

func (i ErrCode) String() string {
	if i < 0 || i >= ErrCode(len(_ErrCode_index)-1) {
		return "ErrCode(" + strconv.FormatInt(int64(i), 10) + ")"
	}
	return _ErrCode_name[_ErrCode_index[i]:_ErrCode_index[i+1]]
}

生成的代码做了一些优化，减少了字符串对象的数量。

这时ERR_CODE_INVALID_PARAMS.String()返回的描述信息是ERR_CODE_INVALID_PARAMS。在一些上下文中甚至不需要自己调用String()方法，如fmt.Println。因为ErrCode实现了fmt.Stringer，一些上下文中会自动调用。

这样errcode.go文件中mapErrDesc全局变量和getDescription函数都可以去掉了。

但是我们更希望的是能返回后面的注释作为错误描述。这就需要使用stringer的-linecomment选项。修改go:generate如下：

//go:generate stringer -type ErrCode -linecomment -output code_string.go

然后，执行go generate命令。生成的code_string.go与之前的有所不同，如下：

const _ErrCode_name = "OK无效参数超时"

var _ErrCode_index = [...]uint8{0, 2, 14, 20}

可以看到确实通过注释生成了错误消息。

注意点：

go:generate前面只能使用//注释，注释必须在行首，前面不能有空格且//与go:generate之间不能有空格！！！
go:generate可以在任何 Go 源文件中，最好在类型定义的地方。

自动化

有人会说，这样还是很麻烦啊：每次都要执行一次go generate命令，我忘了怎么办？我很懒，也不想手动敲这个命令。没问题，不会偷懒不是一个好程序员。我们可以在构建项目的脚本中执行这个命令，例如在 makefile 中：

all:
    go generate && go build .

这样一个make命令就可以执行go generate同时编译项目了。完美！

当然上面命令比较简单，实际项目中可能需要处理一下目录。

代码在Github上。

参考链接

个人主页