深入理解Go之generate 深入理解Go之generate

概述开发中经常有定义错误码这样的需求，错误码唯一标识具体的错误信息。另外还需要设置每个错误的具体描述。在 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 errcodeimport "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 mainimport ( "github.com/darjun/errcode" )func main() { code := errcode.ERR_CODE_INVALID_PARAMS fmt.Println(code, errcode.GetDescription(errCode))// 输出: 1 无效参数 }

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

type ErrCode intconst ( 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 errcodeimport "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如下：