go-zero 常用命令速查

准备

先装上 goctl

所有命令都来自 goctl，先确保它在 PATH 里。

安装

go install github.com/zeromicro/go-zero/tools/goctl@latest

装完验证：

goctl --version # 输出版本号即成功

macOS/Linux 记得把 $GOPATH/bin 加进 PATH：export PATH=$PATH:$(go env GOPATH)/bin

最常用 ①

goctl api —— 生成 HTTP 服务

写完 .api 文件，一键产出完整 rest 服务骨架。

生成 Go 服务

goctl api go -api user.api -dir .

-api 指定描述文件，-dir 指定输出目录。会生成 handler/logic/svc/types + main + yaml。

顺手生成 Dockerfile

goctl api docker -o user-api/Dockerfile

从文档反向生成 api 文件（可选）

goctl api format -w user.api # 格式化

最常用 ②

goctl rpc —— 生成 RPC 服务

写完 .proto，生成 gRPC 桩 + zrpc 封装 + 配置 + main。

核心命令

goctl rpc protoc user.proto \ --go_out=. \ --go-grpc_out=. \ --zrpc_out=. \ -m # -m 生成 main.go 和 etc 配置

三个 out 分别产出消息、gRPC 接口、zrpc 服务端/客户端封装。-m 让 goctl 顺便把 main 和 yaml 也生成好。

从已有 .proto 只更新代码

goctl rpc protoc user.proto --zrpc_out=. # 重跑即可覆盖生成

手动改过的 logic 不会被覆盖（logic 是手写的），但 pb.go、grpc.pb.go 会被重新生成，不要在生成物里手写代码。

最常用 ③

goctl model —— 生成数据访问层

把 SQL 表结构变成带缓存的 CRUD 代码，再也不手写 SQL 拼装。

从 SQL 文件生成

goctl model mysql ddl \ -src user.sql \ -dir ./internal/model \ -c # -c 开启缓存

从数据库直连生成

goctl model mysql datasource \ -url "user:pass@tcp(127.0.0.1:3306)/db" \ -table user,order \ -dir ./internal/model \ -c

生成的方法形如 Insert / FindOne / FindOneByXxx / Update / Delete。带 -c 时 FindOne 自动走缓存 + singleflight 防击穿。

最常用 ④

goctl docker / kube —— 上容器

生成多阶段 Dockerfile 与 K8s 部署清单，省去手搓 yaml。

Dockerfile

goctl docker -go user-api.go \ -o Dockerfile

多阶段构建，最终镜像只有二进制 + 极简基础镜像。

K8s 部署

goctl kube deploy \ -name user-api \ -namespace default \ -image user-api:v1 \ -port 8888 \ -o user-api.yaml

产出 Deployment + Service，改镜像即可上集群。

一页背下来

命令速查表

日常 90% 用到的就这 8 条。

用途	命令	说明
安装	go install .../goctl@latest	装 CLI
HTTP 服务	goctl api go -api x.api -dir .	从 .api 生成 rest 骨架
RPC 服务	goctl rpc protoc x.proto --go_out=. --go-grpc_out=. --zrpc_out=. -m	从 proto 生成 RPC
数据模型	goctl model mysql ddl -src x.sql -dir . -c	从 SQL 生成带缓存 model
连库生成	goctl model mysql datasource -url=... -table=... -dir . -c	从数据库反向生成
Dockerfile	goctl docker -go main.go	多阶段构建镜像
K8s	goctl kube deploy -name x -image x:v1 -port 8888	产出 Deployment/Service
格式化	goctl api format -w x.api	格式化 api 文件

记忆口诀：写接口用 api，写内部调用用 rpc，写数据库用 model，要上线用 docker / kube。四个动词覆盖了 go-zero 开发的全生命周期。