07-Go语言指南

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

  • 在.proto文件中定义消息格式
  • 使用protocol buffers编译器
  • 使用 Go protocol buffers API来编写和读取消息

这不是在Go中使用protocol buffers的综合指南。有关更详细的参考信息，请参阅“protocol buffers语言指南”，“Go API参考”，“生成代码指南”和“编码参考”。

0.1. 为何使用Protocol Buffers

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

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

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

protocol buffers是灵活，高效，自动化的解决方案，可以解决这个问题。使用protocol buffers编写要存储的数据结构的.proto描述文件。然后protocol buffers编译器创建一个类，该类使用有效的二进制格式实现protocol buffers数据的自动编码和解析。生成的类为构成protocol buffers的字段提供getter和setter，并生成一个protocol buffers，并将protocol buffers作为一个单元读取和写入详细信息。重要的是，protocol buffers格式支持扩展格式，使得代码仍然可以读取用旧格式编码的数据。

0.2. 在哪里查看样例代码

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

可以在GitHub存储库的examples目录中找到完整的示例。

0.3. 自定义协议格式

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

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

syntax = "proto3";
package tutorial;

import "google/protobuf/timestamp.proto";

在Go中，包名称用作Go包，除非指定了go_package。即使确实提供了go_package，仍然应该定义一个普通的包，以避免在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和更大数字的标签号留给不太常用的可选元素。重复字段中的每个元素都需要重新编码标记号，因此重复字段特别适合此优化。

如果未设置字段的值，则使用默认值：数字类型为零，字符串为空字符串，布尔型为false。对于嵌入式消息，默认值始终是消息的“默认实例”或“原型”，其中没有设置其字段。调用访问器以获取尚未显式设置的字段的值始终返回该字段的默认值。

对于重复字段，该字段可以重复任意次数（包括零）。重复值的顺序将保留在protocol buffers中。将重复字段视为动态数组。

在Protocol Buffer指南中找到编写.proto文件的完整指南，包括所有可能的字段类型。不要去寻找类继承这样的工具，protocol buffers不会这样做。

0.4. 编译Protocol Buffers

既然有一个.proto文件，需要做的下一件事是生成读取和写入AddressBook（以及Person和PhoneNumber）消息所需的类。为此，需要在.proto上运行protocol buffers编译器protoc：

  1. 如果尚未安装编译器，请下载该软件包并按照自述文件中的说明进行操作。

  2. 运行以下命令安装Go protocol buffers 插件

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

    编译器插件protoc-gen-go将被安装在$GOBIN中，默认为$GOPATH/bin。该路径必须在$PATH中，协议编译器protoc才能找到它。

  3. 现在运行编译器：

    1. 指定源目录（应用程序的源代码所在的位置，如果不提供值，则使用当前目录），
    2. 指定目的目录（希望生成的代码存放的位置，通常与$SRC_DIR相同），
    3. 指定.proto的路径。

如下所示：

protoc -I=$SRC_DIR --go_out=$DST_DIR $SRC_DIR/addressbook.proto

因为需要Go类，所以使用--go_out选项，其他支持的语言也可以提供类似的选项。

这会在指定的目标目录（$DST_DIR）中生成addressbook.pb.go。

0.5. Protocol Buffers API

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

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

可以阅读更多有关“生成代码”指南中生成的内容的详细信息，但在大多数情况下，可以将这些视为完全普通的Go类型。

这是list_people命令关于如何创建Person实例的单元测试的示例：

p := pb.Person{
        Id:    1234,
        Name:  "John Doe",
        Email: "jdoe@example.com",
        Phones: []*pb.Person_PhoneNumber{
                {Number: "555-4321", Type: pb.Person_HOME},
        },
}

0.6. 写一条消息

使用protocol buffers的目的是序列化数据，以便可以在其他地方解析它。在Go中，使用proto库的Marshal函数来序列化protocol buffers数据。指向protocol buffers消息的struct的指针实现了proto.Message接口。调用proto.Marshal会返回以传输格式编码的protocol buffers。例如，在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)
}

0.7. 读一条消息

要解析编码的消息，使用proto库的Unmarshal函数。调用它将buf中的数据解析为protocol buffers，并将结果放在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)
}

0.8. 扩展一个Protocol Buffers

一段时间后，会释放使用protocol buffers的代码，毫无疑问会想要“改进”protocol buffers的定义。如果希望新缓冲区向后兼容，并且旧缓冲区是向前兼容的，那么需要在新得到protocol buffers中遵循一些规则：

  • 不得更改任何现有字段的标记号。
  • 可以删除字段。
  • 可以添加新字段，但必须使用新的标记号（即从未在此协议缓冲区中使用的标记号，甚至不包括已删除的字段）。

这些规则有一些例外，但它们很少使用。

如果遵循这些规则，旧代码将很乐意阅读新消息并简单地忽略任何新字段。对于旧代码，已删除的单个字段将只具有其默认值，删除的重复字段将为空。新代码也将透明地读取旧消息。

但是，请记住旧消息中不会出现新字段，因此需要使用默认值执行合理的操作。使用特定于类型的默认值：

  • 对于字符串，默认值为空字符串
  • 对于布尔值，默认值为false
  • 对于数字类型，默认值为零
上次修改: 14 April 2020