阅读 553

深入理解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 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 arg2command可以是在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}
复制代码

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

注意点:

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

自动化

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

all:
    go generate && go build .
复制代码

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

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

代码在Github上。

参考链接

  1. go blog - generate
  2. go generate文档

个人主页

关注下面的标签,发现更多相似文章
评论