go:generate不是构建流程的一部分，仅在显式运行go generate时触发；编译器完全忽略该注释，必须人工或ci中执行go generate ./...才能生成代码。
go:generate 不是构建流程的一部分，它只在你显式调用 go generate 时才执行 —— 忘记运行它，生成代码就永远不会出现。
为什么 go:generate 命令不自动触发
Go 编译器完全忽略 //go:generate 注释；它只是静态标记。这和 //go:noinline 这类编译指令有本质区别。生成逻辑必须靠人工或 CI 显式调用 go generate 启动。
- 常见误操作：写完
//go:generate stringer -type=Status就直接go build，结果报undefined: StatusString—— 因为stringer根本没跑过 - CI 中必须加一步：
go generate ./...（注意./...才能递归扫描子包） - 本地开发建议加 Makefile 或 pre-commit hook，否则极易遗漏
//go:generate 的路径和工作目录陷阱
命令执行时的当前工作目录是 go generate 被调用时所在的目录，不是注释所在文件的目录 —— 这直接影响相对路径、-o 输出位置和导入路径解析。
- 错误写法：
//go:generate go run gen.go -o ./gen/enum.go，如果在子目录下运行go generate，./gen/会相对于该子目录，而非项目根目录 - 推荐做法：统一在项目根目录运行
go generate ./...，并在所有//go:generate行中使用绝对包路径（如github.com/you/repo/pkg/enum）和固定输出路径（如-o gen/enum_string.go） - 若必须跨包生成，用
$(go env GOPATH)/bin/yourtool显式指定二进制路径，避免$PATH混乱
如何让 go:generate 支持多平台条件生成
Go 本身不提供 //go:generate +build 这种条件语法，但可以通过 shell 命令层实现分支逻辑。
- Linux/macOS 下可用：
//go:generate sh -c "if [ \"$(uname)\" = \"Darwin\" ]; then stringer -type=OS; else stringer -type=OS -linecomment; fi" - Windows 下需用
cmd /c，且注意转义：//go:generate cmd /c "if \"%GOOS%\"==\"windows\" (stringer -type=WinEvent) else (stringer -type=UnixEvent)" - 更可靠的方式：把判断逻辑写进一个
gen.sh或gen.go脚本，再//go:generate go run gen.go—— 可读性和可维护性高得多
调试 go:generate 失败的三步法
错误信息常被吞掉或模糊，比如只显示 exit status 1。关键是要还原真实执行环境。
- 第一步：加
-x参数看实际命令：go generate -x ./pkg，它会打印出每条生成命令及其完整参数 - 第二步：复制那条失败的命令，cd 到对应目录，手动执行 —— 此时你能看到原始 stderr，比如
stringer: cannot load package "foo": import "foo" is a program, not an importable package - 第三步：检查生成工具是否支持
-v或--debug，例如mockgen -debug会输出 AST 解析过程，定位 interface 查找失败原因
最易被忽略的是：go:generate 命令里不能依赖未 go install 的本地工具二进制 —— 它只查 $PATH，不会自动 go build 当前目录下的 main.go。要么提前 go install，要么改用 go run 直接执行源码。
