有效写法必须顶格写//go:generate、放于.go文件package声明前、用./显式指定相对路径（如//go:generate go run ./cmd/gen/main.go -type=User），否则因路径解析错误或命令不可达而失效。
go:generate 指令怎么写才有效
直接写 //go:generate go run gen.go 很容易失效——它不支持相对路径展开、不自动识别工作目录、也不检查命令是否存在。实际执行时经常报错 exec: "go": executable file not found 或静默跳过。
关键点是：指令必须以 //go:generate 开头，顶格写（前面不能有空格或注释），且必须放在 Go 文件顶部的 package 声明之前；命令默认在该 .go 文件所在目录执行，不是 $GOPATH 或模块根目录。
- 推荐写法：
//go:generate go run ./cmd/gen/main.go -type=User（用./显式指明相对路径） - 避免写法：
//go:generate go run cmd/gen/main.go（没./，go tool 会去 $PATH 找，不是当前目录） - 调试技巧：运行
go generate -n ./...查看实际要执行的命令，不真正执行
生成代码前为什么必须先定义好类型和结构体
go:generate 本身不解析语法，只是调起外部命令；而绝大多数生成器（比如 stringer、mockgen、自定义的 gen.go）都依赖 go/types 或 go/parser 加载源码并提取 AST。如果目标 struct 还没定义，或者字段类型引用了未导入的包，生成器会直接 panic 或报 cannot load package。
- 常见错误现象：
can't find type User in package main—— 实际是因为User在另一个文件，且没被go list正确识别（缺少//go:build约束或 build tag 冲突） - 解决办法：确保所有参与生成的类型都在同一包内，或用
-o指定输出路径时，显式传入完整 import path（如-pkg github.com/x/y/z） - 小技巧：在生成器入口加
if len(os.Args) ，避免无参数时误生成空文件
如何让生成的代码不被 git 提交又不被 IDE 报错
生成文件（如 user_string.go）既不能手动编辑，也不能被 IDE 当作“缺失依赖”标红——这需要两层控制：Git 忽略 + Go 工具链识别。
立即学习“go语言免费学习笔记（深入）”；
- Git 层：在
.gitignore加一行**/*_string.go或**/zz_generated*.go（约定俗成用zz_前缀表示生成文件） - Go 层：生成文件顶部必须含合法 package 声明和
// Code generated by ... DO NOT EDIT.注释；否则go list可能跳过它，go build报 duplicate definition - IDE 兼容点：VS Code 的 Go 插件依赖
gopls，而gopls默认读取go:generate并缓存结果；若生成失败，删掉goplscache 目录（~/.cache/gopls）再重启
自定义生成器里为什么建议用 text/template 而不是字符串拼接
硬拼 "func (" + t.Name + ") String() string { return \"" + v + "\" }" 看似快，但一遇到字段名含 Unicode、结构体嵌套、多行注释或导出规则（首字母大小写）就崩——根本没法处理转义、缩进、import 冲突等细节。
- template 更可靠：
{{.TypeName}}String()自动首字母大写；{{printf "%q" .Value}}自动加引号并转义；{{range .Fields}}{{end}}天然支持循环 - 性能差异不大：一次生成几百行，模板编译开销可忽略；反而字符串拼接容易漏空格、多换行，导致生成代码无法编译
- 注意点：template 中
{{.PackageName}}应来自go/types.Package.Name()，别用文件名推断——包名可能和目录名不同（比如package v1 // in dir api/v1）
go/loader 加载类型，用 text/template 渲染），后期维护成本越低；但第一步得先让 go generate 稳定跑起来——路径、包范围、执行时机，这三个地方错一个，整个流程就卡住。 
