最轻量、最 go-native 的代码生成方式是直接用 go:generate 触发脚本；需确保脚本可执行、路径正确、输出在当前包目录、注释格式严格顶格，且生成文件含标准头部注释并避免构建约束冲突。
直接用 go:generate 触发脚本，而不是写 Makefile 或 CI 脚本去绕路调用——这是最轻量、最 Go-native 的方式，且能和 IDE、go build 流程自然对齐。
怎么让 Python/Shell 脚本被 go generate 安全调用
Go 不解析 shell 变量，也不加载你的 .bashrc，所以别写 //go:generate python3 ./gen.py $GOFILE 这种带 $ 的命令——它会字面量传参，根本不会展开。
- 预定义变量只有
${GOFILE}、${GOPACKAGE}、${GODIR}等几个，且仅在 Go 1.19+ 稳定支持；低版本建议全用相对路径 + 显式传参 - 脚本必须在
PATH中，或写绝对路径（推荐用$(go env GOPATH)/bin/gen这类可复现路径） - Python 脚本第一行加
#!/usr/bin/env python3，并chmod +x；否则go generate在某些系统上会报exec format error - 输出文件务必写进当前包目录（如
./models_gen.go），否则go build找不到它
go:generate 注释写在哪、怎么写才不踩坑
注释必须出现在 *.go 源文件里，且顶格、无空格、紧跟 //go:generate —— 写成 // go:generate（前面有空格）或放在 .md 里，go generate 就直接忽略。
- 一个文件里可以有多行
//go:generate，但它们执行顺序不确定，别让第二行依赖第一行生成的文件 - 命令里别用别名（如
gen-model），子进程不继承 shell alias；要么用完整路径，要么确保二进制在$PATH - 加
-o显式指定输出文件名，比如//go:generate stringer -type=State -o state_string.go，避免工具按约定乱放导致 Git 漏提交 - 生成文件开头必须有
// Code generated by go generate; DO NOT EDIT.注释，否则gofmt或 linter 可能误报
生成的代码没生效？先查这三个地方
go build 成功但运行时 panic，大概率是生成文件没更新或没纳入编译范围。
- 生成的目标文件是否在当前
package目录下？不在的话go build根本看不到它 - 文件是否被设为只读（比如
git checkout后权限锁死）？go generate默认不覆盖只读文件，会静默失败 - 生成的文件有没有被
//go:build ignore或其他构建约束排除？检查文件顶部是否有冲突的构建 tag - CI 环境中，记得
git add生成的文件——go mod tidy不管它，Git 也不自动跟踪
真正难的不是写生成逻辑，而是让每次 go generate 的输出稳定、可预测、不依赖环境状态。路径、权限、构建约束、文件编码，任何一个细节错位，都会让自动化变成定时失灵的黑盒。
