本教程使用proto3版本的protocol buffer语言,提供了一个基本的在Go程序中使用protocol buffer的介绍。通过创建一个简单的示例应用程序,向你展示如何
.proto
文件中定义消息格式。它不是一个全面的在Go中使用protocol buffer的指南,更详细的参考信息请查看前面的两个教程。
我们将要使用的示例是一个非常简单的“地址簿”应用程序,可以在文件中读取和写入人员的联系人详细信息。地址簿中的每个人都有姓名,ID,电子邮件地址和联系电话号码。
如何序列化和检索这样的结构化数据?有几种方法可以解决这个问题:
protocol buffer是灵活,高效,自动化的解决方案,可以解决这个问题。使用protocol buffer,您可以编写要存储的数据结构的 .proto
描述。由此,protocol buffer编译器会创建一个类,该类使用有效的二进制格式实现协议缓冲区数据的自动编码和解析。生成的类会为构成protocol buffer的字段提供getter和setter,并负责将protocol buffer作为一个单元读取和写入的细节。重要的是,protocol buffer格式支持随着时间的推移扩展格式的想法,使得代码仍然可以读取使用旧格式编码的数据。
示例是一组用于管理地址簿数据文件的命令行应用程序,使用protocol buffer进行编码。命令 add_person_go
向数据文件添加新条目。命令 list_people_go
解析数据文件并将数据打印到控制台。
PS: 微信不让加外链点击原文链接去github上下载程序代码吧。
下载这些文件到你的项目目录中:
.proto
文件 addressbook.proto要创建地址簿应用程序,您需要从 .proto
文件开始。.proto文件中的定义很简单:为要序列化的每个数据结构定义消息,然后为消息中的每个字段指定名称和类型。在我们的示例中,定义消息的.proto文件是addressbook.proto。
.proto文件以包声明开头,这有助于防止不同项目之间的命名冲突。
syntax = "proto3";package tutorial;
import "google/protobuf/timestamp.proto";
在Go中,protocol buffer的包名称用作Go包,除非您指定了gopackage。即使你确实提供了gopackage,你仍然应该在 .proto
文件中定义一个包名,以避免在Protocol Buffers命名空间和非Go语言中发生名称冲突。
接下来,是消息定义。消息只是包含一组类型字段的聚合。许多标准的简单数据类型都可用作字段类型,包括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
类型在 Person
中定义。如果您希望其中一个字段值的取值范围是预定义的值列表中的值,还可以定义枚举类型 - 此处你要指定电话号码可以是 MOBILE
, HOME
或 WORK
之一。
每个元素上的“= 1”,“= 2”标记标识该字段在二进制编码中使用的唯一“标记”。标签号1-15编码时比更大编号少需要一个字节,因此作为优化,您可以决定将这些标签用于常用或重复的元素,将标签16和更高标签留给不太常用的可选元素。重复字段中的每个元素都需要重新编码标记号,因此重复字段特别适合此优化。
如果未设置字段值,则使用默认值:数字类型为零,字符串为空字符串,bools为false。对于嵌入式消息,默认值始终是消息的“默认实例”或“原型”,其中没有设置其字段。调用访问器以获取尚未显式设置的字段的值始终返回该字段的默认值。
如果一个字段是可重复的,该字段可以重复任意次数(包括零)。重复值的顺序将保留在protocol buffer中。将可重复字段视为变长数组。
您将在Protobuf语言指南中找到编写.proto文件的完整指南 - 包括所有可能的字段类型。不要去寻找类继承类似的东西,protocol buffer不支持这些。
有了 .proto
后,你需要做的下一件事是生成你需要读取和写入AddressBook(以及Person和PhoneNumber)消息所需的类(Go中是结构体和结构体方法)。为此,你需要在.proto上运行protocol buffer译器protoc:
protoc
我们使用的示例go代码中导入编译后的 pb.go文件的路径是 pb"github.com/protocolbuffers/protobuf/examples/tutorial" 所以用protoc编译时使用的目标路径应该是
protoc --go_out=$GOPATH/src/github.com/protocolbuffers/protobuf/examples/tutorial ./addressbook.proto
$GOPATH/src/github.com/protocolbuffers/protobuf/examples/tutorial
目录需要提前创建好。
生成addressbook.pb.go提供以下有用类型:
可以阅读更多有关“生成代码”指南中生成的内容的详细信息,但在大多数情况下,您可以将这些视为完全普通的Go类型。
行动胜千言,下载教程中提供的代码,运行上面的编译命令,去看看生成的 addressbook.pb.go
中的代码吧。
下面是如何创建Person实例的示例:
p := pb.Person{ Id: 1234, Name: "John Doe", Email: "jdoe@example.com", Phones: []*pb.Person_PhoneNumber{ {Number: "555-4321", Type: pb.Person_HOME}, },}
使用protocl buffer目的是序列化你的结构化数据,以便可以在其他地方解析它。在Go中,使用 proto
库的 Marshal
函数来序列化protocol buffer数据。指向消息的结构体的指针实现了 proto.Message
接口。调用 proto.Marshal
会返回以其有线格式编码的protocol buffer。例如,我们在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中的数据解析为protocol buffer,并将结果放在结构体中。因此,要在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)}
go build add_person.go
和 go build list_people.go
会生成两个二进制文件 add_person
和 list_people
。./add_person ADDRESS_BOOK
程序会在命令行中提示输入,用命令行的输入构建地址簿数据然后将数据序列化为protocol buffer存储到文件 ADDRESS_BOOK
中。./list_people
程序会从文件 ADDRESS_BOOK
读取protocol buffer数据,解析到结构体中然后打印出结构体中的 Person
数据。