Go-Zero文档三级定位法：1.从.api文件查接口定义；2.在生成的xxxlogic.go中找业务逻辑；3.通过IDE跳转或GitHub对应tag查框架源码。
想快速查清 Go-Zero 某个功能的文档说明、参数含义或源码实现位置，却在官网、GitHub、中文社区间反复跳转浪费半小时——这不是你效率低，而是没掌握 go-zero 文档的三级定位法：API 定义文件 → 生成代码注释 → 框架源码路径，三步直击源头。
第一步：从 .api 文件定位接口语义与结构
所有 HTTP 接口的行为定义都始于 【.api 文件】，它不是文档附件，而是文档本身。打开项目中任意一个如 user.api 或 order.api 的文件，直接阅读 type 块和 service 块。
例如看到 post /api/user/register (UserReq) returns (UserResp)，就立刻知道这个接口是 POST 请求、路径为 /api/user/register、入参结构体叫 UserReq、返回结构体叫 UserResp。
注意：.api 文件里 @doc(summary: "...") 注释会原样生成到 Swagger 文档标题中，这是唯一需要人工维护的“文档层”，其余全部由工具同步。
第二步：在生成代码里找 handler 和 logic 的真实调用链
运行过 goctl api go -api user.api -dir ./ 后，进入 internal/handler/ 目录，找到对应 handler 文件（如 registerhandler.go）。
打开它，第一眼就看函数签名：func RegisterHandler(svcCtx *svc.ServiceContext) http.HandlerFunc —— 这说明该 handler 接收完整服务上下文，可直接调用 RPC、DB 或缓存。
再往下滑，找到 logic := NewRegisterLogic(r.Context(), svcCtx) 这一行，紧接着就是 resp, err := logic.Register(&req)；此时立刻去 internal/logic/ 下打开 registerlogic.go，业务逻辑真正在这里写，所有数据库查询、RPC 调用、校验逻辑都在这个文件里。
这一步的关键是：不要在 handler 里找业务实现，handler 只负责粘合；真正要查“为什么返回空数据”或“哪里加了限流”，必须跳进对应的 【xxxlogic.go】。
第三步：精准跳转框架源码，查透底层机制
当你遇到诸如 “JWT 鉴权失败但没报错”、“熔断器不触发”、“timeout 不生效” 这类问题，必须查 go-zero 框架自身行为。
方法一：用 IDE 全局搜索关键词 → 在 GoLand 或 VS Code 中按 Ctrl+Click（Windows/Linux）或 Cmd+Click（macOS）点击任意一个框架内建类型，比如 zerobase.RestConf、middleware.Timeout、jwt.Middleware，IDE 会自动跳转到 $GOPATH/pkg/mod/github.com/zeromicro/go-zero@v1.x.x/... 对应源码位置。
方法二：手动定位核心包路径 → 所有中间件实现在 go-zero/core/middleware/，配置解析在 go-zero/core/conf/，HTTP 服务启动逻辑在 go-zero/rest/httpserver.go，RPC 客户端封装在 go-zero/rpc/x/client.go。
特别提醒：【不要 clone 整个 go-zero 仓库来读】，直接通过 go list -m all | grep zero 查出本地实际使用的版本号，然后去 GitHub 上对应 release tag 页面浏览源码，更轻量、更准确。
