Go 终极指南：编写一个 Go 工具
原文：https://arslan.io/2017/09/14/the-ultimate-guide-to-writing-a-go-tool/
做者：Fatih Arslan
译者：oopsguy.comnode
我以前编写过一个叫 gomodifytags 的工具，使个人开发工做变得很轻松。它会根据字段名称自动填充结构体标签字段。下图是它的功能展现：git
使用这样的工具能够很容易管理结构体的多个字段。该工具还能够添加和删除标签、管理标签选项（如 omitempty）、定义转换规则（snake_case、camelCase 等）等。但这样的工具是怎样工做的呢？它内部使用了什么 Go 包？有不少问题须要回答。github
这是一篇很是长的博文，其解释了如何编写这样的工具以及每一个构建细节。它包含许多独特的细节、技巧和未知的 Go 知识。golang
拿起一杯咖啡☕️，让咱们一块儿深刻探索！json
首先，让我列出这个工具须要作的事情：vim
- 读取源文件、理解并可以解析 Go 文件
- 找到相关的结构体
- 找到结构体后，获取字段名称
- 根据字段名来更新结构体标签（根据转换规则，如
snake_case） - 可以把变动后的内容更新到文件中，或者可以以可消费的方式输出结果
咱们首先来了解什么是 结构体（struct）标签（tag），从这里咱们能够学习到全部东西以及如何把它们组合在一块儿使用，在此基础上您也能够构建出这样的工具。数组
结构体的标签值（内容，如 json: "foo"）不是官方规范的一部分，可是 reflect 包定义了一个非官方规范的格式标准，这个格式一样被 stdlib 包（如 encoding/json）所使用。它经过 reflect.StructTag 类型定义：app
这个定义有点长，不是很容易理解。咱们尝试分解一下：编辑器
- 一个结构体标签是一个字符串（由于它有字符串类型）
- 键（key）部分是一个无引号的字符串
- 值（value）部分是带引号的字符串
- 键和值由冒号（:)分隔。键与值且由冒号分隔组成的值称为键值对
- 结构体标签能够包含多个键值对（可选）。键值对由空格分隔。
- 非定义部分为选项设置。像
encoding/json这样的包在读取值时把它看成一个由逗号分隔列表。第一个逗号后的内容都是选项部分，好比foo,omitempty,string。其有一个名为foo的值和 [omitempty,string] 选项 - 由于结构体标签是字符串文字，因此须要使用双引号或反引号包裹。又由于值必须使用引号，所以咱们老是使用反引号对整个标签作处理。
总的来讲：ide
咱们已经了解了什么是结构体标签，咱们能够根据须要轻松地修改它。如今的问题是，咱们如何解析它才可以轻松进行修改？幸运的是，reflect.StructTag 包含了一个方法，咱们能够用它来进行解析并返回指定键的值。以下示例：
package main
import (
"fmt"
"reflect"
)
func main() {
tag := reflect.StructTag(`species:"gopher" color:"blue"`)
fmt.Println(tag.Get("color"), tag.Get("species"))
}
结果：
blue gopher
若是键不存在，则返回一个空字符串。
这很是有用，但也有一些不足使得它并不适合咱们，由于咱们须要更加灵活的方式：
- 它没法检测到标签是否格式错误（如：键部分用引号包裹，值部分没有使用引号等）。
- 它没法得知选项的语义。
- 它没有办法迭代现有的标签或返回它们。咱们必需要知道要修改哪些标签，若是不知道名字怎么办？
- 修改现有标签是不可能的。
- 咱们不能从头开始构建新的结构体标签。
为了改进这点，我写了一个自定义的 Go 包，它解决了上面提到的全部问题，并提供了一个 API，能够轻松地改变结构体标签的各个方面。
该包名为 structtag，能够从 github.com/fatih/structtag 获取。咱们能够经过这个包以简洁的方式解析和修改标签。如下是一个完整示例，您能够复制/粘贴并自行尝试：
package main
import (
"fmt"
"github.com/fatih/structtag"
)
func main() {
tag := `json:"foo,omitempty,string" xml:"foo"`
// parse the tag
tags, err := structtag.Parse(string(tag))
if err != nil {
panic(err)
}
// iterate over all tags
for _, t := range tags.Tags() {
fmt.Printf("tag: %+v\n", t)
}
// get a single tag
jsonTag, err := tags.Get("json")
if err != nil {
panic(err)
}
// change existing tag
jsonTag.Name = "foo_bar"
jsonTag.Options = nil
tags.Set(jsonTag)
// add new tag
tags.Set(&structtag.Tag{
Key: "hcl",
Name: "foo",
Options: []string{"squash"},
})
// print the tags
fmt.Println(tags) // Output: json:"foo_bar" xml:"foo" hcl:"foo,squash"
}
此时咱们已经了解了如何解析、修改和建立结构体标签，是时候尝试修改一个 Go 源文件了。在上面示例中，标签已经存在，可是如何从现有的 Go 结构体中获取标签呢？
答案是经过 AST。AST（Abstract Syntax Tree，抽象语法树）容许咱们从源代码中检索每一个标识符（节点）。在下面你能够看到一个结构体类型的 AST（简化版）：
在这棵树中，咱们能够检索和操做每一个标识符、每一个字符串、每一个括号等。这些都经过 AST 节点表示。例如，咱们能够经过替换表示它的节点将字段名称从 Foo 更改成 Bar。该逻辑一样适用于结构体标签。
要得到一个 Go AST，咱们须要解析源文件并将其转换成一个 AST。实际上，这二者都是经过同一个步骤来处理的。
要实现这一点，咱们将使用 go/parser 包来解析文件以获取 AST（整个文件），而后使用 go/ast 包来处理整棵树（咱们能够手动作这个工做，但这是另外一篇博文的主题）。 您在下面能够看到一个完整的例子：
package main
import (
"fmt"
"go/ast"
"go/parser"
"go/token"
)
func main() {
src := `package main
type Example struct {
Foo string` + " `json:\"foo\"` }"
fset := token.NewFileSet()
file, err := parser.ParseFile(fset, "demo", src, parser.ParseComments)
if err != nil {
panic(err)
}
ast.Inspect(file, func(x ast.Node) bool {
s, ok := x.(*ast.StructType)
if !ok {
return true
}
for _, field := range s.Fields.List {
fmt.Printf("Field: %s\n", field.Names[0].Name)
fmt.Printf("Tag: %s\n", field.Tag.Value)
}
return false
})
}
输出结果：
Field: Foo Tag: `json:"foo"`
代码执行了如下操做：
- 咱们定义了只有一个结构体的有效 Go 包示例
- 咱们使用 go/parser 包来解析这个字符串。
parser包也能够从磁盘读取文件（或整个包）。 - 在解析后，咱们处理了节点（分配给变量文件）并查找由 ast.StructType 定义的 AST 节点（参考 AST 图）。经过
ast.Inspect()函数完成树的处理。它会遍历全部节点，直到它收到false值。这很是方便，由于它不须要知道每一个节点。 - 咱们打印告终构体的字段名称和结构体标签信息。
咱们如今能够作两件重要的事，首先，咱们知道了如何解析一个 Go 源文件并检索其结构体标签（经过 go/parser）；其次，咱们知道了如何解析 Go 结构体标签，并根据须要进行修改（经过 github.com/fatih/structtag）。
有了这些，咱们如今可使用这两个知识点来开始构建咱们的工具（命名为 gomodifytags）。该工具应按顺序执行如下操做
- 获取配置，用于描述要修改哪一个结构体
- 根据配置查找和修改结构体
- 输出结果
因为 gomodifytags 将主要应用于编辑器，咱们将经过 CLI 标志（flag）传入配置。第二步包含多个步骤，如解析文件，找到正确的结构体，而后修改结构体（经过修改 AST）。最后，咱们将结果输出，不管结果的格式是原始的 Go 源文件仍是某种自定义协议（如 JSON，稍后再说）。
如下是 gomodifytags 简化版的主要功能：
让咱们更详细地解释每个步骤。为了简单起见，我将尝试以归纳总结的形式来解释重要部分。原理都同样，一旦你读完这篇博文，你将可以在没有任何指导状况下阅整个源码（指南末尾附带了全部资源）
让咱们从第一步开始，了解如何获取配置。如下是咱们的配置，包含全部必要的信息
type config struct {
// first section - input & output
file string
modified io.Reader
output string
write bool
// second section - struct selection
offset int
structName string
line string
start, end int
// third section - struct modification
remove []string
add []string
override bool
transform string
sort bool
clear bool
addOpts []string
removeOpts []string
clearOpt bool
}
它分为三大部分：
第一部分包含有关如何读取和读取哪一个文件的设置。文件来源能够是本地文件系统的文件名，也能够是直接来自 stdin（主要用在编辑器中）。它还用于设置如何输出结果（go 源文件或 JSON），以及是否应该覆盖文件而不是输出到 stdout。
第二部分定义了如何选择一个结构体及其字段。有不少种方法能够作到这一点。咱们能够经过它的偏移量（光标位置）、结构体名称、单行（仅选择字段）或一系列行来定义它。最后，咱们不管如何都须要到开始行和结束行。例如在下面的例子中，您能够看到，咱们使用它的名字来选择结构体，而后提取开始行和结束行以选择正确的字段：
若是是应用在编辑器上，则最好使用字节偏移量。例以下面你能够发现咱们的光标恰好在 port 字段名称后面，从那里咱们能够很容易地获得开始行和结束行：
配置中的第三个部分其实是一个映射到 structtag 包的一对一映射。它基本上容许咱们在读取字段后将配置传给 structtag 包。如你所知，structtag 包容许咱们解析一个结构体标签并对各个部分进行修改。但它不会覆盖或更新结构体字段。
咱们如何得到配置？咱们只需使用 flag 包，再为配置中的每一个字段建立一个标志，而后给它们分配赋值。举个例子：
flagFile := flag.String("file", "", "Filename to be parsed")
cfg := &config{
file: *flagFile,
}
咱们对配置中的每一个字段执行相同的操做。有关完整内容，请查看 gomodifytag 当前 master 分支的 flag 定义
咱们一旦有了配置，就能够作些基本的验证：
func main() {
cfg := config{ ... }
err := cfg.validate()
if err != nil {
log.Fatalln(err)
}
// continue parsing
}
// validate validates whether the config is valid or not
func (c *config) validate() error {
if c.file == "" {
return errors.New("no file is passed")
}
if c.line == "" && c.offset == 0 && c.structName == "" {
return errors.New("-line, -offset or -struct is not passed")
}
if c.line != "" && c.offset != 0 ||
c.line != "" && c.structName != "" ||
c.offset != 0 && c.structName != "" {
return errors.New("-line, -offset or -struct cannot be used together. pick one")
}
if (c.add == nil || len(c.add) == 0) &&
(c.addOptions == nil || len(c.addOptions) == 0) &&
!c.clear &&
!c.clearOption &&
(c.removeOptions == nil || len(c.removeOptions) == 0) &&
(c.remove == nil || len(c.remove) == 0) {
return errors.New("one of " +
"[-add-tags, -add-options, -remove-tags, -remove-options, -clear-tags, -clear-options]" +
" should be defined")
}
return nil
}
将验证部分放置在一个单独的函数中，以便测试。咱们了解了如何获取配置并进行验证，接下来继续解析文件：
咱们已经开始讨论如何解析文件了。这里的解析是 config 结构体的一个方法。实际上，全部的方法都是 config 结构体的一部分：
func main() {
cfg := config{}
node, err := cfg.parse()
if err != nil {
return err
}
// continue find struct selection ...
}
func (c *config) parse() (ast.Node, error) {
c.fset = token.NewFileSet()
var contents interface{}
if c.modified != nil {
archive, err := buildutil.ParseOverlayArchive(c.modified)
if err != nil {
return nil, fmt.Errorf("failed to parse -modified archive: %v", err)
}
fc, ok := archive[c.file]
if !ok {
return nil, fmt.Errorf("couldn't find %s in archive", c.file)
}
contents = fc
}
return parser.ParseFile(c.fset, c.file, contents, parser.ParseComments)
}
parse 函数只作一件事：解析源代码并返回一个 ast.Node。若是咱们传入的是文件，那就很是简单了，在这种状况下，咱们使用 parser.ParseFile() 函数。须要注意的是 token.NewFileSet()，它建立一个 *token.FileSet 类型。咱们将它存储在 c.fset 中，同时也传给了 parser.ParseFile() 函数。为何呢？
由于 fileset 用于为每一个文件单独存储每一个节点的位置信息，这对接下来的工做很是有用，能够用于得到 ast.Node 的确切位置（请注意，ast.Node 只包含了一个精简的位置信息 token.Pos，要获取更多的信息，它须要经过 token.FileSet.Position() 函数来获取一个 token.Position，其包含更多的信息）
让咱们继续。若是经过 stdin 传递源文件，那么这就更加有趣了。config.modified 字段是一个易于测试的 io.Reader，但实际上咱们传递的是 stdin。咱们如何检测是否须要从 stdin 读取呢？
咱们询问用户是否想经过 stdin 传递内容，这种状况下，工具用户须要传递 --modified 标志（这是一个 bool flag）。若是用户传递了它，咱们只需将 stdin 分配给 c.modified：
flagModified = flag.Bool("modified", false,
"read an archive of modified files from standard input")
if *flagModified {
cfg.modified = os.Stdin
}
若是再次检查上面的 config.parse() 函数，您将会发现咱们检查是否已为 .modified 字段赋值。由于 stdin 是一个任意的数据流，咱们须要可以根据给定的协议进行解析，在这种状况下，咱们假定存档包含如下内容：
- 文件名，后接一行新行
- 文件大小（十进制），后接一行新行
- 文件的内容
由于咱们知道了文件大小，就能够无障碍地解析文件内容，任何超出给定文件大小的部分，咱们将不进行解析。
此方法也被应用在其余几个工具上（如 guru、gogetdoc 等），对编辑器来讲很是有用。由于这样可让编辑器传递修改后的文件内容，而不会保存到文件系统中。所以命名为 modified。
如今咱们有了本身的节点，让咱们继续 查找结构体 这一步：
在 main 函数中，咱们将使用从上一步解析获得的 ast.Node 调用 findSelection() 函数：
func main() {
// ... parse file and get ast.Node
start, end, err := cfg.findSelection(node)
if err != nil {
return err
}
// continue rewriting the node with the start&end position
}
cfg.findSelection() 函数根据配置返回结构体的开始位置和结束位置以告知咱们如何选择一个结构体。它迭代给定节点，而后返回开始位置和结束位置（如上配置部分中所述）：
但怎么作呢？记住有三种模式。分别是行选择、偏移量和结构体名称：
// findSelection returns the start and end position of the fields that are
// suspect to change. It depends on the line, struct or offset selection.
func (c *config) findSelection(node ast.Node) (int, int, error) {
if c.line != "" {
return c.lineSelection(node)
} else if c.offset != 0 {
return c.offsetSelection(node)
} else if c.structName != "" {
return c.structSelection(node)
} else {
return 0, 0, errors.New("-line, -offset or -struct is not passed")
}
}
行选择是最简单的部分。这里咱们只返回标志值自己。所以若是用户传入 --line 3,50 标志，函数将返回(3, 50, nil)。 它所作的就是拆分标志值并将其转换为整数（一样执行验证）：
func (c *config) lineSelection(file ast.Node) (int, int, error) {
var err error
splitted := strings.Split(c.line, ",")
start, err := strconv.Atoi(splitted[0])
if err != nil {
return 0, 0, err
}
end := start
if len(splitted) == 2 {
end, err = strconv.Atoi(splitted[1])
if err != nil {
return 0, 0, err
}
}
if start > end {
return 0, 0, errors.New("wrong range. start line cannot be larger than end line")
}
return start, end, nil
}
当您选中一行或多行并高亮它们时，编辑器将使用此模式。
对于偏移量和结构体名称选择，咱们须要作更多的工做。首先须要收集全部给定的结构体，以即可以计算偏移位置或查找结构体名称。为此，咱们首先要有一个收集全部结构体的函数：
// collectStructs collects and maps structType nodes to their positions
func collectStructs(node ast.Node) map[token.Pos]*structType {
structs := make(map[token.Pos]*structType, 0)
collectStructs := func(n ast.Node) bool {
t, ok := n.(*ast.TypeSpec)
if !ok {
return true
}
if t.Type == nil {
return true
}
structName := t.Name.Name
x, ok := t.Type.(*ast.StructType)
if !ok {
return true
}
structs[x.Pos()] = &structType{
name: structName,
node: x,
}
return true
}
ast.Inspect(node, collectStructs)
return structs
}
咱们使用 ast.Inspect() 函数逐步遍历 AST 并查找结构体。
咱们首先查找 *ast.TypeSpec，以便得到结构体名称。查找 *ast.StructType 时给定的是结构体自己，而不是它的名字，这就是为何咱们有一个自定义的 structType 类型，它保存了名称和结构体节点自己。这样在各个地方都很方便，由于每一个结构体的位置都是惟一的，而且在同一位置上不可能存在两个不一样的结构体，所以咱们使用位置做为 map 的键。
如今咱们拥有了全部结构体，在最后能够为偏移量和结构体名称模式返回一个结构体的起始位置和结束位置。对于偏移位置，咱们检查偏移是否在给定的结构体之间：
func (c *config) offsetSelection(file ast.Node) (int, int, error) {
structs := collectStructs(file)
var encStruct *ast.StructType
for _, st := range structs {
structBegin := c.fset.Position(st.node.Pos()).Offset
structEnd := c.fset.Position(st.node.End()).Offset
if structBegin <= c.offset && c.offset <= structEnd {
encStruct = st.node
break
}
}
if encStruct == nil {
return 0, 0, errors.New("offset is not inside a struct")
}
// offset mode selects all fields
start := c.fset.Position(encStruct.Pos()).Line
end := c.fset.Position(encStruct.End()).Line
return start, end, nil
}
咱们使用 collectStructs() 来收集全部结构体，以后进行迭代。还得记得咱们存储了用于解析文件的初始 token.FileSet 么？
如今能够用它来获取每一个结构体节点的偏移信息（咱们将提取出一个 token.Position，它提供了 .Offset 字段）。咱们所作的只是一个简单的检查和迭代，直到找到结构体（这里命名为 encStruct）为止：
for _, st := range structs {
structBegin := c.fset.Position(st.node.Pos()).Offset
structEnd := c.fset.Position(st.node.End()).Offset
if structBegin <= c.offset && c.offset <= structEnd {
encStruct = st.node
break
}
}
有了这些信息，咱们能够为找到的结构体提取出开始位置和结束位置：
start := c.fset.Position(encStruct.Pos()).Line end := c.fset.Position(encStruct.End()).Line
该逻辑一样适用于结构体名称选择模式。咱们所作的只是尝试检查结构体名称，直到找到与给定名称一致的结构体，而不是检查偏移量是否在给定的结构体范围内：
func (c *config) structSelection(file ast.Node) (int, int, error) {
// ...
for _, st := range structs {
if st.name == c.structName {
encStruct = st.node
}
}
// ...
}
如今有了开始位置和结束位置，咱们终于能够进行第三步了：修改结构体字段。
在 main 函数中，咱们将使用从上一步解析获得的节点来调用 cfg.rewrite() 函数：
func main() {
// ... find start and end position of the struct to be modified
rewrittenNode, errs := cfg.rewrite(node, start, end)
if errs != nil {
if _, ok := errs.(*rewriteErrors); !ok {
return errs
}
}
// continue outputting the rewritten node
}
这是该工具的核心。在 rewrite 函数中，咱们将重写开始位置和结束位置之间的全部结构体字段。在深刻了解以前，咱们能够看一下该函数的大概内容：
// rewrite rewrites the node for structs between the start and end
// positions and returns the rewritten node
func (c *config) rewrite(node ast.Node, start, end int) (ast.Node, error) {
errs := &rewriteErrors{errs: make([]error, 0)}
rewriteFunc := func(n ast.Node) bool {
// rewrite the node ...
}
if len(errs.errs) == 0 {
return node, nil
}
ast.Inspect(node, rewriteFunc)
return node, errs
}
正如你所见，咱们再次使用 ast.Inspect() 来逐步处理给定节点树。咱们在 rewriteFunc 函数中重写每一个字段的标签（更多内容在后面）。
由于传递给 ast.Inspect() 的函数不会返回错误，所以咱们将建立一个错误映射（使用 errs 变量定义），以后在遍历树并处理每一个单独的字段时收集错误。如今让咱们来谈谈 rewriteFunc 的内部原理：
rewriteFunc := func(n ast.Node) bool {
x, ok := n.(*ast.StructType)
if !ok {
return true
}
for _, f := range x.Fields.List {
line := c.fset.Position(f.Pos()).Line
if !(start <= line && line <= end) {
continue
}
if f.Tag == nil {
f.Tag = &ast.BasicLit{}
}
fieldName := ""
if len(f.Names) != 0 {
fieldName = f.Names[0].Name
}
// anonymous field
if f.Names == nil {
ident, ok := f.Type.(*ast.Ident)
if !ok {
continue
}
fieldName = ident.Name
}
res, err := c.process(fieldName, f.Tag.Value)
if err != nil {
errs.Append(fmt.Errorf("%s:%d:%d:%s",
c.fset.Position(f.Pos()).Filename,
c.fset.Position(f.Pos()).Line,
c.fset.Position(f.Pos()).Column,
err))
continue
}
f.Tag.Value = res
}
return true
}
记住，AST 树中的每个节点都会调用这个函数。所以，咱们只寻找类型为 *ast.StructType 的节点。一旦找到，咱们就能够开始迭代结构体字段。
这里咱们使用 start 和 end 变量。这定义了是否要修改该字段。若是字段位置位于 start 和 end 之间，咱们将继续，不然忽略：
if !(start <= line && line <= end) {
continue // skip processing the field
}
接下来，咱们检查是否存在标签。若是标签字段为空（也就是 nil），则初始化标签字段，避免后面的 cfg.process() 函数触发 panic：
if f.Tag == nil {
f.Tag = &ast.BasicLit{}
}
如今让我先解释一个有趣的地方，而后再继续。gomodifytags 尝试获取字段的字段名称并处理它。然而，当它是一个匿名字段呢？：
type Bar string
type Foo struct {
Bar //this is an anonymous field
}
在这种状况下，由于没有字段名称，咱们尝试从类型名称中获取字段名称：
// if there is a field name use it
fieldName := ""
if len(f.Names) != 0 {
fieldName = f.Names[0].Name
}
// if there is no field name, get it from type's name
if f.Names == nil {
ident, ok := f.Type.(*ast.Ident)
if !ok {
continue
}
fieldName = ident.Name
}
一旦咱们得到了字段名称和标签值，就能够开始处理该字段。cfg.process() 函数负责处理有字段名称和标签值（若是有的话）的字段。在它返回处理结果后（在咱们的例子中是 struct tag 格式），咱们使用它来覆盖现有的标签值：
res, err := c.process(fieldName, f.Tag.Value)
if err != nil {
errs.Append(fmt.Errorf("%s:%d:%d:%s",
c.fset.Position(f.Pos()).Filename,
c.fset.Position(f.Pos()).Line,
c.fset.Position(f.Pos()).Column,
err))
continue
}
// rewrite the field with the new result,i.e: json:"foo"
f.Tag.Value = res
实际上，若是你记得 structtag，它返回标签实例的 String() 表述。在咱们返回标签的最终表述以前，咱们根据须要使用 structtag 包的各类方法修改结构体。如下是一个简单的说明图示：
例如，咱们要扩展 process() 中的 removeTags() 函数。此功能使用如下配置来建立要删除的标签数组（内容键名称）：
flagRemoveTags = flag.String("remove-tags", "", "Remove tags for the comma separated list of keys")
if *flagRemoveTags != "" {
cfg.remove = strings.Split(*flagRemoveTags, ",")
}
在 removeTags() 中，咱们检查是否使用了 --remove-tags。若是有，咱们将使用 structtag 的 tags.Delete() 方法来删除标签：
func (c *config) removeTags(tags *structtag.Tags) *structtag.Tags {
if c.remove == nil || len(c.remove) == 0 {
return tags
}
tags.Delete(c.remove...)
return tags
}
此逻辑一样适用于 cfg.Process() 中的全部函数。
咱们已经有了一个重写的节点，让咱们来讨论最后一个话题：输出和格式化结果：
在 main 函数中，咱们将使用上一步重写的节点来调用 cfg.format() 函数：
func main() {
// ... rewrite the node
out, err := cfg.format(rewrittenNode, errs)
if err != nil {
return err
}
fmt.Println(out)
}
您须要注意一件事，咱们输出到 stdout。这佯作有许多优势。首先，您只需运行工具就能查看到结果，它不会改变任何东西，只是为了让工具用户当即看到结果。其次，stdout 是可组合的，能够重定向到任何地方，甚至能够用来覆盖原来的工具。
如今咱们来看看 format() 函数：
func (c *config) format(file ast.Node, rwErrs error) (string, error) {
switch c.output {
case "source":
// return Go source code
case "json":
// return a custom JSON output
default:
return "", fmt.Errorf("unknown output mode: %s", c.output)
}
}
咱们有两种输出模式。
第一个（source）以 Go 格式打印 ast.Node。这是默认选项，若是您在命令行使用它或只想看到文件中的更改，那么这很是适合您。
第二个选项（json）更为先进，其专为其余环境而设计（特别是编辑器）。它根据如下结构体对输出进行编码：
type output struct {
Start int `json:"start"`
End int `json:"end"`
Lines []string `json:"lines"`
Errors []string `json:"errors,omitempty"`
}
对工具进行输入和最终结果输出（没有任何错误）的大概示意图以下：
回到 format() 函数。如以前所述，有两种模式。source 模式使用 go/format 包将 AST 格式化为 Go 源码。该软件包也被许多其余官方工具（如 gofmt）使用。如下是 source 模式的实现方式：
var buf bytes.Buffer
err := format.Node(&buf, c.fset, file)
if err != nil {
return "", err
}
if c.write {
err = ioutil.WriteFile(c.file, buf.Bytes(), 0)
if err != nil {
return "", err
}
}
return buf.String(), nil
format 包接受 io.Writer 并对其进行格式化。这就是为何咱们建立一个中间缓冲区（var buf bytes.Buffer）的缘由，当用户传入一个 -write 标志时，咱们可使用它来覆盖文件。格式化后，咱们返回缓冲区的字符串表示形式，其中包含格式化后的 Go 源代码。
json 模式更有趣。由于咱们返回的是一段源代码，所以咱们须要准确地呈现它本来的格式，这也意味着要把注释包含进去。问题在于，当使用 format.Node() 打印单个结构体时，若是它们是游离的，则没法打印出 Go 注释。
什么是游离注释（lossy comment）？看看这个例子：
type example struct {
foo int
// this is a lossy comment
bar int
}
每一个字段都是 *ast.Field 类型。此结构体有一个 *ast.Field.Comment 字段，其包含某字段的注释。
可是，在上面的例子中，它属于谁？属于 foo 仍是 bar？
由于不可能肯定，这些注释被称为游离注释。若是如今使用 format.Node() 函数打印上面的结构体，就会出现问题。当你打印它时，你可能会获得（https://play.golang.org/p/peHsswF4JQ）：
type example struct {
foo int
bar int
}
问题在于游离注释是 *ast.File 的一部分，它与树分开。只有打印整个文件时才能打印出来。因此解决方法是打印整个文件，而后删除掉咱们要在 JSON 输出中返回的指定行：
var buf bytes.Buffer
err := format.Node(&buf, c.fset, file)
if err != nil {
return "", err
}
var lines []string
scanner := bufio.NewScanner(bytes.NewBufferString(buf.String()))
for scanner.Scan() {
lines = append(lines, scanner.Text())
}
if c.start > len(lines) {
return "", errors.New("line selection is invalid")
}
out := &output{
Start: c.start,
End: c.end,
Lines: lines[c.start-1 : c.end], // cut out lines
}
o, err := json.MarshalIndent(out, "", " ")
if err != nil {
return "", err
}
return string(o), nil
这样作确保咱们能够打印全部注释。
这就是所有内容！
咱们成功完成了这个工具，如下是咱们在整个指南中实施的完整步骤图：
回顾一下咱们作了什么：
- 咱们经过 CLI flag 获取配置
- 咱们经过
go/parser包解析文件来获取一个ast.Node。 - 在解析文件以后，咱们搜索 获取相应的结构体来获取开始位置和结束位置，这样咱们就能够知道须要修改哪些字段
- 一旦有了开始位置和结束位置，咱们再次遍历
ast.Node，重写开始位置和结束位置之间的每一个字段（经过使用structtag包） - 以后，咱们将格式化重写的节点，为编辑器输出 Go 源代码或自定义的 JSON
在建立此工具后，我收到了不少好评，评论者们提到了这个工具如何简化他们的平常工做。正如您所看到，尽管看起来它很容易编写，但在整篇指南中，咱们已经针对许多特殊的状况作了特别处理。
gomodifytags 在如下编辑器和插件中已经成功应用有几个月了，使得数以千计的开发人员提高了工做效率：
- vim-go
- atom
- vscode
- acme
若是您对该项目的源代码感兴趣，能够访问如下仓库连接：
此外，我还在 Gophercon 2017 上发表了一个演讲，若是您感兴趣，可点击下面的 youtube 连接观看：
谢谢您阅读此文。但愿这篇指南能给您启发。
- 1. [译] Go 终极指南：编写一个 Go 工具
- 2. 用Go语言编写一门工具的终极指南
- 3. 搭建go tour(go指南)
- 4. Go 语言“可变参数函数”终极指南
- 5. 一个小时学会用 Go 编写命令行工具
- 6. Java程序员学习Go指南（终）
- 7. Go Modules 终极入门
- 8. Go入门指南
- 9. Go学习指南
- 10. Go语法指南
- 更多相关文章...
- • XML 指南 - 网站建设指南
- • JavaScript 指南 - 网站建设指南
- • PHP开发工具
- • 算法总结-双指针
-
每一个你不满意的现在，都有一个你没有努力的曾经。
- 1. [译] Go 终极指南：编写一个 Go 工具
- 2. 用Go语言编写一门工具的终极指南
- 3. 搭建go tour(go指南)
- 4. Go 语言“可变参数函数”终极指南
- 5. 一个小时学会用 Go 编写命令行工具
- 6. Java程序员学习Go指南（终）
- 7. Go Modules 终极入门
- 8. Go入门指南
- 9. Go学习指南
- 10. Go语法指南