goctl 命令需在 goland 终端中确保全局路径、go module 环境及 gopath/goroot 一致；live template 要绑定 classname()；自定义模板须通过 --home 指定并修改 handler.tpl；rpc 调试需显式配置 etcd_endpoints 并验证 etcd 连通性。
goctl 命令必须在 GoLand 终端里正确初始化
goctl 不是 IDE 插件，它依赖全局可执行路径和当前工作区的 Go module 环境。如果在 GoLand Terminal 里执行 goctl api new demo 报错 “command not found” 或 “no Go module found”，说明环境没对齐。
常见错误现象：终端能跑 goctl --version，但生成失败；或生成后 go run demo.go 提示找不到包。
- 确保 GOPATH 和 GOROOT 已设为系统环境变量（不是仅 GoLand 的 Shell path）
- 在 GoLand Terminal 中执行
cd到空目录后，先运行go mod init demo，再跑goctl api new demo - 不要用 Windows PowerShell 或 CMD 单独开窗口执行后再切回 GoLand —— GoLand Terminal 的 shell 环境可能未加载 GOPATH
- 检查
go env GOPATH输出是否与 GoLand Settings → Go → GOPATH 一致
Live Template 必须绑定 className() + groovyScript 才能适配生成代码结构
Go-Zero 生成的 handler、logic、svc 层都带固定命名模式（如 UserHandler、UserLogic），手写模板若只用静态占位符，Tab 后还得手动改类型名，失去意义。
例如你想在 internal/logic/userlogic.go 里快速补一个数据库调用桩，光标停在 User struct 上时按 dbcall 应自动展开为 svcCtx.UserModel.FindOne(ctx, id)，而不是硬编码 UserModel。
- 新建 Live Template 缩写填
dbcall，模板内容：svcCtx.$className$Model.FindOne(ctx, $id$) - 点击 “Edit variables”，给
className绑定表达式className()，给id设默认值id - “Applicable in” 必须选中 “Go: declaration” 和 “Go: statement”，否则 struct 定义里不触发
- 别用
variableName()替代className()—— 光标在字段上时它返回字段名，不是结构体名
自定义 handler 模板需显式 import response 包并替换 OkJson
Go-Zero 默认生成的 handler 直接用 httpx.OkJson(w, resp)，但实际项目往往要求统一响应格式（如 {"code":0,"msg":"OK","data":{}}）。硬改每个生成文件不可持续，必须改模板。
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
错误做法：在生成后手动改 handler/userhandler.go 里的 OkJson 调用 —— 下次 goctl api proto 或升级模板就覆盖了。
- 先执行
goctl template init --home $HOME/gozero-tpl落盘模板 - 编辑
$HOME/gozero-tpl/1.6.4/api/handler.tpl，找到httpx.OkJson(w, resp)行，替换成response.Response(w, resp, nil) - 在 import 块里加一行
"your-project/response"（注意路径要和你真实包路径一致） - 后续所有
goctl api -o都要带上--home $HOME/gozero-tpl，否则仍用内存默认模板
RPC 服务注册失败时，GoLand Debug 配置要绕过 etcd 连通性校验
本地开发时，user-rpc 启动报 service not found，90% 是因为 etcd 未就绪或 Registry 地址写错。但你在 GoLand 里直接 Run/Debug user-rpc.go，它不会等 etcd ready 就 panic。
这不是代码 bug，而是启动时序问题。强行加 time.Sleep 不解决根本，还污染生产代码。
- GoLand Run Configuration → Environment variables 添加
ETCD_ENDPOINTS=http://127.0.0.1:2379 - 勾选 “Include system environment variables”，避免被 .env 文件覆盖
- 在
etc/user-rpc.yaml里把Etcd.Hosts改成["127.0.0.1:2379"]，别用localhost（Docker for Desktop 下解析异常） - 启动前先在终端跑
etcdctl --endpoints=http://127.0.0.1:2379 endpoint health确认连通，再点 GoLand 的 ▶️
真正容易被忽略的是：GoLand 的 Run Configuration 默认不加载项目根目录下的 .env，而 go-zero 的 config 加载逻辑又依赖环境变量注入。没显式配置，本地调试永远卡在注册阶段。
