go generate 完全指南

争做团队核心程序员，关注「幽鬼」

开发人员有很强的自动化重复性任务的倾向，这也适用于编写代码。因此，元编程（metaprogramming）的主题是一个开发和研究的热门领域，可以追溯到 1960 年代的 Lisp。元编程中一个特别有用的领域是代码生成（code-generation）。支持宏的语言内置了此功能；其他语言扩展了现有功能以支持这一点（例如 C++模板元编程^[1]）。

虽然 Go 没有宏或其他形式的元编程，但它是一种实用语言，它包含官方工具链支持的代码生成。

自从 Go 1.4^[2] 引入 go generate 命令后，它一直广泛应用于 Go 生态系统。Go 项目本身在很多地方都依赖于 go generate；我将在后面的帖子中快速概述这些用例。

01 基础知识

让我们从一些术语开始。go generate 工作方式主要由三个参与者之间协调进行的：

• Generator：是由 go generate 调用的程序或脚本。在任何给定的项目中，可以调用多个生成器，可以多次调用单个生成器等。
• Magic comments：是 .go 文件中以特殊方式格式化的注释，用于指定调用哪个生成器以及如何调用。任何以文本 //go:generate 行开头的注释都是合法的。
• go generate : 是 Go 工具，它读取 Go 源文件、查找和解析 magic comments 并运行指定的生成器。

需要强调的是，以上是 Go 为代码生成提供的自动化的全部范围。对于其他任何事情，开发人员可以自由使用适合他们的任何工作流程。例如，go generate 应该始终由开发人员手动运行；它永远不会自动调用（比如不会作为 go build 的一部分）。此外，由于我们通常使用 Go 将二进制文件发送给用户或执行环境，因此很容易理解 go generate 仅在开发期间运行（可能就在运行 go build 之前）；Go 程序的用户不会知道哪部分代码是生成的以及如何生成的。（实际上，很多时候会在生成的文件开头加上注释，这是生成的，请别手动修改。）

这也适用于生成 module；go generate 不会运行导入包的生成器。因此，当一个项目发布时，生成的代码应该与其余代码一起 checked 和分发。

02 一个简单的例子

学习最好是动手做；为此，我创建了几个简单的 Go 项目，它们将帮助我说明这篇文章中解释的主题。第一个是samplegentool^[3]，一个基本的 Go 工具，用于模拟生成器。

这是它的完整源代码：

package main

import (
  "fmt"
  "os"
)

func main() {
  fmt.Printf("Running %s go on %s\n", os.Args[0], os.Getenv("GOFILE"))

  cwd, err := os.Getwd()
  if err != nil {
    panic(err)
  }
  fmt.Printf("  cwd = %s\n", cwd)
  fmt.Printf("  os.Args = %#v\n", os.Args)

  for _, ev := range []string{"GOARCH", "GOOS", "GOFILE", "GOLINE", "GOPACKAGE", "DOLLAR"} {
    fmt.Println("  ", ev, "=", os.Getenv(ev))
  }
}

这个工具不读任何代码，也不写任何代码；它所做的只是报告它是如何被调用的。我们很快就会了解细节。首先我们看另一个项目 - mymod^[4]。这是一个示例 Go 模块，包含 3 个文件，分为两个包：

$ tree
.
├── anotherfile.go
├── go.mod
├── mymod.go
└── mypack
    └── mypack.go

这些文件的内容只是填充物；重要的是 go:generate 这个神奇的注释。让我们以mypack/mypack.go 中的那个为例：

//go:generate samplegentool arg1 "multiword arg"

我们看到它调用带有一些参数的 samplegentool。为了使这个调用起作用，应该在 PATH 的某个地方能找到 samplegentool。这可以通过在 samplegentool项目运行 go build 来完成，以生成二进制，然后设置 PATH。现在，如果我们在 mymod 项目的根目录中运行 go generate ./...，我们将看到如下内容：

$ go generate ./...
Running samplegentool go on anotherfile.go
  cwd = /tmp/mymod
  os.Args = []string{"samplegentool", "arg1", "arg2", "arg3", "arg4"}
   GOARCH = amd64
   GOOS = linux
   GOFILE = anotherfile.go
   GOLINE = 1
   GOPACKAGE = mymod
   DOLLAR = $
Running samplegentool go on mymod.go
  cwd = /tmp/mymod
  os.Args = []string{"samplegentool", "arg1", "arg2", "-flag"}
   GOARCH = amd64
   GOOS = linux
   GOFILE = mymod.go
   GOLINE = 3
   GOPACKAGE = mymod
   DOLLAR = $
Running samplegentool go on mypack.go
  cwd = /tmp/mymod/mypack
  os.Args = []string{"samplegentool", "arg1", "multiword arg"}
   GOARCH = amd64
   GOOS = linux
   GOFILE = mypack.go
   GOLINE = 3
   GOPACKAGE = mypack
   DOLLAR = $

首先，注意 samplegentool 在它出现在 magic comment 中的每个文件上被调用；这包括子目录，因为我们 使用 ./... 模式运行 go generate。这对于在不同地方有很多生成器的大型项目来说真的很方便。

输出中有很多有趣的东西；让我们一行一行地剖析它：

• cwd 报告调用 samplegentool 的工作目录。这始终是找到带有 magic 注释的文件的目录；这由 go generate 保证，并让生成器知道它在目录树中的位置。
• os.Args 报告传递给生成器的命令行参数。正如上面的输出所示，这包括 flag 以及用引号括起来的多词参数。
• 传递给生成器的环境变量被打印出来；有关这些的完整解释，请参阅 官方文档^[5]。这里最有趣的环境变量是 GOFILE ，它指向在其中找到 magic 注释的文件名（此路径是相对于工作目录的），而 GOPACKAGE 告诉生成器，此文件属于哪个包。

03 generators（生成器） 能做什么？

现在我们已经很好地了解了 go generate 是如何调用生成器的，那么它们能做什么呢？事实上他们可以做任何我们想做的事情。毕竟，生成器是计算机程序。如前所述，生成的文件通常也会放入到源代码中，因此生成器可能只需要很少次运行。在许多项目中，开发人员不会像我在上面的示例中那样从根运行 go generate ./...；相反，他们只会根据需要在特定目录中运行特定的生成器。

在下一节中，我将深入介绍一个非常流行的生成器 — stringer工具。同时，以下是 Go 项目本身使用生成器执行的一些任务（这不是完整列表；所有用途都可以通过在 Go 源代码树中 grepping go:generate 找到）：

• gob 包使用生成器生成重复的辅助函数用于编码/解码数据。
• math/bits 包使用生成器为其提供的某些位操作生成快速查找表。
• 个别 crypto 包使用生成器为某些操作生成散列函数混洗模式和重复的汇编代码。
• 某些 crypto 包还使用生成器从特定的 HTTP URL 获取证书。显然，这些不是为了经常运行而设计的...
• net/http 使用生成器来生成各种 HTTP 常量。
• Go 运行时的源代码中有几个有趣的生成器，例如为各种任务生成汇编代码，为数学运算生成查找表等。
• Go 编译器实现使用生成器为 IR 节点生成重复的类型和方法。

此外，标准库中至少有两个地方使用生成器来实现类似泛型的功能，其中几乎重复的代码是从不同类型的现有代码中生成的，比如 sort 和 suffixarray 包。

04 深挖生成器 stringer

Go 项目中最常用的生成器之一是stringer^[6] — 一种自动为类型创建 String() 方法的工具，以便它们实现 fmt.Stringer 接口。它最常用于为枚举生成文本表示。

我们看标准库math.big 包中的一个例子；具体来说是 RoundingMode^[7] 类型，其定义如下：

type RoundingMode byte

const (
  ToNearestEven RoundingMode = iota
  ToNearestAway
  ToZero
  AwayFromZero
  ToNegativeInf
  ToPositiveInf
)

至少在 Go 1.18 之前，这是一个惯用的 Go 枚举；为了使这些枚举值的名称可打印，我们需要为这种类型实现一个 String() 方法，这会使用 switch 语句，枚举每个值及其字符串表示。这是一项非常重复的工作，stringer 工具正好派上用场。

我在一个小示例模块中^[8]复制了 RoundingMode 类型及其值， 以便我们可以更轻松地试验生成器。让我们在文件中添加适当的 magic 注释：

//go:generate stringer -type=RoundingMode

我们将快速讨论 stringer 接受的 flag。确保先安装了它：

$ go install golang.org/x/tools/cmd/stringer@latest

现在我们可以运行 go generate；因为在示例项目中，带有 magic 注释的文件位于一个子包中，所以我将从模块根目录运行它：

$ go generate ./...

如果一切设置正确，此命令成功完成后不会有任何输出。查看项目内容，会发现生成了一个名为roundingmode_string.go 的文件，内容如下：

// Code generated by "stringer -type=RoundingMode"; DO NOT EDIT.package floatimport "strconv"func _() {  // An "invalid array index" compiler error signifies that the constant values have changed.  // Re-run the stringer command to generate them again.  var x [1]struct{}  _ = x[ToNearestEven-0]  _ = x[ToNearestAway-1]  _ = x[ToZero-2]  _ = x[AwayFromZero-3]  _ = x[ToNegativeInf-4]  _ = x[ToPositiveInf-5]}const _RoundingMode_name = "ToNearestEvenToNearestAwayToZeroAwayFromZeroToNegativeInfToPositiveInf"var _RoundingMode_index = [...]uint8{0, 13, 26, 32, 44, 57, 70}func (i RoundingMode) String() string {  if i >= RoundingMode(len(_RoundingMode_index)-1) {    return "RoundingMode(" + strconv.FormatInt(int64(i), 10) + ")"  }  return _RoundingMode_name[_RoundingMode_index[i]:_RoundingMode_index[i+1]]}

工具 stringer 拥有多个代码生成策略，取决于调用它的枚举值的性质。我们的案例是最简单的案例，其中包含“单次连续运行（single consecutive run）”的值。如果这些值形成多个连续运行，stringer 将生成稍微不同的代码，如果这些值根本不形成运行，则生成另一个版本。为了娱乐和讲解，详细研究 stringer 的来源；在这里，让我们关注当前使用的策略。

首先，_RoundingMode_name 常量用于有效地将所有字符串表示形式保存在单个连续字符串中。_RoundingMode_index 用作此字符串的查找表；例如 ToZero 值为 2。_RoundingMode_index[2] 是 26，所以该代码将索引_RoundingMode_name在索引 26 中，这使我们的ToZero部（端是下一个索引，32 在这种情况下） . 因此，代码将索引到索引 26 处的 _RoundingMode_name，这将引导我们找到 ToZero 部分。

String() 中的代码有一个回调函数，以防添加更多枚举值但未重新运行 stringer 工具。在这种情况下，产生的值将是 RoundingMode(N)，其中 N 是数值。

这个回调很有用，因为 Go 工具链中没有任何内容可以保证生成的代码与源代码保持同步；如前所述，运行生成器完全是开发人员的责任。

但是 func _() 中的奇怪代码呢？首先，请注意它实际上什么也没有编译：该函数不返回任何内容，没有副作用并且不会被调用。这个函数的目的是作为 编译守卫；如果原始 enum 以与生成的代码根本不兼容的方式发生变化，并且开发人员忘记重新运行 go generate，则这是一种额外的安全性。具体来说，它将防止现有的枚举值被修改。在这种情况下，除非重新运行 go generate，否则 String() 方法可能会成功，但会产生完全错误的值。编译守卫试图通过使代码无法编译越界数组查找来捕获这种情况。

现在让我们谈谈 stringer 的工作原理；首先，阅读它的 -help 是有指导意义的：

$ stringer -helpUsage of stringer:  stringer [flags] -type T [directory]  stringer [flags] -type T files... # Must be a single packageFor more information, see:  https://pkg.go.dev/golang.org/x/tools/cmd/stringerFlags:  -linecomment      use line comment text as printed text when present  -output string      output file name; default srcdir/<type>_string.go  -tags string      comma-separated list of build tags to apply  -trimprefix prefix      trim the prefix from the generated constant names  -type string      comma-separated list of type names; must be set

我们已经使用 -type 参数告诉 stringer 为哪种类型生成 String() 方法。在现实的代码库中，人们可能希望在其中定义了多种类型的包上调用该工具；在这种情况下，我们可能希望stringer 只为特定类型生成 String() 方法。

我们没有指定 -output flag，所以使用默认值；在这种情况下，生成的文件名为 roundingmode_string.go。

眼尖的读者会注意到，当我们调用 stringer 时，我们没有指定它应该用作输入的文件。快速浏览该工具的源代码会发现它也不使用 GOFILE 环境变量。那么它如何知道要分析哪些文件呢？事实证明，stringer 使用 golang.org/x/tools/go/packages 从其当前工作目录（你还记得，这是包含 magic 注释的文件所在的目录）加载整个包。这意味着无论魔术（magic）注释在哪个文件中，stringer 默认情况下会分析整个包。如果你仔细考虑一下，这是有道理的，谁说常量必须与类型声明在同一个文件中？在 Go 中，文件只是一个方便的代码容器；包是工具关心的真正输入单位。

05 源码生成器和构建 tags

到目前为止，我们假设生成器在 go generate 运行时位于 PATH 中的某个位置，但情况并非总是如此。

考虑一个非常常见的场景，你的模块有自己的生成器，它只对这个特定的模块有用。当有人对模块进行黑客攻击时，他们能够克隆代码，运行 go generate 和 go build 等。但是，如果魔术注释假定生成器始终位于 PATH 中，则除非在运行 go generate 之前构建并正确指向生成器，否则这将无法工作。

Go 中的解决方案很简单，因为 go run 是运行生成器的完美搭配，这些生成器只是模块树中某处的 .go 文件。这里有^[9]一个简单的例子。这是一个带有神奇注释的包文件：

package mypack//go:generate go run gen.go arg1 arg2func PackFunc() string {  return "insourcegenerator/mypack.PackFunc"}

请注意此处如何调用生成器：使用 go run gen.go。这意味着 go generate 将期望在与包含魔术注释的文件相同的目录中找到 gen.go。gen.go 的内容是：

//go:build ignorepackage mainimport (  "fmt"  "os")func main() {  // ... same main() as the simple example at the top of the post}

它只是一个小的 Go 程序（在包 main 中）。唯一需要注意的是 //go:build 约束，它告诉 Go 工具链在构建项目时忽略这个文件。事实上，gen.go 不是包的一部分；它位于 main 包中，旨在与 go generate 一起运行，而不是编译到包中。

标准库中有许多小程序的示例，这些小程序旨在通过作为生成器的 go run 调用。

典型的模式是代码生成涉及 3 个文件，它们都共存于同一个目录/包中：

• 源文件包含一些包的代码，以及一条神奇的注释，用于调用带有 go run 的生成器。
• generator，它是一个单一的包含 package main 的 .go 文件; 该生成器由源文件中的魔术注释中的 go run 调用以生成生成的文件。生成器 .go 文件通常会有一个 //go:build ignore 约束，以将其从包本身的构建中排除。
• generated file 由 generator 生成; 在某些约定中，它与源文件具有相同的名称，但后跟_gen（如 pack.go --> pack_gen.go）；或者它可能是某种前缀（如 gen）。生成文件中的代码与源文件中的代码在同一个包中。在许多情况下，生成的文件包含一些未导出符号的实现细节；源文件可以在其代码中引用这一点，因为这两个文件位于同一个包中。

当然，这些都不是工具所要求的——它只是描述了一个通用的约定；特定的项目可以以不同的方式设置（例如，一个生成器为多个包生成代码）。

06 高级功能

本节讨论 go generate 的一些高级或较少使用的功能。

-command 标志

这个 flag 让我们为 go:generate 行定义别名；如果某些生成器是一个多字命令，我们想为多次调用缩短它，这可能会很有用。

最初的动机可能是将 go tool yacc 缩短为 yacc ：

//go:generate -command yacc go tool yacc

之后 yacc 可以只用这个 4 个字母的名字而不是三个词来调用多次。

有趣的是，go tool yacc在 1.8 中^[10]从核心 Go 工具链中删除了，而且我在主 Go 存储库（除了测试go generate本身）或x/tools模块中都没有发现 -command 的任何用法 。

-run 标志

该标志用于 go generate 命令本身，用于选择要运行的生成器。回想一下我们在同一个项目中调用了 3 次 samplegentool 的简单示例 。我们只能选择其中之一来使用 -run 标志运行：

$ go generate -run multi ./...Running samplegentool go on mypack.go  cwd = /tmp/mymod/mypack  os.Args = []string{"samplegentool", "arg1", "multiword arg"}   GOARCH = amd64   GOOS = linux   GOFILE = mypack.go   GOLINE = 3   GOPACKAGE = mypack   DOLLAR = $

这对于调试应该是显而易见的：在具有多个生成器的大型项目中，我们通常只想运行一个子集以进行调试/快速编辑这样的循环目的。

DOLLAR

在自动神奇地传递给生成器的环境变量（ env var ）中，有一个脱颖而出 —— DOLLAR。它是做什么用的？为什么要将 env var 专用于一个字符？在 Go 源代码树中没有使用这个 env var。

DOLLAR的起源可以追溯到Rob Pike 的这个提交^[11]。正如更改描述所说，这里的动机是将 $ 字符传递到生成器中，而无需复杂的shell escaping^[12]。如果 go generate 调用 shell 脚本或将正则表达式作为参数的东西，这很有用。

可以使用我们的 samplegentool 生成器观察 DOLLAR 的效果。如果我们将其中一个神奇的注释更改为：

//go:generate samplegentool arg1 $somevar

生成器报告其参数为

os.Args = []string{"samplegentool", "arg1", ""}

这是因为 $somevar 被 shell 解释为引用 somevar 变量，该变量不存在，因此其默认值为空。相反，我们可以如下使用 DOLLAR：

//go:generate samplegentool arg1 ${DOLLAR}somevar

然后生成器报告：

os.Args = []string{"samplegentool", "arg1", "$somevar"}

原文链接：https://eli.thegreenplace.net/2021/a-comprehensive-guide-to-go-generate/

参考资料

[1]

C++模板元编程: https://en.wikipedia.org/wiki/Template_metaprogramming

[2]

Go 1.4: https://go.dev/blog/generate

[3]

samplegentool: https://github.com/eliben/code-for-blog/tree/master/2021/go-generate-guide/samplegentool

[4]

mymod: https://github.com/eliben/code-for-blog/tree/master/2021/go-generate-guide/mymod

[5]

官方文档: https://pkg.go.dev/cmd/go#hdr-Generate_Go_files_by_processing_source

[6]

stringer: https://pkg.go.dev/golang.org/x/tools/cmd/stringer

[7]

RoundingMode: https://pkg.go.dev/math/big#RoundingMode

[8]

小示例模块中: https://github.com/eliben/code-for-blog/tree/master/2021/go-generate-guide/stringerusage

[9]

这里有: https://github.com/eliben/code-for-blog/tree/master/2021/go-generate-guide/insourcegenerator

[10]

在 1.8 中: https://tip.golang.org/doc/go1.8#tool_yacc

[11]

Rob Pike 的这个提交: https://go-review.googlesource.com/c/go/+/8091/

[12]

shell escaping: http://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Quoting

---

往期推荐

欢迎关注「幽鬼」，像她一样做团队的核心。