前言

有位同学在群里说：“Go-Zero 官方文档太简洁了，对小白有点不友好。好奇你们是怎么学习的？项目是怎么封装的？有什么提高开发效率的技巧吗？”。

来来来，这期内容给你安排上，先教你 goctl 的妙用！

前两篇文章分享了 Go-Zero微服务快速入门和最佳实践（一） 和 Go-Zero从0到1实现微服务项目开发（二）。

本文将继续深入探讨 Go-Zero 的强大，并带你从 0 到 1 学会使用 goctl。

通过本文的教程，你将能够亲自实践并完成 goctl 生成模板代码，进一步提升你的开发效率。

概述

goctl 是 go-zero 的内置脚手架，是提升开发效率的一大利器，可以一键生成代码、文档、部署 k8s yaml、dockerfile 等。

官方文档：goctl 安装 | go-zero Documentation

goctl 安装

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

验证

goctl --version

goctl 使用实战

接下来和我使用 goctl 实现快速搭建 api 服务、rpc 服务脚手架以及 model 代码的生成：

goctl api

goctl api 是 goctl 中的核心模块之一，通过该命令可以快速生成一个 api 演示项目。

我们可以通过 goctl api --help 查看 goctl api 的所有指令。

goctl api --help

goctl api new

用于快速生成 Go HTTP 服务，需要指定服务名称，输出目录为当前工作目录。

• 创建 demo 服务

goctl api new demo

这样在当前目录下就能够生成 demo 的 api 服务了。

下图为生成的项目目录结构:

• 在 logic 下面的 demologic.go 编写逻辑

func (l *DemoLogic) Demo(req *types.Request) (resp *types.Response, err error) {        // todo: add your logic here and delete this line        return &types.Response{                Message: "hello world",        }, nil}

• 启动服务

# 跳到demo服务根目录cd demo# 启动服务（默认8888端口，可在etc/demo-api.yaml配置）go run demo.go -f etc/demo-api.yaml

• 访问服务

http://localhost:8888/from/you

至此一个 Go-Zero 的单体服务就完成啦。

goctl api doc

• 根据 api 文件生成 markdown 文档。

• -dir 表示文档输出目录

goctl api doc -dir ./

goctl api go

根据 api 文件生成 Go HTTP 代码。-api 表示 api 文件路径，-dir 表示代码输出目录，--style 表示输出文件和目录的命名风格格式化符号。

详情见 文件风格

--home 表示自定义模板文件目录（自定义模板我们会在后续进行讲解，别忘了关注我）

• 修改 demo.api 文件内容，增加一个 post 接口

type PostDemoReq {        Message string `json:"message"`}
type PostDemoResp {        Message string `json:"message"`}
service demo-api {        @handler PostDemoHandler        post /postDemo(PostDemoReq) returns (PostDemoResp)}

• 重新生成代码

cd demogoctl api go -api demo.api -dir . -style gozero

会生成这两个文件

• 修改 logic 逻辑

func (l *PostDemoLogic) PostDemo(req *types.PostDemoReq) (resp *types.PostDemoResp, err error) {        // todo: add your logic here and delete this line        return &types.PostDemoResp{                Message: req.Message,        }, nil}

• 重新启动服务

go run demo.go -f etc/demo-api.yaml

• 使用 ApiFox 发起请求

至此我们已经学会怎么创建单体服务，并创建 get 和 post 接口啦，已经能应对大多数单体项目的开发需求。

当然我们做接口测试的时候一个个手动输入到 ApiFox 十分麻烦，这时候我们可以借助 goctl api 的插件生成 swagger 导入到 ApiFox 当中。

生成 swagger 文档

goctl-swagger 用于一键生成 api 的 swagger 文档

安装 goctl-swagger

1. 编译 goctl-swagger 插件

GOPROXY=https://goproxy.cn/,direct go install github.com/zeromicro/goctl-swagger@latest

2. 配置环境将 $GOPATH/bin 中的 goctl-swagger 添加到环境变量

使用 goctl-swagger 生成 swagger.json

goctl api plugin -plugin goctl-swagger="swagger -filename demo.json" -api demo.api -dir . 

生成如下文档

3. 导入 ApiFox

4. 导入 demo.json

5. 配置开发环境路由前缀

6.进行接口测试

goctl rpc

goctl rpc 是 goctl 中的核心模块之一，其可以通过 .proto 文件一键快速生成一个 rpc 服务，如果仅仅是启动一个 go-zero 的 rpc 演示项目， 你甚至都不用编码，就可以完成一个 rpc 服务开发及正常运行。

goctl rpc new

• 快速生成一个 rpc 服务，其接收一个终端参数来指定服务名称。

goctl rpc new RPCDemo

• 生成项目目录结构如下图所示

goctl rpc -o

用于快速生成一个 proto 模板文件，其接收一个 proto 文件名称参数。

goctl rpc -o demoProto.proto

• 会在相同目录下生成 proto 模板文件

goctl rpc protoc

• 根据 protobufer 文件生成 rpc 服务。

cd .\RPCDemogoctl rpc protoc RPCDemo.proto --go_out=./ --go-grpc_out=./  --zrpc_out=./ --style=goZero

• 由于没安装 Etcd，因此我们把 etc/rpcdemo.yaml 的 Etcd 相关配置注释掉

• 在 logic/pingLogic.go 修改为如下逻辑

func (l *PingLogic) Ping(in *rPCDemo.Request) (*rPCDemo.Response, error) {        // todo: add your logic here and delete this line
        return &rPCDemo.Response{                Pong: in.Ping,        }, nil}

• 运行服务

cd .\RPCDemogo run .

• 项目默认跑在 8080 端口，可根据需求修改

将 proto 导入 ApiFox 进行测试

• 新建项目

• 新建 gRPC 项目

• 添加项目中的 RPCDemo.proto

• 右上角选择环境

• 测试接口

• 至此，我们已经能够根据 proto 文件生成 gRPC 接口并进行测试啦。

goctl model

goctl model 为 goctl 提供的数据库模型代码生成指令，目前支持 MySQL、PostgreSQL、Mongo 的代码生成，MySQL 支持从 sql 文件和数据库连接两种方式生成，PostgreSQL 仅支持从数据库连接生成。

本文主要以 MySQL 为数据表来源生成代码，其他数据库类似。

• 创建 genModel 文件夹

• 生成代码。对应位置的 MySQL 连接参数改为你的即可。-table 表示你的表名，-dir 表示生成代码的输出目录 -cache 表示是否生成带缓存的代码

goctl model mysql datasource -url="root:PXDN93VRKUm8TeE7@tcp(127.0.0.1:33069)/lottery" -table="lottery" -dir="./genModel" -cache=true --style=goZero

• 显示 Done.说明成功。

至此我们成功使用 goctl model 根据数据库中的数据表生成了 model 代码。

后续通过修改模板代码我们可以实现生成代码的定制化需求，记得关注我！

总结

这篇文章相比官方文档，详细介绍了如何使用 Go-Zero 的 goctl 工具进行 api 服务、rpc 服务和 model 层代码的生成，以及生成 swagger 文件，并提供了 Demo 进行实际操作。

我将继续更新 Go-Zero 系列文章，如果你对 Go 语言或者微服务感兴趣，欢迎关注我，也欢迎直接私信我。

微信：wangzhongyang1993