goctl api
详情移步:
go-zero的路由机制解析
基于go-zero的api服务刨析并对比与gin的区别
goctl rpc
goctl支持多种rpc,较为流行的是google开源的grpc,这里主要介绍goctl rpc protoc的代码生成与使用。
protoc是grpc的命令,作用是将proto buffer文件转化为相应语言的代码。这里gocrl集成了proto buffer。
--go_out
和--go-grpc_out
分别是生成的pb文件和_grpc.pb文件的目录。
使用protoc命令的前提条件是要有proto文件,如下:
syntax = "proto3";
package pb;
option go_package = "./pb";
//获取某用户的认证详细信息
message IdentifyDetailReq{
string Id = 1;
}
message Detail{
string Id = 1; //客户id
string Contacts = 2; //企业联系人
string Corporation = 3; //企业联系人身份证号
int64 Status = 4; //认证状态 0-待审核;1-已通过;2-未通过
string CompanyName = 5; //企业名称
string Phone = 6; //企业联系人电话
string Address = 7; //通讯录地址
string Reason = 8; //认证不通过理由
int64 Type = 9; //企业证件类型 0-营业执照三证合一;1-营业执照非三证合一;2-非营业执照
string qualifications = 10;//企业资质信息
}
message IdentifyDetailResp{
Detail IdentifyInfo = 1;
}
service Identify{
rpc IdentifyDetail(IdentifyDetailReq) returns (IdentifyDetailResp);
}
初始项目目录如下:
执行命令:
goctl rpc protoc test.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=.
生成目录文件
grpc最主要的文件是pb文件,rpc远程调用都基于这两个文件。
goctl rpc 生成的go文件和grpc不并不一样,zero对grpc进一步分装,且封装的库放在github.com/zeromicro/go-zero/zrpc
中。
原生grpc
和原生grpc使用不同的是:
-
开发者自定义
UnimplementedXXXServer
的实现类 -
重写指向
UnimplementedXXXServer
实现类的所有方法。 -
编写服务端代码并注册所有实现的方法
-
客户端调用方法。
在proto文件生成的_grpc.pb
文件自定义的接口:
需要新建该类的实现类并重写所有方法,完成特定功能。由于返回值参数都是在pb
文件中,具备任何两个pb文件的够可以构建该同名称函数的rpc远程调用,并返回参数后序列化。
另外还需的注意的是grpc只生成的pb文件客户端与服务端都需要开发者来编写。
zero的grpc
在go-zero对grpc进一步封装,并将封装的,完成pb文件的生成与服务端的代码生成。如下自动生成的目录:
grpc原生命令只生成两个pb文件。
goctl rpc proto生成4个目录和一个rpc服务端启动程序。其中第二个目录是对grpc客户端代码的进一步封装,自定义的客户端。
在使用goctl rpc proto生成的代码是可以快速的构建rpc应用,方便的使用rpc客户端,另外zero还对etcd进行了集成,无需开发者操作,任然可以使用goctl一键生成。
pb文件就不再赘述了,这是看grpc使用的第二步,实现接口方法并注册方法,方法的实现zero也是使用服务层与逻辑层的调用方式,如下:
- server目录实现了
_grpc.pb
的所有方法,但是在方法中并没有写具体实现,而是直接调用了logic层。
- logic层具体实现
此次封装只是隐藏了一个入参,当然也可以直接使用logic实现完整的代码,直接在服务点调用,跳过server也是可以的。
唠叨grpc第三步,服务端代码编写与接口注册,这一步也是由goctl生成的。在grpc中一般是调用_grpc.pb
中的RegisterXXXServer
方法参数为一个初始化的grpc服务端,可以接口。
第一个参数来自grpc目录(zero集成了grpc),第二个参数也在_grpc.pb
为包含自定义方法的接口。
在go-zero中也是直接实现了服务端编写,查看源码都可以发现实现服务端构建都是使用了zrpc.MustNewServer
方法,源码如下:
// A RpcServer is a rpc server.
type RpcServer struct {
server internal.Server
register internal.RegisterFn
}
// MustNewServer returns a RpcSever, exits on any error.
func MustNewServer(c RpcServerConf, register internal.RegisterFn) *RpcServer {
server, err := NewServer(c, register)
logx.Must(err)
return server
}
该方法传入了RpcServerConf
服务端配置,肯定是必须的,要设置ip监听端口等;第二个参数呢是一个是一个参数为grpc.Server
的函数,显然安装常规的构建服务端方法,就差一个接口了。
那么主要在这个方法内部调用pb的注册方法就可以了,看到zero的代码
调用了_grpc.pb方法注册,但不同的是第二个参数,并不是_grpc.pb的接口,而是server目录的封装的方法。
注册方法的参数是两个接口,可以是任意类型,但是第一个参数必须是grpc.Server
这里zero有一次并没有传入接口,而是自定义的结构体,结构体的方法被注册到grpc服务端。
pb.UnimplementedIdentifyServer
构建grpc服务端的关键,重写了其方法,将其子类通过注册的方式注册到grpc服务端。
以上就zero对grpc的封装过程,goctl直接实现了构建grpc服务的前三个步骤,开发者只需要编写实现逻辑和少量配置即可。也就是说通过goctl生成的rpc服务只需要两个简单的步骤:
- 在yaml配置文件配置
zrpc.RpcServerConf
所需要的参数
2. logic层编写方法实现的具体逻辑
以上就是go-zero rpc服务端了。
其实客户端goctl也生成了,对于原生的grpc创建实现客户端包含连个步骤:1. 配置客户端连接参数;2. 实例化客户端对象。
源码也在_grpc.pb
文件中:
图片上的转换过程有点复杂,出现了不少接口与接口的变化,不太好懂,当下只知道如何使用即可。
//配置连连接参数(无加密)
dial, err := grpc.Dial("localhost:1099", grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
println("failed grpc connect", err)
}
defer dial.Close()
//创建客户端连接
client := protoInterface.NewInterfaceClient(dial)
//通过客户端调用方法
res, err := client.GetProduct(context.Background(), &protoInterface.Request{
ParamString: "hello",
})
在上述代码中最核心的就是grpc.Dial
这步,创建grpc连接,后续调用pb的NewXXXClient
传入该参数就得到了一个客户端对象就可以调用方法了。
go-zero客户端
zero中进一步封装,看zero源码(一般是生成文件的第二个目录即在etc下面的目录文件是对客户端的封装)。
第一个表示接口方法就是pb客户端的方法,第二个是对客户端的封装,第三个是创建客户端方法,第四个是方法实现,其实这都可上一小结原生pb的grpc客户端一模一样,就是换了个名字。
那么显然不能再用gprc原生的内容了,使用这些包装的rpc客户端也很简单,显然NewIdentify
是构建客户端实例的方法,就差连接对象了。查看zrpc.Client
源码如下:
再查看internal.Client
源码:
巧了吗这不是,到头来还是自己,却有三个名。
到此思路就清晰了。
实例化一个zrpc.Client
或者直接使用grpc.Dial
,需要注意的是zrpc.Client
类型和同款类型是一个接口啊,没法像接口那样直接实例化,需要通过另一个方法实例化。
直接在zrpc库中找即可
conn := zrpc.MustNewClient(zrpc.RpcClientConf{
Target: "dns:///127.0.0.1:8080",
})
zrpc.MustNewClient
方法可以实例化,其参数是一个zrpc.RpcClientConf
结构体。这个参数可以配置在config目录下额文件中,通过配置获取。
到此也可以明白这莫多层的封装的意义了把,就是把下面这些配置集成了grpc中,并能通过yaml文件配置。
客户端对象实例获取后,如何可以直接调用方法获取服务端返回的数据库,保证服务端启动者即可。
etcd的整合
上述过程还未使用etcd的服务注册与发现功能,可以看到上之前的一些配置类中如服务端zrpc.RpcServerConf
与zrpc.RpcClientConf
均出现了Etcd的配置类,在go-zero中使用etcd也是十分方便。一般有如下几个步骤:
- 安装etcd,确保其正常运行
- rpc服务端构建etcd心跳客户端持续发送心跳,并上传数据
- rpc客户端构建etcd普通客户端获取数据。
go-zero中使用etcd和单独使用区别不大,主要是配置文件那块。
详情请移步go-zero微服务实战——etcd服务注册与发现
goctl model
goctl model支持多种数据库,较为常用的是mysql,这里主要介绍goctl mode mysql的代码生成与使用。
goctl model mysql datasource -url="user:password@tcp(127.0.0.1:3306)/database" -table="table1,table2" -dir="./model"
运行命令后会在指定的目录下生成三个文件
其中usermodel.go
是用户自定义的DML,DQL,开发者可在此处定义自己编写的sql查询语句;usermodel_gen.go
是goctl自动生成的DML,DQL实现了数据库的基本操作即CRUD操作;第三个var.go
就是自定义的数据库操作失败的返回值和其他参数。
goclt自动生成数据库引擎,在
goctl model mysql
命令的datasource参数就是配置数据库引擎的参数。接下来会参数如何使用。
可以看到user_mode_gen.go
的userModel接口定义了很多方法:
而这些接口最终都指向了defaultUserModel
转到defaultUserModel的定义
defaultUserModel struct {
sqlc.CachedConn
table string
}
结构体定义了缓存和表名,后者由命令参数传递。
同源文件下也提供了实例化的方法:
func newUserModel(conn sqlx.SqlConn, c cache.CacheConf, opts ...cache.Option) *defaultUserModel {
return &defaultUserModel{
CachedConn: sqlc.NewConn(conn, c, opts...),
table: "`user`",
}
}
通过该方法创建一个defaultUserModel的实例,那么通过该方法创建实例,就可以调用接口的所有方法了。但是可以看到这个方法是私有的。
在xxxmodel.go
文件下也有一个NewUserModel
方法是公开的,如下:
// NewUserModel returns a model for the database table.
func NewUserModel(conn sqlx.SqlConn) UserModel {
return &customUserModel{
defaultUserModel: newUserModel(conn),
}
}
该方法对defaultUserModel进行了多次封装会有返回以newUserModel构建的defaultUserModel。开发者可以使用 NewUserModel来调用model生成的方法。
在对defaultUserModel多次封装的过程中出现了如下的接口和结构体:
UserModel
接口内嵌userModel
显然是其子接口,继承了userModel的方法且是公开的。customeUserModel也是defaultUserModel子类,并只能通过NewUserModel方法调用。显然该层继承是为了方便开发者拓展model层,实现自定义sql操作数据库。
自定义model的一般步骤包括:1. xxxmodel的接口中定义方法;2. 在同包下实现方法,并指向defaultUserModel的实现类。
如下使用NewUserModel就可以直接调用自定义的方法了
自定义方法操作数据库
除了上述使用goctl的model规范操作数据库外,也可以通过自定义的方法操作数据库。会看model的的代码,其中操作数据库的核心就是sqlx.SqlConn
这里的sqlx来源与zero的库
"github.com/zeromicro/go-zero/core/stores/sqlx"
在sqlx中有一个NewMysql
方法返回sqlx.SqlConn实例,就可以直接通过该方法返回的对象直接操作数据库。
var mysql = sqlx.NewMysql(datasource)
func Test2(t *testing.T) {
mysql := sqlx.NewMysql("username:password@tcp(ip:3306)/databasename?charset=utf8mb4&parseTime=True")
sql_ := "select * from user"
user := User{}
mysql.QueryRowCtx(context.Background(), &user, sql_)
fmt.Println(user)
}
直接调用sqlx.SqlConn实例操作数据库的方法即可。
整合第三方框架
也可以整合一些第三方框架如gorm,xorm等,这就比较简单了,go get [address]
安装。1. 封装工具类,暴露数据库引擎实例;2. 通过实例方法操作数据库。
可gin,iris,beego等框架整合xorm一样的方式,就不再过多叙述。