go-zero强制按微服务最佳实践组织代码，需用goctl依.api文件生成骨架；配置须显式加载且大小写敏感；RPC注册需确保etcd地址、服务名一致；API调用RPC须预热、复用client并设超时。
go-zero 本身不是“教程型框架”，它默认就强制你按微服务最佳实践组织代码——不照做，项目跑不起来。
怎么初始化一个能跑的 go-zero 微服务
别从零手写 api 或 rpc 目录结构，go-zero 提供了 goctl 工具生成骨架。没装？先执行：GO111MODULE=on GOPROXY=https://goproxy.cn go install github.com/zeromicro/go-zero/tools/goctl@latest。生成前必须有明确的 API 定义（.api 文件），比如 user.api 里写清楚路由、请求参数和响应字段。运行 goctl api go -api user.api -dir . 才会产出可编译的 handler、logic、types 等目录。漏掉 .api 或路径写错，goctl 会静默失败或生成空文件。
为什么 service.conf 配置改了却没生效
go-zero 的配置加载是“严格分层+显式传参”的：每个服务（api 或 rpc）必须在启动时用 conf.Load 显式加载自己的 service.conf，再把解析后的结构体传给 server.NewServer。常见错误包括：
- 忘记调用
conf.Load，导致所有配置都是零值 - 把
rpc的配置误传给api.Server（类型不匹配，编译报错） - 配置项名大小写写错，比如写成
Etcd而非etcd（struct tag 是json:"etcd"） - 环境变量覆盖时用了
GOZERO_ENV但没在 conf 结构体里加envtag
RPC 服务注册失败，etcd 日志显示 “key not found”
这不是连接问题，而是服务端没正确注册到 etcd。关键检查点：
-
rpc服务启动时，是否调用了registry.MustNewRegistry并传给了server.NewServer -
registry初始化时的etcd地址必须和api服务里rpc客户端配置的地址完全一致（含端口） - 服务名（
service.Name）在rpc的service.conf和api的rpc配置段中必须拼写一致，区分大小写 - etcd 集群本身健康（
etcdctl endpoint health可验证）
api 就查不到服务节点，报 rpc error: code = Unavailable desc = service xxx is not available。立即学习“go语言免费学习笔记（深入）”；
API 层怎么调用 RPC 接口才不卡死
go-zero 的 rpc client 默认使用短连接 + 懒加载，首次调用会阻塞建立连接。生产环境必须：
- 在
api服务启动后、接收请求前，预热 client：调用一次client.Ping或任意轻量方法 - client 实例全局复用，不要每次 handler 都 new 一个（否则连接池失效）
- 如果 RPC 接口耗时长，必须在
logic层显式设置超时：ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)，再传给 client 方法 - 避免在
handler层直接写业务逻辑——所有 RPC 调用必须收口到logic，否则无法统一熔断和限流
最常被跳过的其实是 goctl 生成后的手动补全：比如 logic 里数据库操作要自己加 sqlx 或 gorm，而 goctl 不会帮你 import 这些包；还有 service.conf 里的 redis、mysql 配置，必须手写且确保 struct field tag 和配置键完全对应。这些地方不填平，服务启动就 panic。
