go:generate 在显式执行 go generate 命令时触发，不参与 go build 或 go test；按源码顺序执行，任一失败则中止后续；不支持 //go:embed 和 //go:build，需避免隐式环境依赖。
go:generate 指令到底在哪个阶段执行
go:generate 不是编译器指令，也不参与 go build 流程本身。它只是被 go generate 命令识别并触发的注释标记，本质是「手动调用外部命令的快捷标签」。你写 //go:generate go run gen.go，和直接在终端敲 go run gen.go 效果一致，只是位置和触发方式不同。
常见误解是以为加了这行注释，go test 或 go build 会自动执行它——不会。必须显式运行 go generate（或加 -x 参数看实际执行了什么命令）。
- 只在当前包目录下运行
go generate才会扫描该包内所有.go文件里的go:generate行 - 子目录需单独进入执行，或用
go generate ./...递归触发 - 如果命令路径含空格或特殊字符（比如
go:generate bash -c "echo hello"），务必用单引号或转义，否则 shell 解析失败
为什么 go:generate 命令里不能用相对路径引用本包代码
go:generate 启动的进程默认工作目录是「包含该注释的 .go 文件所在目录」，但 go run / go build 在解析 import 路径时，仍按 GOPATH 或 module root 查找包。如果你写 //go:generate go run ./gen/main.go，而 main.go 里 import 了 "myproject/internal/xxx"，那它能跑通的前提是：当前目录是 module root（即有 go.mod），且 ./gen/main.go 是合法的可执行入口。
- 错误示范：
//go:generate go run gen.go，但gen.go没加package main或缺少func main()→ 报错cannot run non-main package - 更隐蔽的问题：生成脚本依赖
go:embed或//go:build约束，而go generate不加载这些元信息，导致运行时报错或行为不一致 - 推荐做法：把生成逻辑封装成独立
main包，用go install安装为二进制，再在go:generate中调用，避免路径和模块上下文干扰
多个 go:generate 指令的执行顺序和失败处理
同一文件中多个 go:generate 注释，按源码出现顺序从上到下执行。但关键点在于：**任意一条失败，后续全部跳过**，且 go generate 默认返回非零退出码（即 shell 中 && 链会中断）。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
立即学习“go语言免费学习笔记（深入）”；
- 没有内置重试、超时或条件跳过机制；想跳过某条，得靠命令自身逻辑（比如加
-skip-if-exists参数） - 不要写
//go:generate go run gen1.go && go run gen2.go——&&是 shell 特性，go:generate只认第一个命令，后面部分会被当参数传给go run，大概率报错 - 若需强依赖顺序（如先生成 types，再基于 types 生成 mock），建议合并到一个生成器里统一控制，而不是拆成多行
go:generate
go:generate 和 //go:embed / //go:build 的兼容性问题
go:generate 运行时完全不感知 //go:embed 或 //go:build，这意味着：如果你的生成器代码里用了 embed.FS 加载模板文件，或依赖 //go:build ignore 跳过某些平台逻辑，它很可能在 go generate 阶段就 panic 或静默失败。
-
//go:embed只在go build时由编译器处理，go run执行生成脚本时不会注入嵌入文件系统 -
//go:build约束对go:generate无效；即使你写了//go:build !windows，该行仍会被go generate扫描并尝试执行 - 安全做法：生成器自身用
runtime.GOOS判断平台，用os.ReadFile读模板，而非依赖embed；构建约束逻辑移到生成后的代码里，而非生成器内部
真正麻烦的不是语法怎么写，而是生成器一旦混入业务逻辑、环境假设或隐式依赖，就会在 CI、新同事本地、甚至换 GOPATH 后突然失效。最稳的方式是：生成器只做纯文本转换，输入输出全走 stdin/stdout 或明确路径参数，不碰 go list、不查 GOENV、不读 go.mod 外的配置。
