Go go generate把生成结果纳入构建前检查的实践示例

项目里只要有代码生成，就会遇到一个很具体的风险：源定义已经改了，生成文件却还停在上一次结果。此时本地可能因为缓存或旧文件仍能编译，换一台机器或进入 CI 才暴露问题。比较稳妥的做法是把 go generate 放在构建前，先刷新生成结果，再检查工作区是否出现未提交差异，最后才执行 go build 或 go test。

一、先把 go generate 和 go build 分成两个阶段

Go 官方对这两个命令的边界很清楚：go generate 会扫描源文件里的特殊注释并执行命令，但它没有依赖分析，也不是 go build 的隐式前置步骤。也就是说，构建成功只说明当前目录里的文件能编译，不能证明这些文件已经由最新输入生成。

因此，构建前检查的顺序应固定成：

二、为生成命令建立可重复入口

生成入口应放在普通的、不会被生成器覆盖的 Go 文件里。指令必须从行首开始写成 //go:generate，后面接要执行的命令。下面用一个本地脚本模拟生成器，重点是展示输入文件、输出文件和退出码如何固定下来。

package schema

//go:generate go run ./cmd/schema-gen -input schema.yaml -output zz_schema_gen.go

// SchemaMarker 让这个文件保持为稳定的生成入口，不承载生成结果。
type SchemaMarker struct{}

生成器本身也要明确失败边界：输入不存在时返回非零状态，成功时只写入约定的输出文件。不要让命令依赖开发者当前目录下偶然存在的临时文件。进入模块目录后可以先单独运行：

# 先刷新本模块声明的全部生成文件
go generate ./...

# 再确认生成结果能够被构建工具读取
go build ./...

三、把生成结果变成构建前的硬检查

仅仅执行 go generate 还不够，因为生成器可能已经成功运行，但结果没有被提交。一个简单而有效的检查是：在干净工作树中先生成，再查看差异；如果发现变化，就让检查失败，把差异交给提交者处理。

#!/usr/bin/env bash
set -euo pipefail

# 生成命令失败时立即停止，避免拿半成品继续构建。
go generate ./...

# 只允许生成阶段不留下差异；其他手工改动也应在 CI 中单独管理。
if ! git diff --exit-code -- '*.go' '*.gen' '*.yaml'; then
  echo '生成结果与仓库内容不一致，请提交更新后的生成文件' >&2
  exit 1
fi

# 差异检查通过后，才进入真正的编译和测试阶段。
go build ./...
go test ./...

如果仓库允许本地未提交的业务改动，可以把检查范围收窄到生成文件，例如 zz_*.go 或工具约定的目录。关键不在于复制这段脚本，而在于先定义“哪些输出由生成器负责”，再用差异检查表达这条规则。

四、处理工具、路径与提交边界

这里最容易混淆的是“谁需要生成工具”。go generate 面向包作者，调用的程序未必安装在下游使用者机器上；如果生成文件是一个可导入包的一部分，生成并测试通过后通常应把结果纳入源码仓库。这样使用者执行 go get 或构建依赖时，不必重新安装你的生成器。

团队可以把下面几项写入项目约定：

• 生成工具固定在模块内的命令目录，或通过明确的工具依赖安装。
• 输入文件和输出文件命名稳定，避免把临时目录或本机绝对路径写进结果。
• 生成文件顶部保留机器生成标识，人工修改统一回到输入文件。
• CI 的生成日志保留命令名、输出路径和失败原因，但不把敏感环境变量拼进日志。

五、提交前检查清单

日常开发不必记很多规则，按“改输入—跑生成—看差异—跑构建”四步检查即可：

1. 确认本次改动是否触及生成输入，例如 schema、常量或模板。
2. 在模块根目录运行 go generate ./...，确认所有指令都执行成功。
3. 只审阅生成文件的预期差异，确认没有临时路径、机器名或无关格式变化。
4. 差异已纳入提交后，再执行 go build ./... 和 go test ./...。

这套流程的价值不是让构建工具替你猜测生成依赖，而是把“生成结果是否新鲜”变成可见、可失败、可修复的检查点。

相关问题

go build 会自动执行 go generate 吗？

不会。需要在构建脚本、CI 或开发流程中显式调用 go generate。

生成文件一定要提交到仓库吗？

取决于使用者是否需要在没有生成工具的环境中直接构建；可导入的库通常更适合提交已生成且经过测试的结果。

为什么生成后要检查 git diff？

因为命令成功不代表结果已同步到仓库，差异检查可以尽早发现过期或漏提交的生成文件。