go-zero rpc客户端调不通的主因是etcd配置缺失或错误导致服务未注册；需检查etcd.hosts、etcd进程状态及注册路径，多环境通过-f指定配置文件，proto字段需加jsontag确保序列化一致。
go-zero 里不用自己写 RPC 服务注册和发现逻辑，框架已经封装好了，但必须按约定组织代码结构，否则 goctl 生成的代码会连不上服务。
goctl 生成 RPC 代码后为什么客户端调不通？
常见错误现象：rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing dial tcp :0: connect: connection refused" —— 不是端口没开，而是服务根本没启动成功。
原因在于 go-zero 的 RPC 服务依赖 etcd 做服务注册，而 goctl rpc proto 生成的代码默认读取 etc/<service>.yaml</service> 配置，其中 Etcd 配置项如果缺失或地址写错，服务启动时不会报错，但也不会注册，客户端查不到实例。
- 检查生成的
svc.NewService调用是否传入了正确的config（尤其是Etcd.Hosts） - 确认本地
etcd进程在运行，且Hosts地址能 ping 通、端口可连（默认2379） - 服务启动后，手动执行
etcdctl get --prefix /go-zero/看是否有注册路径（如/go-zero/user.rpc/127.0.0.1:8080）
如何让 go-zero RPC 服务支持多环境配置？
go-zero 默认只加载 etc/<service>.yaml</service>，不自动识别 dev/prod 后缀。硬编码环境判断会破坏配置热加载能力。
正确做法是用 -f 参数指定配置文件路径，配合构建脚本或部署工具切换：
- 启动命令写成
./user-rpc -f etc/user-dev.yaml或./user-rpc -f etc/user-prod.yaml - 所有环境配置文件必须包含完整结构，尤其不能漏掉
Etcd、Service和Redis（如果用了）等顶层字段 - 避免在代码里用
os.Getenv拼接配置路径 —— 这会导致conf.Load无法监听文件变更
RPC 接口返回 struct 时，proto 文件里字段命名要注意什么？
go-zero 用 goctl 把 .proto 编译成 Go 代码时，会把 snake_case 字段转成 CamelCase，但 JSON 序列化默认仍用原始 proto 名（小写下划线），导致 API 层返回字段名跟 RPC 层不一致。
比如 proto 定义 user_name，生成的 Go struct 是 UserName，但 HTTP 网关转发时若没配 json tag，前端收到的是 user_name，不是 userName。
- 在
.proto中为每个字段加(gogoproto.jsontag) = "userName"注解（需启用gogoproto插件） - 或者统一在
goctl api proto生成的.api文件里，用@handler+@response显式映射字段 - 更稳妥的方式：RPC 层只传基础类型或 flat struct，复杂嵌套由 HTTP 层组装，避开序列化歧义
最常被忽略的是 etcd 的健康检查机制 —— go-zero 的服务注册带 TTL，默认 30 秒，如果服务卡在初始化（比如 DB 连接超时），它可能先注册再崩溃，etcd 里残留脏数据，新实例起不来。上线前务必跑通 etcdctl del --prefix 清理再试。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
