必须完成Go环境配置、goctl安装、API骨架生成、代码生成与编译、服务启动五步，才能curl通返回JSON；任一环节缺失都会导致404或connection refused。
要让 Go-Zero 第一个服务真正跑起来、能 curl 通、返回 JSON，必须走完从环境准备到 HTTP 接口可访问的完整链路——跳过任意一环，比如没配 GOPATH/bin 到 PATH、没生成 handler 代码、没启动服务却去 curl，都会卡在“404”或“connection refused”上。
检查并配置 Go 环境
运行 go version 确认已安装 Go 1.20 及以上版本；若提示 command not found，需先安装 Go 并配置环境变量。
执行 go env GOPATH 查看 GOPATH 路径，记下输出结果（如 /Users/xxx/go 或 C:\Users\xxx\go）；【这一步漏掉会导致后续 goctl 命令找不到】
将 $GOPATH/bin（macOS/Linux）或 %GOPATH%\bin（Windows）添加到系统 PATH 环境变量中，然后新开终端验证：echo $PATH 或 path 中应包含该路径。
安装 goctl 工具
运行安装命令：go install github.com/zeromicro/go-zero/tools/goctl@latest。
安装完成后立即执行 goctl --version；如果报 command not found，说明上一步 PATH 没生效，不要继续往下走。
这一步操作起来很简单，直接把命令复制粘贴执行就行，无需手动下载二进制或解压。
创建项目并生成 API 骨架
新建空目录，例如 mkdir ~/myapi && cd ~/myapi。
初始化模块：go mod init myapi。
用 goctl 创建最简 API 服务：goctl api new greet；该命令会生成 greet/ 目录，含 greet.api、etc/、internal/ 等标准结构。
进入生成的目录：cd greet；此时不要改任何文件，先确保骨架能跑通。
生成并编译服务代码
第一步：生成 Go 代码：goctl api go -api greet.api -dir .；这会把 .api 文件翻译成 handler、logic、types、routes 等全套文件。
第二步：下载依赖：go mod tidy；go-zero 依赖项较多，这步耗时可能达 30 秒以上，耐心等待，别 Ctrl+C 中断。
第三步：编译可执行文件：go build -o greet；成功后当前目录会出现 greet（macOS/Linux）或 greet.exe（Windows）二进制文件。
启动服务并验证接口
方法一：直接运行二进制：./greet -f etc/greet.yaml；服务默认监听 0.0.0.0:8080。
方法二：用 go run 启动（适合调试）：go run greet.go -f etc/greet.yaml；注意不是 run main.go，而是 go-zero 自动生成的入口文件名就是 greet.go。
新开终端，执行：curl "http://localhost:8080/hello/World"；预期返回 {"message":"Hello World"}。
如果返回 curl: (7) Failed to connect to localhost port 8080: Connection refused，说明服务根本没起来——回去检查 greet.go 是否存在、etc/greet.yaml 路径是否正确、端口是否被占用。
