本文档向Go程序员介绍了如何使用协议缓冲区。通过创建一个简单的示例应用程序,它向您展示了如何
.proto
文件中定义消息格式。这不是在Go中使用协议缓冲区的全面指南。有关更多详细的参考信息,请参阅《协议缓冲区语言指南》,《Go API参考》,《Go生成的代码指南》和《编码参考》。
我们将使用的示例是一个非常简单的“地址簿”应用程序,该应用程序可以在文件中读取和写入人们的详细联系信息。通讯录中的每个人都有一个姓名,一个ID,一个电子邮件地址和一个联系电话。
您如何像这样序列化和检索结构化数据?有几种方法可以解决此问题:
协议缓冲区是灵活,高效,自动化的解决方案,可以准确地解决此问题。使用协议缓冲区,您可以编写.proto
要存储的数据结构的描述。由此,协议缓冲区编译器创建了一个类,该类以有效的二进制格式实现协议缓冲区数据的自动编码和解析。生成的类为构成协议缓冲区的字段提供了获取器和设置器,并以协议为单位来处理读取和写入协议缓冲区的详细信息。重要的是,协议缓冲区格式支持以某种方式扩展格式的思想,以使代码仍可以读取以旧格式编码的数据。
我们的示例是一组命令行应用程序,用于管理使用协议缓冲区编码的地址簿数据文件。该命令add_person_go
将新条目添加到数据文件。该命令list_people_go
解析数据文件并将数据打印到控制台。
您可以 在GitHub存储库的examples目录中找到完整的示例 。
要创建地址簿应用程序,您需要从.proto
文件开始 。.proto
文件中的定义很简单:您为要序列化的每个数据结构添加一条消息,然后为消息中的每个字段指定名称和类型。在我们的示例中,.proto
定义消息的文件为 addressbook.proto
。
该.proto
文件以程序包声明开头,这有助于防止不同项目之间的命名冲突。
syntax = "proto3";
package tutorial;
import "google/protobuf/timestamp.proto";
该go_package
选项定义了包的导入路径,该包将包含该文件的所有生成的代码。Go软件包名称将是导入路径的最后一个路径部分。例如,我们的示例将使用包名称“ tutorialpb”。
option go_package = "github.com/protocolbuffers/protobuf/examples/go/tutorialpb";
接下来,您将拥有消息定义。消息只是包含一组类型字段的汇总。许多标准的简单数据类型都可以作为字段类型,包括bool
,int32
, float
,double
,和string
。您还可以通过使用其他消息类型作为字段类型来为消息添加更多的结构。
message Person {
string name = 1;
int32 id = 2; // Unique ID number for this person.
string email = 3;
enum PhoneType {
MOBILE = 0;
HOME = 1;
WORK = 2;
}
message PhoneNumber {
string number = 1;
PhoneType type = 2;
}
repeated PhoneNumber phones = 4;
google.protobuf.Timestamp last_updated = 5;
}
// Our address book file is just one of these.
message AddressBook {
repeated Person people = 1;
}
在上面的示例中,Person
消息包含 PhoneNumber
消息,而AddressBook
消息包含Person
消息。您甚至可以定义嵌套在其他消息中的消息类型-如您所见,该 PhoneNumber
类型在inside中定义Person
。您还可以定义enum
,如果你希望你的领域之一,有预定义的值列表中的一个类型-在这里你要指定一个电话号码可以是一个MOBILE
,HOME
或 WORK
。
每个元素上的“ = 1”,“ = 2”标记标识该字段在二进制编码中使用的唯一“标记”。标签编号1至15与较高的编号相比,编码所需的字节减少了一个字节,因此,为了进行优化,您可以决定将这些标签用于常用或重复的元素,而将标签16和更高的标签用于较少使用的可选元素。重复字段中的每个元素都需要重新编码标签号,因此重复字段是此优化的最佳候选者。
如果未设置字段值, 则使用默认值:数字类型为零,字符串为空字符串,布尔值为false。对于嵌入式消息,默认值始终是消息的“默认实例”或“原型”,没有设置任何字段。调用访问器以获取尚未显式设置的字段的值将始终返回该字段的默认值。
如果一个字段为repeated
,则该字段可以重复任意次(包括零次)。重复值的顺序将保留在协议缓冲区中。将重复字段视为动态大小的数组。
您.proto
可以在“协议缓冲区语言指南”中找到有关编写文件的完整指南,包括所有可能的字段类型。但是,不要去寻找类似于类继承的工具–协议缓冲区不能做到这一点。
现在,您有了.proto
,接下来需要做的是生成您需要读取和写入AddressBook
(并因此Person
和PhoneNumber
)消息的类。要做到这一点,你需要运行协议缓冲编译器protoc
对您.proto
:
如果尚未安装编译器,请下载软件包并按照自述文件中的说明进行操作。
运行以下命令以安装Go协议缓冲区插件:
go install google.golang.org/protobuf/cmd/protoc-gen-go
编译器插件protoc-gen-go
将安装在 $GOBIN
,默认为$GOPATH/bin
。协议编译器必须在您的$PATH目录中protoc
才能找到它。
现在运行编译器,指定源目录(应用程序的源代码所在的位置;如果您不提供值,则使用当前目录),目标目录(您希望生成的代码进入的位置;通常与$SRC_DIR
相同)以及通向您的.proto的路径。在这种情况下,您将调用:
protoc -I=$SRC_DIR --go_out=$DST_DIR $SRC_DIR/addressbook.proto
因为您需要Go代码,所以可以使用该--go_out
选项–其他受支持的语言也提供了类似的选项。
这将github.com/protocolbuffers/protobuf/examples/go/tutorialpb/addressbook.pb.go
在您指定的目标目录中生成。
生成为addressbook.pb.go
您提供以下有用的类型:
AddressBook
具有People
字段的结构。Person
与域结构Name
,Id
,Email
和Phones
。Person_PhoneNumber
结构,其中包含Number
和的字段Type
。Person_PhoneType
为Person.PhoneType
枚举中的每个值定义的类型和值。您可以在Go Generated Code指南中详细了解确切生成的内容,但在大多数情况下,您可以将它们视为完全普通的Go类型。
这是list_people
命令的单元测试中的一个示例,该示例说明了如何创建Person的实例:
p := pb.Person{
Id: 1234,
Name: "John Doe",
Email: "[email protected]",
Phones: []*pb.Person_PhoneNumber{
{Number: "555-4321", Type: pb.Person_HOME},
},
}
使用协议缓冲区的全部目的是对数据进行序列化,以便可以在其他位置对其进行解析。在Go中,您可以使用proto
库的Marshal函数来序列化协议缓冲区数据。指向协议缓冲区消息的指针的指针struct
实现了该proto.Message
接口。调用proto.Marshal
返回协议缓冲区,并以其有线格式进行编码。例如,我们在add_person
命令中使用以下功能:
book := &pb.AddressBook{}
// ...
// Write the new address book back to disk.
out, err := proto.Marshal(book)
if err != nil {
log.Fatalln("Failed to encode address book:", err)
}
if err := ioutil.WriteFile(fname, out, 0644); err != nil {
log.Fatalln("Failed to write address book:", err)
}
要解析编码的消息,请使用proto
库的Unmarshal函数。调用此方法buf
会将数据解析为协议缓冲区,然后将结果放入中pb
。因此,要在list_people
命令中解析文件,我们使用:
// Read the existing address book.
in, err := ioutil.ReadFile(fname)
if err != nil {
log.Fatalln("Error reading file:", err)
}
book := &pb.AddressBook{}
if err := proto.Unmarshal(in, book); err != nil {
log.Fatalln("Failed to parse address book:", err)
}
在发布使用协议缓冲区的代码之后,迟早无疑会希望“改进”协议缓冲区的定义。如果您希望新的缓冲区向后兼容,而旧的缓冲区向后兼容,而您几乎肯定希望这样做,那么您需要遵循一些规则。在新版本的协议缓冲区中:
(这些规则有 一些例外,但很少使用。)
如果遵循这些规则,旧代码将很乐意阅读新消息,而忽略任何新字段。对于旧代码,删除的单个字段将仅具有其默认值,而删除的重复字段将为空。新代码还将透明地读取旧消息。
但是,请记住,新字段不会出现在旧消息中,因此您需要对默认值进行合理的处理。使用特定于类型的 默认值 :对于字符串,默认值为空字符串。对于布尔值,默认值为false。对于数字类型,默认值为零。
其它语言的可以看这里:https://developers.google.com/protocol-buffers/docs/tutorials
可以直接下载对应系统和版本的软件直接使用,可以把这当成gcc等编译器一样直接编译proto文件:
https://github.com/protocolbuffers/protobuf/releases
Windows下在下载安装protoc后,还需要将protoc路径添加到环境变量,这时cmd下运行可以找到protoc了:
但是goland运行时还是提示找不到protoc:
protoc: command not found
这时还需要将protoc.exe复制到:C:\Windows\System32
在运行时报错:
The import path must contain at least one forward slash ('/') character.
然后在issue中找到了解决方法:https://github.com/techschool/pcbook-go/issues/
即go_option中的当前路径Windows下可能和mac等有差异,Windows下是’./’。
这个通过设置代理也没办法解决,代理处理的包相当于是golang.org下相关的一些包,而protobuf是在google.golang.org下面,相当于不是标准库,是一些扩展,这部分代理服务是没有的;也是因为墙的原因,所以按照我们最初的思路我们可以将这部分包下载放到国内的代码仓库中,然后再下载即可。
对应的GitHub地址是:https://github.com/protocolbuffers/protobuf-go
可以通过fork的方式在gitee等国内平台进行定时同步,然后本地项目通过这些平台地址下载即可(或者import中直接替换成对应GitHub地址也可以,但是一般.pb.go是直接生成的,不建议修改)。