Go go generate让生成脚本可重复执行的工程方案

Go 的代码生成要做到可重复执行，关键不是把命令写得更长，而是把“输入、工具、工作目录和输出”固定下来，再用第二次生成的差异结果约束它。go generate只执行源码中的//go:generate指令，不会被go build或go test自动触发。

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

一、把生成契约写进 go:generate 指令

先把生成动作放到普通、可提交的 Go 源文件里。指令必须从行首开始，//和go:generate之间不能有空格。下面的例子假定 schema.json 是输入，生成器负责写出 internal/generated/config.go。

package config

// 生成契约固定输入与输出，开发者只需要执行 go generate。
//go:generate go run ./cmd/configgen -input schema.json -output internal/generated/config.go

// Config 是手写代码使用的稳定入口，生成文件不在这里添加业务逻辑。
type Config struct {
    Name string
}

这条指令的工程价值在于把“谁来生成、读什么、写到哪里”放进版本库。不要在脚本里拼接开发者的绝对路径，也不要把一次性的临时目录当成输出目录。生成器如果需要多个单词组成的命令，可以用 -command 在当前源文件内定义别名。

二、让生成器使用稳定的工作目录与环境变量

go generate会在包含指令的包目录中运行生成器，所以相对路径应以这个目录为基准。生成器不要假设命令从仓库根目录启动；如果确实需要根目录资源，可以把根目录作为明确参数传入，或沿目录查找并在找不到时返回清晰错误。

// 生成器读取 go generate 提供的环境变量，避免硬编码源文件名。
source := os.Getenv("GOFILE")
pkg := os.Getenv("GOPACKAGE")
if source == "" || pkg == "" {
    return fmt.Errorf("缺少 GOFILE 或 GOPACKAGE，必须通过 go generate 调用")
}

// 输出文件先写入临时文件，再原子替换，避免中途失败留下半个结果。
tmp, err := os.CreateTemp(filepath.Dir(output), ".generated-*")
if err != nil {
    return fmt.Errorf("创建临时文件失败: %w", err)
}
defer os.Remove(tmp.Name())
// 省略生成内容写入与格式化逻辑。
if err := tmp.Close(); err != nil {
    return fmt.Errorf("关闭临时文件失败: %w", err)
}
if err := os.Rename(tmp.Name(), output); err != nil {
    return fmt.Errorf("替换生成文件失败: %w", err)
}

这里的重点不是必须使用某一种临时文件 API，而是让失败具备可恢复性：输入缺失时立即退出，输出写完且关闭后再替换。生成器还应该固定排序规则，不能把 map 的随机遍历顺序直接写入源码。

三、控制输出边界并标记生成文件

生成文件应只包含机器负责的内容，手写扩展点放到另一个文件。文件开头可以使用 Go 工具链识别的标记，告诉维护者不要直接编辑它：

// Code generated by configgen; DO NOT EDIT.

package generated

// GeneratedName 返回由 schema 生成的常量。
const GeneratedName = "demo"

输出边界可以按下面的清单检查：

如果生成文件要被下游模块或发布包使用，就应像普通源文件一样提交并测试。不要把“客户端也能在安装时生成”当作默认前提，因为客户端环境未必安装了对应生成器。

四、用重复运行和差异检查验证幂等性

幂等性不是指每次都生成相同时间戳，而是相同输入、工具和参数下，第二次运行不会制造无意义变更。可以在本地和 CI 使用同一组检查：

# 先生成，再检查生成后的源码格式。
go generate ./...
gofmt -w internal/generated/*.go

# 第二次生成不应产生新的源码差异；有差异就让 CI 失败。
go generate ./...
git diff --exit-code -- internal/generated

若第二次总有 diff，优先排查四件事：输出中是否包含当前时间或绝对路径；map、目录或依赖列表是否未排序；工具版本是否由 PATH 随机决定；生成器是否把自身的临时文件也扫进输入。把这些变量拿掉后，再考虑是否需要缓存。

相关问题

go build 会自动执行 go generate 吗？

不会。生成必须显式执行；构建流程应明确安排 go generate，或者直接提交已经生成并测试过的文件。

生成器应该放在 PATH 还是仓库里？

团队协作更适合放在仓库内并固定依赖版本；如果使用外部工具，也要在文档和 CI 中锁定版本及安装方式。

为什么输出文件每次内容都不一样？

通常是时间、绝对路径、随机遍历顺序或工具版本漂移造成的。先记录输入和参数，再逐项消除非业务变量。