go-zero 是服务生命周期的起点，需用 goctl 生成代码；安装失败应清理旧版并用 go install 安装；.api 文件错误导致 panic；RPC 注册需注意地址、鉴权与服务名格式；gRPC 调试必关 TLS；依赖版本须严格匹配 goctl 推荐版本。
直接用 goctl 搭，别自己手写骨架；go-zero 不是“可选组件”，它是整个服务生命周期的起点——从 .api 文件生成代码、启动、配置加载、限流熔断，全链路由它驱动。
goctl 安装失败或版本不对？先清干净再重装
常见错误现象：goctl: command not found 或 goctl --version 报错找不到符号，多因旧版残留或 GOPATH/bin 未生效。
- 删掉所有旧安装：
rm -rf $GOPATH/bin/goctl（Linux/macOS）或手动删 Windows 下%GOPATH%\bin\goctl.exe - 强制指定模块代理安装：
GO111MODULE=on GOPROXY=https://goproxy.cn,direct go install github.com/zeromicro/go-zero/tools/goctl@latest - 验证路径是否在
$PATH里：echo $PATH | grep -q "$GOPATH/bin"，没命中就补上 - 别用
go get——它已废弃，go install才是 Go 1.16+ 的标准方式
生成 API 服务时，.api 文件写错会导致整个结构崩掉
真实场景里，80% 的启动 panic 来自 service.api 里路径、类型或 tag 写错，比如 POST /user/:id 漏了冒号，或 req *UserReq 里字段没加 json:"id"。
- 路径必须以
/开头，且不能含空格或中文：POST /v1/user/create✅，POST user/create❌ - 请求体结构体字段首字母必须大写，且显式声明
jsontag：Id string `json:"id"`，小写id string会被忽略 -
goctl api go -api service.api -dir .会覆盖当前目录下所有生成文件，别在已有业务逻辑的目录里直接跑 - 生成后立刻检查
handler目录下是否生成了对应路由注册，以及types是否有正确结构体定义
RPC 服务注册不进 etcd/Nacos？不是网络问题，是配置漏项
register to etcd failed 或 Nacos 返回 403 Forbidden，基本不是连不上，而是地址格式、鉴权、服务名三处之一错了。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- Nacos 地址必须带
/nacos后缀：http://127.0.0.1:8848/nacos，写成http://127.0.0.1:8848就静默失败 - Nacos 2.x 默认开启鉴权，需在
etc/user.yaml中显式配账号：username: "nacos"+password: "nacos" - etcd 地址别写
localhost：Docker 容器内解析失败，换成宿主机 IP 或host.docker.internal - 服务名只允许小写字母、数字、短横线：
user-rpc✅，user_rpc或UserRpc❌，注册直接被拒绝
本地调试时 gRPC 调不通？99% 是 TLS 没关
context deadline exceeded 看似超时，实则是客户端根本没连上服务端——因为两端默认启用 TLS，但你没配证书。
- 客户端初始化时必须加
client.WithInsecure()：NewUserClient("user-rpc", conf, client.WithInsecure()) - 服务端启动也要关：
server.NewServer(server.WithInsecure()) - 别信文档里“开发环境可省略”的说法——
go-zero0.5.0+ 版本起，WithInsecure()是硬性要求，不加就握手卡死 - 调用前用
etcdctl get --prefix "/go-zero/"确认服务节点已注册，路径前缀是/go-zero/，不是/kitex/或/micro/
最易被忽略的点：所有生成代码都依赖 go.mod 里 github.com/zeromicro/go-zero 的精确版本，一旦你手动 upgrade 到非 patch 版本（比如从 v1.5.2 升到 v1.6.0），goctl 生成的代码可能因接口变更而编译失败——别贪新，用 goctl version 显示的推荐版本最稳。
