go-zero不是“装完就能跑”的框架，必须严格按微服务规范组织代码：需先编写.api文件并正确路径加载配置、预热rpc client、复用实例、显式设超时、用goctl生成model等，缺一不可。

go-zero 不是“装完就能跑”的框架，它强制你按微服务工程规范组织代码——不生成 .api 文件、不显式加载配置、不预热 RPC client，项目大概率启动失败或线上卡死。

goctl 生成项目前必须写好 user.api 文件

很多人执行 goctl api new user 后直接 go run user.go，报错找不到 handler 或 panic nil pointer。根本原因：goctl 不会帮你写接口定义，它只根据 .api 文件生成骨架。

• .api 文件必须放在 api/ 目录下，且文件名要和 goctl api go -api 参数一致（比如 -api api/user.api）
• 最简可用的 user.api 至少包含 service 名、type、路由和类型定义，漏掉 type 声明会导致 types 包为空
• 路径写错（如写成 ../user.api）或文件编码含 BOM，goctl 会静默跳过生成，目录里只剩空文件夹

conf.Load 必须在 main 中显式调用，且结构体 tag 要严格匹配

改了 etc/user.yaml 却没生效？90% 是因为配置没真正加载进服务。go-zero 不自动扫描配置，所有参数都靠 conf.Load 解析后手动传入。

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

• 必须用 conf.Load("etc/user.yaml")，路径错误或文件不存在时不会报错，只会返回零值结构体
• 配置 struct 字段的 json tag 必须小写，比如 Etcd string `json:"etcd"` 写成 `json:"Etcd"` 就无法绑定
• RPC 和 API 服务不能共用一个配置结构体：RPC 需要 registry 字段，API 需要 port 字段，混用会编译失败

调用 RPC 之前必须预热 client 并复用实例

第一次请求 API 接口时卡住 2–3 秒，之后又正常？这是 RPC client 懒加载导致的阻塞。go-zero 的 rpcx client 默认首次调用才建连，且不复用就会反复创建连接池。

• 在 main 函数启动 server 前，加一行 client.Ping(context.Background()) 预热
• client 实例必须作为全局变量或注入到 svc.ServiceContext 中，绝不能在每个 logic 里 new 一个
• 超时必须显式设置：ctx, cancel := context.WithTimeout(r.Context(), time.Second*2)，否则默认是无限等待

数据库模型生成依赖 goctl model mysql，不是手写 model

手写 model/user.go 看似省事，但很快会和表结构脱节。go-zero 推荐用 goctl model mysql 从 DDL 或 DSN 自动生成，保证字段、类型、tag 与 DB 严格一致。

• 执行前确保 MySQL 连通，且用户有 SHOW CREATE TABLE 权限，否则报 invalid connection 却不提示具体哪张表失败
• 生成命令中的 -table 参数区分大小写，MySQL 表名是小写，但写成 -table User 会找不到
• 生成后记得手动补上 CreatedAt 等软删除/时间戳字段的 gorm tag，否则 ORM 不识别

最容易被忽略的是：go-zero 的每个环节都假设你已理解微服务的基本契约——服务注册发现靠 etcd、配置靠 YAML+struct 绑定、RPC 调用靠预热与超时控制。它不隐藏复杂性，只是把重复劳动自动化；你跳过其中一环，框架不会替你兜底。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！