Go generate 未执行指令的注释与目录检查

Go generate 没有执行预期指令时，先分清它是没被识别、没被选中，还是执行后失败或写到了其他位置。指令需采用准确的行注释格式，目标包需属于本次命令范围；生成器在包源码目录运行。go build 与 go test 不会自动替你执行生成步骤。

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

为什么写了注释却没有运行？

设想项目在 internal/catalog 中声明生成规则，开发者只在模块根目录执行构建，随后发现常量文件没有更新。我会先核对实际调用了什么命令，而不是先改生成器。这个原创情境用于解释排查顺序，不是本文已经执行的项目记录。

“注释存在”只表示源文件保存了一条指令文本，不能说明工具已经扫描这份文件，也不能说明子进程完成。把这几个状态分别记录，通常就能避免把目录问题误诊为 Go 工具链故障。

先查哪些格式和包选择问题？

有效指令以行首的 //go:generate 开始，不应缩进，也不能写成 // go:generate。随后检查文件是否属于所选包、是否受构建约束影响，以及命令的 -run 或 -skip 是否过滤了它。过滤匹配针对整条指令文本，不能只凭生成器名称猜测结果。

我倾向于先指定单个目标包，这样输出更容易与指令文件对应。只有生成责任已经整理清楚，才扩大到多个包。为排障盲目执行整个仓库的生成脚本，会混入与当前问题无关的产物变更。

怎样建立可理解的最小生成布局？

下面的示例采用一个模块，go.mod 位于根目录；internal/catalog/generate.go 保存指令；internal/catalog/cmd/cataloggen/main.go 保存生成器。生成结果为 internal/catalog/catalog_gen.go。两个源码文件按下面内容分别保存即可，本文未运行它们。

generate.go 的完整内容：

package catalog

// 生成器路径相对本包目录，输出也写入本包。
//go:generate go run ./cmd/cataloggen -out catalog_gen.go

cmd/cataloggen/main.go 的完整内容：

package main

import (
    "flag"
    "fmt"
    "go/format"
    "os"
)

func main() {
    out := flag.String("out", "catalog_gen.go", "生成文件路径")
    flag.Parse()

    // 演示固定生成一份包内常量，不依赖网络或外部模板。
    src := []byte("// Code generated by cataloggen. DO NOT EDIT.\n" +
        "package catalog\n\nconst CatalogSchema = 3\n")
    data, err := format.Source(src)
    if err != nil {
        fmt.Fprintln(os.Stderr, "格式化生成内容失败:", err)
        os.Exit(1)
    }
    if err := os.WriteFile(*out, data, 0644); err != nil {
        // 写入失败必须返回非零退出码，不能假装成功。
        fmt.Fprintln(os.Stderr, "写入生成文件失败:", err)
        os.Exit(1)
    }
}

生成器按设计写出 CatalogSchema 常量。这里故意不读取外部模板或远程接口，方便把指令发现、路径解析和写文件三个问题隔离开。真实项目可以换成自己的输入和生成逻辑，但仍应显式接受输出路径并在失败时返回错误。

阅读者可在自己的示例目录中执行以下命令。这里没有附实际输出，也不声称本文完成了代码运行验证。

# 从模块根目录选择资源所属包，打印处理位置和实际命令。
go generate -v -x ./internal/catalog

# 只有确需处理当前模块所有匹配包时才扩大范围。
go generate -v -x ./...

# 生成结束后再检查该包是否满足使用要求。
go test ./internal/catalog

为什么路径和 shell 参数与预期不同？

生成器工作目录是包源码目录。因此示例中的 ./cmd/cataloggen 相对 internal/catalog，而不是模块根目录；-out catalog_gen.go 也将输出放在该包中。若脚本误以为起点是根目录，就可能读错模板或把文件写入意外目录。

参数解析也不是一般 shell 脚本。双引号按 Go 字符串规则处理，环境变量可以展开，但通配符不会自动替换为文件列表。不要把管道或重定向符号直接塞进指令后，期待它们自然变成 shell 操作。

示例选择用 Go 程序自己写文件，避免依赖重定向语法。若已有项目必须调用 shell，需显式选择对应解释器并承担平台差异；不要仅为了少写一个输出参数而引入隐含执行环境。

另外，外部命令必须在执行环境中可找到。若使用依赖 PATH 的工具，开发机安装成功并不代表流水线也安装了相同版本。本文示例用包内 Go 生成器，工具输入随源码一起管理，依旧需要可用的 Go 环境。

出现前置失败和缺失产物时如何处理？

生成命令按规定顺序处理；同一包内某个生成器返回错误后，后续处理会停止。后面的指令没有运行，不一定是它本身有格式问题。先查看最早失败的位置，再检查所需输入是否已经具备。

项目应为每份产物明确拥有者：哪条指令负责生成、输入是什么、输出放在哪里、失败如何返回。本文生成器通过 -out 接收位置，并检查格式化与写入错误。若实际工具失败仍以成功退出，下游只会看到旧文件继续存在，排障就更困难。

若脚本本来就允许“不更新文件”，也应解释判断条件。例如输入没有变化时可以不重写；但这与命令没有被执行是两回事。必要时在生成器中增加清晰、简短的状态说明，不要单靠文件时间戳判定。

延伸问题：生成标签、构建与结果判断

有生成专用文件，正常构建却不需要它，怎么办？

go generate 会设置 generate 构建标签，可用于管理生成专用声明。使用前仍需检查文件选择条件，不能把任意未选中的文件都归因于工具忽略注释。

为什么构建成功，生成结果却仍是旧的？

旧产物可能本来就能满足编译。构建成功只说明当前源码可编译，不说明生成步骤运行过。应在流水线中明确安排生成，并按项目约定检查产物内容。

怎样确认已经修好？

先确认目标指令确实进入执行集合并正常结束，再确认预期位置出现正确内容。对本文示例，最终应检查 catalog 包中的 CatalogSchema，而不是根目录里某份同名文件。真实项目还需检查生成内容是否对应本次输入。

参考：Go generate 指令、执行目录与参数规则。