Go go generate为代码生成命令传递参数的配置方法

我在把 schema 生成代码接进 Go 项目时，最容易写错的不是生成器本身，而是参数边界：路径里有空格时被拆开，变量展开后变成空字符串，或者把 go generate 误当成会替你执行一整段 shell。结论很简单：参数就写在 //go:generate 后面，按空格形成参数；需要保留空格的值用双引号包住，重复命令可用 -command 起别名。

官方资料：https://go.dev/src/cmd/go/internal/generate/generate.go

先记住：让生成器自己用 flag 定义参数契约，指令只负责传递值。这样输入文件、输出文件和包名都能在代码评审中直接看懂。

把参数直接写在 go:generate 指令中

生成指令必须从行首的 //go:generate 开始。命令名后面的每个空格分隔项都会成为生成器收到的一个参数，最适合放稳定的输入、输出和包名。

//go:generate go run ./cmd/gen -input "schema/user.json" -out "internal/gen/user.go" -package generated
// 生成命令显式声明输入、输出和目标包，便于评审与复现。

上面的生成器大致可以这样消费参数：

package main

import (
	"flag"
	"fmt"
	"log"
)

func main() {
	// 用 flag 固定参数名称，避免依赖参数出现的偶然位置。
	input := flag.String("input", "", "schema 输入文件")
	output := flag.String("out", "", "生成文件路径")
	packageName := flag.String("package", "generated", "目标包名")
	flag.Parse()
	if *input == "" || *output == "" {
		log.Fatal("必须同时提供 -input 和 -out")
	}
	// 实际项目中此处读取 input、生成 output，并检查写入错误。
	fmt.Printf("generate %s -> %s (%s)\n", *input, *output, *packageName)
}

用双引号保留带空格的单个参数

Go 官方实现支持空格分隔的 token 和 Go 语法的双引号字符串。比如模板标签、带空格的目录名或一段描述，都应保持为一个参数：

//go:generate go run ./cmd/gen -label "user schema" -out "internal gen/user.go"
// 双引号让 label 和 out 各自保持为一个参数，生成器无需猜测如何拼接。

这里不要套一层 sh -c 来“重新解析”参数。go generate 只做规定的引号解析和变量替换，不做 glob；把复杂逻辑放进可测试的 Go 生成器，跨 macOS、Linux、Windows 更稳。

用自动变量减少硬编码

执行生成器时，Go 会提供 $GOFILE、$GOLINE、$GOPACKAGE、$GOOS、$GOARCH、$GOROOT、$PATH 和 $DOLLAR 等上下文变量。变量在命令执行前展开，且即使写在引号内部也会展开；未设置的变量会变成空字符串。

//go:generate go run ./cmd/gen -source "$GOFILE" -package "$GOPACKAGE"
// 复用当前源文件和包上下文，避免为每个目录复制一套路径。

要注意变量不是通用配置文件。像版本号、业务开关这类稳定配置，直接写入明确的 flag 值或由生成器读取配置文件更可追踪；像当前文件名、包名、目标系统这类运行上下文，才适合使用自动变量。

用 -command 管理重复的生成器入口

同一个源文件有多条指令时，可以先定义本文件范围内的别名：

//go:generate -command gen go run ./cmd/gen
// 下面两条指令复用同一个生成器入口，但参数仍逐条显式传递。
//go:generate gen -input schema/user.json -out internal/gen/user.go
//go:generate gen -input schema/order.json -out internal/gen/order.go

-command 只影响当前源文件后面的指令，不会成为整个模块的全局配置。命令失败时，当前包后续生成会停止，所以生成器应尽早检查必填参数、输入文件和输出目录，并返回有用的错误信息。

发布前的参数排查清单

• 带空格的路径是否用一对双引号包成一个参数。
• 是否把可复用的输入、输出、包名交给 flag，而不是靠固定位置。
• 是否确认自动变量拼写正确；变量为空时，生成器是否能给出明确错误。
• 是否误以为 go generate 会做 glob、管道或 shell 运算。
• 生成文件是否保留 // Code generated ... DO NOT EDIT. 标记，并在生成失败时停止发布。

如果只需要一句配置原则，就是“指令负责传值，生成器负责校验和执行”。这样参数能在源码中审查，生成器也能用正常的单元测试覆盖异常边界。

常见问题

go generate 能直接把一个变量拆成多个参数吗？

不要依赖这种行为。变量在 token 已经形成后展开，展开结果中的空格不会再按 shell 规则重新切分。需要多个独立值时，显式写多个参数，或让生成器读取一个配置文件。

为什么生成器收到的路径和预期不同？

优先检查三处：路径是否被双引号包住、变量是否为空、指令是否依赖了 shell 的 glob 或管道。用 flag 打印并校验收到的字段，比在指令末尾继续堆 shell 语法更容易定位。