掘金 后端 ( ) • 2024-03-31 22:05
（三）Go-Zero和goctl：解锁微服务开发的神器，快速上手指南
goctl 手指 神器

highlight: a11y-dark theme: Chinese-red

本文为稀土掘金技术社区首发签约文章，30天内禁止转载，30天后未获授权禁止转载，侵权必究！

前言

有不少同学和我说：“Go-Zero官网太惜字如金了，好奇我们是怎么学习的？项目是怎么封装的？有什么提高开发效率的技巧吗？”。来来来，这期内容给你安排上，先教你goctl的妙用！

上一篇文章带你实现了Go-Zero从0到1实现微服务项目开发，本文将继续深入探讨Go-Zero的强大，并带你从0到1学会使用goctl。

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

概述

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

官方文档：goctl 安装 | go-zero Documentation，有同学反馈说Go-Zero的文档“惜字如金”，想让我写详细教程，安排！

goctl安装

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

验证

goctl --version

image-20240324183102287

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

image-20240324184942435

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

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

image-20240324185033989

  • 在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

image-20240324190756997

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

goctl api doc

  • 根据 api 文件生成 markdown 文档。
  • -dir表示文档输出目录
goctl api doc -dir ./

image-20240324191938334

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 demo
goctl api go -api demo.api -dir . -style gozero

会生成这两个文件

image-20240324192948952

  • 修改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发起请求

image-20240324193701720

至此我们已经学会怎么创建单体服务，并创建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 .

生成如下文档

image-20240324194904920

3.导入ApiFox

image-20240324195049182

4.导入demo.json

image-20240324195209728

image-20240324195245159

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

image-20240324195511502

image-20240324195600505

6.进行接口测试

image-20240324195701608

goctl rpc

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

goctl rpc new

  • 快速生成一个 rpc 服务，其接收一个终端参数来指定服务名称。
goctl rpc new RPCDemo
  • 生成项目目录结构如下图所示

image-20240324203006437

goctl rpc -o

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

goctl rpc -o demoProto.proto
  • 会在相同目录下生成proto模板文件

image-20240324210023407

goctl rpc protoc

  • 根据 protobufer 文件生成 rpc 服务。
cd .\RPCDemo
goctl rpc protoc RPCDemo.proto --go_out=./ --go-grpc_out=./  --zrpc_out=./ --style=goZero

image-20240324203249132

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

image-20240324204417311

  • 在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 .\RPCDemo
go run .
  • 项目默认跑在8080端口，可根据需求修改

image-20240324204543886

将proto导入ApiFox进行测试

  • 新建项目

    image-20240324204644891

    • 新建gRPC项目

    image-20240324204726142

  • 添加项目中的RPCDemo.proto

    image-20240324204920114

  • 右上角选择环境

    image-20240324205022648

    image-20240324205123891

  • 测试接口

    image-20240324205233980

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

goctl model

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

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

  • 创建genModel文件夹

image-20240324211045538

  • 生成代码。对应位置的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.说明成功。

image-20240324211227428

image-20240324211454772

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

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

总结

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

我将继续更新Go-Zero系列文章，如果你对Go语言或者微服务感兴趣，欢迎关注我的掘金账号，也欢迎在掘金私信我。
相关内容
基于go-zero的goctl二开，gin项目代码生成器