Go generate 怎么让生成文件不被格式化步骤覆盖

如果执行 go generate ./... 后，紧接着的格式化脚本又把生成文件改回旧内容，问题通常不在 gofmt 本身，而在流水线里有两个“最终写入者”：一个从模板生成文件，另一个对整个目录做重写。稳妥做法是让生成器先完成内容拼装和 go/format 格式化，再用临时文件一次性替换目标；外层的 gofmt 只处理手写源码，生成步骤放在最后。

先把手写源码、生成器和结果文件分开

一个清晰的目录可以是 schema/ 保存输入，internal/gen/ 保存生成器，internal/generated/ 只保存产物。手写文件里保留一条明确指令：

//go:generate go run ./internal/gen
package catalog

go generate 扫描的是已有源文件中的指令，它不会理解模板语义，也不会替你判断某个文件是不是生成文件。生成器在包目录中运行，命令参数、相对路径和输出目录都应固定下来。把生成结果和手写代码混放，再对整个仓库执行覆盖式脚本，最容易出现“刚生成就被改回去”的错觉。

让生成器负责格式化后的最终写入

不要先把未格式化字符串写入目标，再指望外层 gofmt -w . 收尾。生成器可以直接调用 go/format，格式化成功后才进入写盘阶段：

package main

import (
	"fmt"
	"go/format"
	"os"
	"path/filepath"
)

func writeGenerated(out string, raw []byte) error {
	// 先格式化完整源码，失败时不碰旧的生成文件。
	formatted, err := format.Source(raw)
	if err != nil {
		return fmt.Errorf("format generated source: %w", err)
	}

	dir := filepath.Dir(out)
	if err := os.MkdirAll(dir, 0o755); err != nil {
		return err
	}
	tmp, err := os.CreateTemp(dir, ".generated-*.tmp")
	if err != nil {
		return err
	}
	tmpName := tmp.Name()
	defer os.Remove(tmpName) // 出错时清理临时文件，保留旧结果。

	if _, err = tmp.Write(append([]byte("// Code generated by catalog-gen; DO NOT EDIT.\n"), formatted...)); err != nil {
		tmp.Close()
		return err
	}
	if err = tmp.Close(); err != nil {
		return err
	}
	// 重命名是最后一步：成功前目标文件不会被半成品替换。
	return os.Rename(tmpName, out)
}

这里的关键不是“把 gofmt 换成另一条命令”，而是把格式化失败和写文件失败都放在目标替换之前。format.Source 只接受格式正确的 Go 源码，失败时旧的 generated.go 仍在；临时文件写完后再重命名，外层脚本也没有机会看到半截文件。

调整格式化与生成的流水线顺序

推荐把流水线写成“格式化手写源码 → 运行生成 → 检查生成结果”，而不是在生成前后对整个仓库无差别执行覆盖脚本：

# 只格式化手写目录，避免把生成目录当成普通输入。
gofmt -w ./catalog ./cmd

# 生成器拥有结果文件的最后写入权。
go generate -x ./...

# 只检查差异，不再次改写生成结果。
git diff --exit-code -- internal/generated

-x 会把实际执行的命令打印出来，适合确认究竟是哪一条指令改动了结果。若项目确实需要对生成文件做格式检查，可以在生成器内部完成，或明确执行 gofmt -d 做只读检查；不要再让第二个模板脚本写同一个目标。

生成文件被覆盖时的检查清单

生成文件顶部保留 // Code generated ... DO NOT EDIT. 标记，让工具和维护者知道它不应手工修改。真正要保留的差异应回到输入文件、模板或生成器逻辑中。

常见问题

go generate 会自动在 gofmt 后运行吗？

不会。它需要显式调用，具体先后顺序由你的脚本、Makefile 或 CI 决定。

生成文件一定不能执行 gofmt 吗？

可以格式化，但最好由生成器在写出前完成，或者只做只读检查，避免另一个步骤再次生成并覆盖同一目标。

为什么要使用临时文件？

模板错误、格式化错误或磁盘写入失败时，临时文件能隔离失败结果，旧的可用文件不会被截断。

参考：Go command 文档中的 generate 说明。