go-grpc 代码库及其工具

go-grpc 代码库及其工具

1. 什么是 Protocol Buffer

Protobuf（全称Protocol Buffer）是Google 出品的一种数据描述语言，可类比于json，独立于语言与平台。

Protobuf 提供了多种语言的实现：java、c#、c++、go 和 python，每一种实现都包含了相应语言的编译器以及库文件。由于它是一种二进制的格式，总得来说就是更小、更快、更简单、更灵活，目前分别有v2、v3的版本，我们推荐使用v3。具体查看Protocol Buffers的README介绍。

2. 什么是 protoc

protoc是.proto文件的编译器（参见github），可以借助这个工具把.proto文件转译成各种编程语言对应的源码，包含数据类型定义、调用接口等。

通过查看protoc的源码可以知道，protoc在设计上把Protobuf和不同的语言解耦了，底层用c++来实现Protobuf结构的存储，然后通过插件的形式来生成不同语言的源码。可以把protoc的编译过程分成简单的两个步骤（如上图所示）：

1. 解析.proto文件，转译成protobuf的原生数据结构在内存中保存；
2. 把protobuf相关的数据结构传递给相应语言的编译插件，由插件负责根据接收到的protobuf原生结构渲染输出特定语言的模板。

protoc源码中直接包含的插件有 csharp、java、js、objectivec、php、python、ruby等多种（没有直接提供给go）。

3. 什么是 protoc-gen-go

protoc的go插件版本有两个，第一个主要版本（于2010年公开发布）由github.com/golang/protobuf模块实现;第二个主要版本（于2020年发布）则是由google.golang.org/protobuf模块实现。

protoc-gen-go是protobuf编译插件系列中的Go版本，执行下面的任一命令即可安装到$GOPATH/bin目录下

go get -u github.com/golang/protobuf/protoc-gen-go  # v1
go get -u google.golang.org/protobuf/cmd/protoc-gen-go # v2，建议使用

虽然protoc-gen-go是二进制文件，但不能直接使用，protoc编译时使用-go_out选项，protoc会自动寻找PATH（系统执行路径）中的protoc-gen-go文件，从而生成*.pb.go文件，示例如下：

# 当前目录编译 helloworld.proto 生成 helloworld.pb.go
protoc -I . --go_out . --go_opt paths=source_relative ./helloworld.proto

4. 什么是 protoc-gen-go-grpc

protoc-gen-go-grpc 是go版本的grpc编译插件，用于读取.proto文件中的grpc服务定义生成特定的go代码，具体参见github。同protoc-gen-go一样，protoc-gen-go-grpc也是由protoc驱动使用的，示例如下

# 当前目录编译 helloworld.proto 生成 helloworld.pb.go 和 helloworld_grpc.pb.go
protoc -I . -I $GOPATH/src/github.com/googleapis/googleapis/ \
--go_out . --go_opt paths=source_relative \
--go-grpc_out . --go-grpc_opt paths=source_relative \
./helloworld.proto

5. 什么是 protoc-gen-grpc-gateway

protoc-gen-grpc-gateway也是go版本的grpc编译插件，与protoc-gen-go-grpc不同的是，该插件用于读取gRPC服务定义，生成一个反向代理服务器，将RESTful JSON API转换为gRPC。此服务器是根据gRPC定义中的自定义选项生成的。

使用示例如下:

# 当前目录编译 helloworld.proto 生成 helloworld.pb.go、helloworld_grpc.pb.go 和 helloworld.gw.pb.go
protoc -I . -I $GOPATH/src/github.com/googleapis/googleapis/ \
--go_out . --go_opt paths=source_relative \
--go-grpc_out . --go-grpc_opt paths=source_relative \
--grpc-gateway_out . --grpc-gateway_opt paths=source_relative \
./helloworld.proto

6. protoc-gen-swagger

首先介绍下Swagger，Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发，是目前最受欢迎的RESTful Api文档生成工具之一。

protoc-gen-swagger是grpc-gateway的Swagger工具，可用于生成你的grpc服务的RESTful Api文档。

# 当前目录编译 helloworld.proto 生成 helloworld.pb.go、helloworld_grpc.pb.go、helloworld.gw.pb.go 和 helloworld.swagger.json 
protoc -I . -I $GOPATH/src/github.com/googleapis/googleapis/ \
--go_out . --go_opt paths=source_relative \
--go-grpc_out . --go-grpc_opt paths=source_relative \
--grpc-gateway_out . --grpc-gateway_opt paths=source_relative \
--swagger_out=logtostderr=true:. \
./helloworld.proto

目前，grpc-gateway V2已经发布，同时protoc-gen-swagger改名为protoc-gen-openapiv2

生成 restful api 文档参考 swagger ui

8. grpc 工具总结

插件	描述	功能	源码仓库
protoc	.proto文件编译器	读取.proto文件中的数据结构传递给相应的编译插件	github
protoc-gen-go	go版本的protoc编译插件	读取.proto文件的message数据定义生成*.pb.go文件	github v1版本 github v2版本
protoc-gen-go-grpc	go版本grpc的protoc编译插件	读取.proto文件的grpc服务定义生成*_grpc.pb.go文件	github
protoc-gen-grpc-gateway	go版本grpc反向代理的protoc编译插件	读取.proto文件的grpc服务定义生成*.gw.pb.go文件	github
protoc-gen-swagger	go版本grpc v1的restful api文档生成工具，	用于生成你的grpc服务的RESTful Api文档	github
protoc-gen-openapiv2	go版本grpc v2的restful api文档生成工具	用于生成你的grpc服务的RESTful Api文档	github

grpc 相关代码库

github.com/protocolbuffers/protobuf

该存储库是Google proto buffer的源码库，包含protoc buffer编译器protoc和多种语言的proto buffer编译插件的实现。

github.com/golang/protobuf

该存储库是protoc buffer的go版本实现，protoc-gen-go目录即编译插件protoc-gen-go的实现。

实际上，go实现了两个主版本 (major version) 的protoc buffer，该存储库便是第一版，第二版是google.golang.org/protobuf，该库包含更新的简化的API，支持protobuf反射以及许多其他改进。 建议新代码使用google.golang.org/protouf模块。

另外第一版有一个增强版，参见github.com/gogo/protobuf。

github.com/gogo/protobuf

该存储库是github.com/golang/protobuf 的增强版，生成的编译插件为protoc-gen-gofast，兼容github.com/golang/protobuf，具有更快的序列化与反序列化速度，支持更多的go结构规范。

另外，该存储库还可以生成以下几个更高效的编译插件：

protoc-gen-gogofast (same as gofast, but imports gogoprotobuf)
protoc-gen-gogofaster (same as gogofast, without XXX_unrecognized, less pointer fields)
protoc-gen-gogoslick (same as gogofaster, but with generated string, gostring and equal methods)

Fields without pointers cause less time in the garbage collector. More code generation results in more convenient methods.

github.com/googleapis/googleapis

该存储库包含支持REST和gRPC协议的公共Google API的原始接口定义。即各种googleapi的proto文件，比如目录 google/api下的annotations.proto。

github.com/golang/protobuf的v1.4及更高版本是根据google.golang.org/protobuf实现的。 使用这两个模块的程序必须至少使用该模块的v1.4版本。

github.com/googleapis/go-genproto

该存储库包含常见protocol buffer类型生成的Go代码库，以及与Google gRPC API进行交互所必需的生成的gRPC代码。

其中，googleapis目录是根据github.com/googleapis/googleapis生成的go代码。protobuf目录则 github.com/google/protobuf 下常用类型的生成代码。

google.golang.org/protobuf

该存储库是go实现的第二个主版本的protoc buffer，代码托管在github。主要包含两个部分：

• protoc-gen-go : protoc的go编译插件，用于生成特定的go代码；
• Runtime library： 该模块包含一组Go软件包，这些软件包构成了Go中protobuf的运行时实现，提供了一组消息定义接口，以及序列化各种消息格式 (比如 json、text、wire) 的功能。

github.com/grpc/grpc-go

该存储库是go版本的grpc实现，提供了protoc-gen-go-grpc编译插件。源存储库为google.golang.org/grpc。

github.com/grpc-ecosystem/grpc-gateway

该存储库是go版本的grpc-gateway实现，用于读取gRPC服务定义，生成一个反向代理服务器，将RESTful JSON API转换为gRPC。此服务器是根据gRPC定义中的自定义选项生成的。为此，该存储库提供了protoc-gen-grpc-gateway和protoc-gen-openapiv2两个编译插件。