乐趣区

在Golang中使用Protobuf

jiezi

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

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

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

为什么使用 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 数据。
退出移动版