go generate -run 怎样只执行指定生成指令

项目里同时放着 mock、枚举字符串和资源文件生成指令时，直接执行 go generate ./... 往往会把整套生成任务全部拉起来。真正需要修一处 mock 时，最稳妥的做法不是手动注释其他指令，而是用 go generate -run 按指令原文做正则筛选。

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

这篇只解决一个边界：怎样从已有的 //go:generate 指令中选中目标项。关键点是，-run 看到的是整行指令原文，不是“生成器名称”这个抽象字段；因此先看原文，再写正则，局部重生成才不会误伤其他任务。

影响面：一次全量生成为什么会放大问题

假设一个包里有三类指令：

//go:generate mockgen -source=store.go -destination=store_mock.go
//go:generate stringer -type=State -output=state_string.go
//go:generate go run ./cmd/embedassets -input=assets -output=assets_gen.go

开发者只修改了 store.go，却运行了 go generate ./...。结果可能是三类生成器都启动，耗时更长，生成文件的变更范围也变大，代码评审很难判断哪些变化和本次修改有关。这里的问题不是某个生成器“坏了”，而是入口没有表达“只重跑哪一种指令”。

触发条件：先把真正可匹配的原文列出来

Go 官方文档规定，生成指令必须是没有前导空格的 //go:generate command argument... 行。go generate 会扫描源文件中的这类指令，并按文件名和指令出现顺序处理。-run 的正则作用在完整原文上，所以示例中的可匹配文本分别是：

根因：用 -run 把目标生成指令筛出来

最小用法是把正则作为 -run 的值，再指定需要扫描的包：

# 只匹配包含 mockgen 的生成指令，再扫描当前模块下的包
go generate -run 'mockgen' ./...

为了减少误选，工程脚本里更推荐匹配指令开头：

# ^ 固定从指令起点匹配，空格保留在表达式中以区分命令名
go generate -run '^//go:generate mockgen ' ./...

# 组合两个明确的生成器前缀，括号内任一分支命中即可
go generate -run '^(//go:generate mockgen |//go:generate stringer )' ./...

这里有两个容易忽略的细节。第一，正则表达式匹配的是包含 //go:generate 的整行原文，因此只写 mockgen 也能命中，但它的边界比完整前缀宽。第二，^ 和结尾空格可以把匹配锚定到命令开头；如果还要限制参数，可以继续补上路径或选项，并在需要时使用 $ 收尾。

修复动作：先预览，再决定是否执行

在第一次写正则时，我会先加 -n。它只打印将要执行的命令，不真正运行生成器；确认命中范围后，再去掉 -n。如果需要观察 Go 实际准备执行的命令，可以用 -x：

# 先预览目标范围，避免一上来就改动生成文件
go generate -n -run '^//go:generate mockgen ' ./...

# 确认范围后执行，并打印实际执行命令
go generate -x -run '^//go:generate mockgen ' ./...

当规则需要“包含 A，但排除某个特殊参数”时，可以配合 -skip。例如保留普通 mock 生成，跳过带有 legacy 标记的指令：

# -skip 优先排除同时命中 -run 的指令
go generate -run 'mockgen' -skip 'legacy' ./...

-skip 也按完整指令原文匹配；如果一条指令同时命中 -run 和 -skip，它会被跳过。这个组合适合逐步收窄规则，但不要用一长串难以维护的例外掩盖指令命名混乱。

防复发：脚本还要处理执行边界

go generate 不是编译流程的隐式步骤。它不会因为执行 go build、go test 或 go run 就自动触发，所以 CI 里应该把生成动作写成显式命令，并让筛选范围由脚本参数或固定约定表达。

# CI 中显式生成指定类型的代码，再进入测试阶段
go generate -run '^//go:generate mockgen ' ./...
go test ./...

还要留意失败边界：同一个包内如果某个生成器返回错误状态，后续生成指令不会继续处理这个包；生成器运行目录是对应包的源目录。也就是说，-run 只能减少候选指令，不能替代对生成器退出状态和输出变更的处理。

我通常会在代码评审约定里固定三件事：第一，指令开头使用稳定的生成器或别名；第二，局部重生成命令先用 -n 预览；第三，生成脚本执行成功后再检查生成文件是否进入预期目录。这样下一次只修 mock 时，筛选规则就是可读的工程入口，而不是临时试错。

常见问题

-run mockgen 会只匹配命令名吗？

它是在完整 //go:generate ... 原文上应用正则，写成 mockgen 时通常会命中包含该文本的指令。若要更严格，使用带 ^//go:generate mockgen 的前缀。

为什么加了 -run 仍然没有生成文件？

先用 -n 看是否命中，再确认扫描的包范围和源文件中的指令格式。还要确认你确实显式执行了 go generate，因为构建和测试命令不会自动触发它。

可以用 -run 直接按生成文件名匹配吗？

不能把它理解成按输出文件名筛选。它匹配的是指令原文；如果输出文件名没有写在指令里，就没有可供正则匹配的文件名文本，应改为按生成器、参数或自定义指令前缀筛选。

-run 和 -skip 同时命中时谁优先？

-skip 优先，既命中 -run 又命中 -skip 的指令会被跳过。