在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：

1. 请先确保已经安装了编译器protoc

2. protoc须要安装插件才能编译生成Go代码，能够运行以下命令安装插件

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

3. 如今运行编译器，指定源目录（应用程序的源代码所在的位置 - 若是不提​​供值，则使用当前目录），目标目录（您但愿生成的代码在哪里;一般与$相同） 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数据。