在Golang中使用Protobuf

本教程使用proto3版本的protocol buffer语言，提供了一个基本的在Go程序中使用protocol buffer的介绍。通过创建一个简单的示例应用程序，向你展示如何

在.proto文件中定义消息格式。
使用protoc编译器编译生成Go代码。
使用Go的protocol buffer API读写消息。

它不是一个全面的在Go中使用protocol buffer的指南，更详细的参考信息请查看前面的两个教程。

Protobuf语言指南

Protobuf生成Go代码指南

为什么使用protocol buffer

我们将要使用的示例是一个非常简单的“地址簿”应用程序，可以在文件中读取和写入人员的联系人详细信息。地址簿中的每个人都有姓名，ID，电子邮件地址和联系电话号码。

如何序列化和检索这样的结构化数据？有几种方法可以解决这个问题：

使用gobs（Go中自定义的序列化编码格式）序列化Go数据结构。这是Go特定环境中的一个很好的解决方案，但如果需要与为其他平台编写的应用程序共享数据，它将无法正常工作。
可以发明一种特殊的方法将数据项编码为单个字符串 - 例如将4个整数编码为“12：3：-23：67”。这是一种简单而灵活的方法，虽然它确实需要编写一次性编码和解析代码，并且解析会产生较小的运行时成本。这最适合编码非常简单的数据。
将数据序列化为XML。这种方法非常有吸引力，因为XML（有点）是人类可读懂的，并且有许多语言都有相应的类库。如果您想与其他应用程序/项目共享数据，这可能是一个不错的选择。然而，XML是众所周知的空间密集型，并且编码/解码它会对应用程序造成巨大的性能损失。此外，导航XML DOM树比通常在类中导航简单字段要复杂得多。

protocol buffer是灵活，高效，自动化的解决方案，可以解决这个问题。使用protocol buffer，您可以编写要存储的数据结构的.proto描述。由此，protocol buffer编译器会创建一个类，该类使用有效的二进制格式实现协议缓冲区数据的自动编码和解析。生成的类会为构成protocol buffer的字段提供getter和setter，并负责将protocol buffer作为一个单元读取和写入的细节。重要的是，protocol buffer格式支持随着时间的推移扩展格式的想法，使得代码仍然可以读取使用旧格式编码的数据。

获得示例程序

示例是一组用于管理地址簿数据文件的命令行应用程序，使用protocol buffer进行编码。命令add_person_go向数据文件添加新条目。命令list_people_go解析数据文件并将数据打印到控制台。

下载这些文件到你的项目目录中：

描述protocol buffer消息格式的.proto文件 addressbook.proto
命令行程序add_person.go，list_people.go

定义协议格式

要创建地址簿应用程序，您需要从.proto文件开始。 .proto文件中的定义很简单：为要序列化的每个数据结构定义消息，然后为消息中的每个字段指定名称和类型。在我们的示例中，定义消息的.proto文件是addressbook.proto。

.proto文件以包声明开头，这有助于防止不同项目之间的命名冲突。

syntax = "proto3";
package tutorial;import "google/protobuf/timestamp.proto";

在Go中，protocol buffer的包名称用作Go包，除非您指定了go_package。即使你确实提供了go_package，你仍然应该在.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不支持这些。

编译protocol buffers

有了.proto后，你需要做的下一件事是生成你需要读取和写入AddressBook（以及Person和PhoneNumber）消息所需的类（Go中是结构体和结构体方法）。为此，你需要在.proto上运行protocol buffer译器protoc：

请先确保已经安装了编译器protoc
protoc需要安装插件才能编译生成Go代码，可以运行如下命令安装插件
```
go get -u github.com/golang/protobuf/protoc-gen-go
```
现在运行编译器，指定源目录（应用程序的源代码所在的位置 - 如果不提供值，则使用当前目录），目标目录（您希望生成的代码在哪里;通常与$相同） SRC_DIR），以及.proto的路径。在这种情况下，你...：
```
protoc -I=$SRC_DIR --go_out=$DST_DIR $SRC_DIR/addressbook.proto
```

我们使用的示例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目录需要提前创建好。

Protocol buffer API

生成addressbook.pb.go提供以下有用类型：

拥有有People字段的AddressBook结构体。
拥有Name，Id，Email和Phones字段的Person结构体。
Person_PhoneNumber结构体，包含Number和Type字段。
类型Person_PhoneType和为Person.PhoneType枚举中的每个值定义的常量。

可以有关“生成代码”指南中生成的内容的详细信息，但在大多数情况下，您可以将这些视为完全普通的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},},
}

在Go中序列化protocol buffer数据

使用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)
}

在Go中解析protocol buffer

要解析编码消息，请使用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应用程序

命令行中运行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数据。