Go protobuf

• 使用protobuf实现节点间通信、编码报文以提高传输效率
• protobuf全程Protocol Buffers，是Google开发的一种数据描述语言。
• protobuf是一种轻便高效的结构化数据存储格式。
• protobuf跟存储格式、语言、平台无关。
• protobuf可扩展可序列化
• protobuf以二进制方式存储，占用内存空间小。

protobuf广泛地应用于远程过程调用（PRC）的二进制传输，使用protobuf的目的是为了获得更高的性能。传输前使用protobuf编码，接收方再进行解码，可显著地降低二进制传输数据的大小。另外，protobuf非常适合传输结构化数据，便于通信字段的扩展。

protobuf

protoc

protoc是protobuf文件（.proto）的编译器，使用protoc工具可以将.proto文件转换为各种编程语言对应的源码，包含数据类型定义和调用接口等。

protoc

从 https://github.com/protocolbuffers/protobuf/releases 中下载最新的protobuf安装包 protoc-3.15.6-win64.zip

解压压缩包后将bin目录下的protoc.exe文件移动到$GOPATH/bin目录下，注意$GOPATH/bin需要提前添加到环境变量Path目录下。

$ protoc -help
$ protoc --version
libprotoc 3.15.6

protobuf

protobuf对于Golang有两个可选用的包分别是官方的goprotobuf和gogoprotobuf，gogoprotobuf是完全兼容Google Protobuf的，只是生成的代码质量要比goprotbuf要高。

安装protobuf库

$ go get github.com/golang/protobuf/proto
go: found github.com/golang/protobuf/proto in github.com/golang/protobuf v1.5.1
go: downloading github.com/golang/protobuf v1.5.0
go: github.com/golang/protobuf upgrade => v1.5.1

安装gogoprotobuf库

$ go get github.com/gogo/protobuf/proto
go: found github.com/gogo/protobuf/proto in github.com/gogo/protobuf v1.3.2

protoc-gen-go

protoc-gen-go 是 protobuf 编译插件系列中的Go版本，protoc-gen-to 使用Golang编写。

在Golang中使用protobuf需提前安装 protoc-gen-to工具，用于将.proto文件转换为Golang代码。

$ go get -u github.com/golang/protobuf/protoc-gen-go

protoc-gen-go将会自动安装到$GOPATH/bin目录下，Windows中会生成 protoc-gen-go.exe 文件。

在当前项目下执行引入protobuf，会在go.mod文件中自动添加对protobuf的require引入。

$ go get github.com/golang/protobuf/proto
go: found github.com/golang/protobuf/proto in github.com/golang/protobuf v1.5.1

protobuf会在.proto文件中定义需要处理的结构化数据，通过protoc工具可将.proto文件转换为C、C++、Golang、Java、Python等多种语言的代码，因此兼容性好且易于使用。

$ protoc --go_out=. *.proto

命令之后理论上会将当前目录下的所有的.proto文件生成.pb.go文件，但实际测试发现报错，不推荐使用。

protoc-gen-go: unable to determine Go import path for "test.proto"

protoc-gen-gogo

gogoprotobuf有两个插件可用分别是protoc-gen-gogo和protoc-gen-gofast，protoc-gen-gogo生成的文件和protoc-gen-go一样性能略快，protoc-gen-gofast生成的Golang文件更为复杂，但性能却高出5~7倍。

安装gogoprotobuf插件

$ go get github.com/gogo/protobuf/protoc-gen-gogo

执行后会在$GOPATH下的bin目录下生成protoc-gen-gogo.exe为文件，同时会在当前项目的go.mod文件内自动引入require github.com/gogo/protobuf v1.3.2。

$ protoc *.proto --gogo_out=.

执行后会将当前目录下的所有.proto文件生成.pb.go文件

protoc-gen-gofast

$ go get github.com/gogo/protobuf/protoc-gen-gofast

执行后会在$GOPATH下的bin目录下生成protoc-gen-gofast.exe为文件

$ protoc *.proto --gofast_out=.

执行后会将当前目录下的所有.proto文件生成.pb.go文件

语法

• Protobuf协议规定：使用Protobuf协议进行数据序列化和反序列化操作时，首先需要定义传输数据的格式，并命名以.proto为扩展名的消息定义文件。
• 使用message定义一个消息
• 指定消息字段类型
• 分配标识符，在消息字段中每个字段都有唯一的一个标识符，最小标识号可以从1开始，最大到536870911。不可以使用[19000 ~ 19999]之间的标号。
• 指定字段规则，字段修饰符包括required、optional、repeated三种类型，注意required弊大于利。

使用

1. 按照protobuf语法，在.proto文件中定义数据结构，同时使用protoc工具生成Golang代码。
2. 在项目代码中引用生成的Golang代码

定义消息类型

$ vim ./proto/test.proto

syntax = "proto3";

package proto;

message User{
    string name = 1;
    bool male = 2;
    repeated int32 balance = 3;
}

运行命令

$ protoc --go_out=output_directory input_directory/file.proto

• --go_out=表示生成Go文件，protoc会自动寻找系统环境变量Path中的protoc-gen-go执行工具。

$ protoc --go_out=. *.proto
protoc-gen-go: unable to determine Go import path for "test.proto"

Please specify either:
        • a "go_package" option in the .proto source file, or
        • a "M" argument on the command line.

See https://developers.google.com/protocol-buffers/docs/reference/go-generated#package for more information.

--go_out: protoc-gen-go: Plugin failed with status code 1.

原因未知，protoc-gen-go插件无法生成.pb.go文件，换用protoc-gen-gofast插件。

$ protoc *.proto --gofast_out=.

标量类型

Protobuf类型	Golang类型	描述
int32	int32	变长编码，对于负值效率较低。若域可能存在负值可使用sint64替代。
int64	int64	-
uint32	uint32	变长编码
uint64	uint64	变长编码
sint32	int32	变长编码，在负值时比int32高效。
sint64	int64	变长编码，有符号整型值。编码时比int64高效。
fixed32	uint32	固长编码，4个字节，若数值大于2^28则比uint32高效。
fixed64	uint64	固长编码，8个字节，若数值大于2^56则比uint64高效。
sfixed32	int32	固长编码，4个字节。
sfixed64	int64	固长编码，8个字节。
float	float32	-
double	float64	-
bool	bool	默认false
bytes	[]byte	任意字节序列，长度不超过2^32，默认空数组。
string	string	UTF8编码或7-bit ASCII编码的文本，长度不超过2^32。

标量类型如果没有被赋值则不会被序列化，解析时会赋予默认值。

标量类型	默认值
strings	空字符串
bytes	空序列
bools	false
数值类型	0

风格

文件

• 文件名使用小写下划线的命名风格，例如lower_snake_case.proto。
• 每行不超过80个字符
• 使用2个空格缩进

包

• 包名应该和目录结构对应，例如文件在my/package/目录下，则包名为my.package。

消息

• 消息名使用首字母大写驼峰风格（CamelCase），例如message PlayerRequest{...}。
• 字段名使用小写下划线风格，例如string user_id = 1。
• 枚举类型中枚举名使用首字母大写驼峰风格，例如enum FooBar，枚举值使用全大写下划线分割的风格（CAPITALS_WITH_UNDERSCORES），例如FOO_DEFAULT = 1。

服务

• RPC服务名和方法名均使用首字母大写驼峰风格，例如service FooService{rpc GetSomething()}。

案例

创建.proto文件

$ vim ./pb/lobby.proto

syntax = "proto3";
package pb;

message Player{
    string user_id = 1;
    string name = 2;
    string icon = 3;
    int32 point = 4;
    int32 seat = 5;
    int32 identity = 6;  //身份
    int32 status = 7;  //状态
}

将.proto生成.pb.go文件

$ cd pb
$ protoc lobby.proto --gogo_out=.

测试代码

$ vim main.go

package main

import (
    "fmt"
    "gfw/pb"
    "github.com/gogo/protobuf/proto"
)

func main() {
    player := &pb.Player{
        UserId: "1",
        Name:   "admin",
    }
    //序列化
    buf, err := proto.Marshal(player)
    if err != nil {
        panic(err)
    }
    fmt.Printf("%v\n", buf)// [10 1 49 18 5 97 100 109 105 110]
    fmt.Printf("%s\n", buf)// 1admin
    //反序列化
    obj := &pb.Player{}
    err = proto.Unmarshal(buf, obj)
    if err != nil {
        panic(err)
    }
    fmt.Printf("%v\n", obj)// user_id:"1" name:"admin" 
    fmt.Printf("%v\n", obj.GetName()) // admin
}

$ go run main.go