goctl生成API服务前必须确认三件事：一是api文件须以.api为后缀且首行符合语法结构；二是配置文件路径需显式指定--home指向模板目录；三是go.mod中go-zero版本必须与goctl匹配。
goctl 生成 API 服务前必须确认的三件事
不配好就跑 goctl api go，90% 的人会卡在启动失败或路由 404。不是框架问题，是生成链路上缺了关键锚点。
-
api文件必须以.api为后缀（如user.api），且首行必须是type Request struct { ... }或service user-api {，否则goctl无法识别语法结构 - 配置文件路径必须显式指定：
goctl api go -api user.api -dir ./api --home $HOME/.goctl，--home指向模板目录，缺了它会 fallback 到内置模板，但自定义字段或中间件可能丢失 -
go.mod里必须已引入github.com/zeromicro/go-zero，且版本与本地goctl匹配（比如goctl@v1.6.1对应go-zero@v1.6.1），版本错位会导致生成的handler中svcCtx类型不兼容
proto 定义 RPC 接口时容易忽略的命名约束
goctl rpc proto 看似只转语法，但命名不合规会导致生成的 Go 代码编译报错或运行时 panic。
- service 名必须大驼峰，且不能和 message 名重复：例如
service UserCenter { ... }合法，service usercenter { ... }会生成空包名，service User { ... }与message User { ... }冲突，导致go build报ambiguous selector - message 字段必须用小驼峰（
userId），不能用下划线（user_id），否则生成的 struct 字段名带下划线，JSON tag 会失效，HTTP 请求参数绑定失败 - proto 文件
option go_package必须写全路径，比如option go_package = "./user";，不能写"user"或留空，否则生成的clientimport 路径错误，调用方找不到UserClient
API 层调用 RPC 服务的实际写法
官方文档常写 svcCtx.UserRpc，但真实项目里这行代码往往直接 panic：nil pointer dereference。
- 确保
etc/user-api.yaml中ServiceConf下正确配置了 RPC 地址：rpc: 127.0.0.1:9000，且该地址对应的是已启动的 RPC server（不是端口监听着但没注册服务） -
svcCtx是从NewServiceContext构造而来，必须在handler初始化时传入，不能在 handler 方法内临时 new —— 否则UserRpc字段未初始化 - 调用前加空指针判断更稳妥：
if svcCtx.UserRpc == nil { return nil, status.Error(codes.Internal, "user rpc not available") }，比让服务崩在第一跳更利于定位 - 超时控制别只靠
context.WithTimeout：RPC client 本身有连接级超时，需在etc/user-api.yaml中设timeout: 3s，否则网络抖动时请求卡住数秒才返回
模型层（model）生成后必须手动改的两处
goctl model mysql 生成的代码开箱即用，但有两处不改必出生产事故。
立即学习“go语言免费学习笔记（深入）”；
- 生成的
FindOne方法默认用QueryRow，查不到数据时返回sql.ErrNoRows；但业务逻辑中常需要区分“不存在”和“查询异常”，必须把err != nil && err != sql.ErrNoRows的分支补全，不能直接return nil, err -
Insert方法默认不返回主键 ID，而多数场景需要插入后立刻拿到id做后续操作（如发消息、写日志），得手动改result, err := m.conn.Insert(ctx, query, vars...)为id, err := result.LastInsertId()并返回
真正卡住开发进度的，从来不是框架能力边界，而是生成代码和实际运行环境之间那几行被忽略的胶水逻辑——尤其是 svcCtx 初始化时机、go_package 路径、以及 sql.ErrNoRows 的处理姿势。
