Protocol Buffer 基础:Dart

一个关于使用 Protocol Buffers 的 Dart 程序员入门指南。

本教程为 Dart 程序员提供了使用 Protocol Buffers 的入门指南,使用 Protocol Buffers 语言的 proto3 版本。通过逐步创建一个简单的示例应用程序,它向您展示了如何

  • .proto 文件中定义消息格式。
  • 使用 Protocol Buffer 编译器。
  • 使用 Dart Protocol Buffer API 编写和读取消息。

这不是关于在 Dart 中使用 Protocol Buffers 的全面指南。有关更详细的参考信息,请参阅 Protocol Buffer 语言指南Dart 语言教程Dart API 参考Dart 生成代码指南编码参考

问题领域

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

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

  • 您可以发明一种临时的方法将数据项编码成单个字符串——例如,将 4 个整数编码为“12:3:-23:67”。这是一种简单灵活的方法,尽管它确实需要编写一次性编码和解析代码,并且解析会带来少量运行时成本。这最适合编码非常简单的数据。
  • 将数据序列化为 XML。这种方法可能非常有吸引力,因为 XML(某种程度上)是人类可读的,并且许多语言都有绑定库。如果您想与其他应用程序/项目共享数据,这可能是一个不错的选择。但是,XML notoriouly 占用空间很大,编码/解码它会对应用程序造成巨大的性能损失。此外,导航 XML DOM 树比导航类中的简单字段复杂得多。

Protocol Buffers 是一个灵活、高效、自动化的解决方案,可以精确地解决此问题。使用 Protocol Buffers,您可以编写要存储的数据结构的 .proto 描述。由此,Protocol Buffer 编译器创建一个类,该类使用高效的二进制格式实现 Protocol Buffer 数据的自动编码和解析。生成的类为构成 Protocol Buffer 的字段提供 getter 和 setter,并负责将 Protocol Buffer 作为一个单元读取和写入的细节。重要的是,Protocol Buffer 格式支持随着时间的推移扩展格式,以便代码仍然可以读取使用旧格式编码的数据。

在哪里找到示例代码

我们的示例是一组用于管理地址簿数据文件的命令行应用程序,使用 Protocol Buffers 进行编码。命令 dart add_person.dart 将新条目添加到数据文件。命令 dart list_people.dart 解析数据文件并将数据打印到控制台。

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

定义您的协议格式

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

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

syntax = "proto3";
package tutorial;

import "google/protobuf/timestamp.proto";

接下来,您有您的消息定义。消息只是一个包含一组类型化字段的聚合。许多标准简单数据类型可用作字段类型,包括 boolint32floatdoublestring。您还可以通过使用其他消息类型作为字段类型来为您的消息添加更多结构。

message Person {
  string name = 1;
  int32 id = 2;  // Unique ID number for this person.
  string email = 3;

  enum PhoneType {
    PHONE_TYPE_UNSPECIFIED = 0;
    PHONE_TYPE_MOBILE = 1;
    PHONE_TYPE_HOME = 2;
    PHONE_TYPE_WORK = 3;
  }

  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 内部定义的。如果希望您的某个字段具有预定义值列表之一,您还可以定义 enum 类型——在这里,您希望指定电话号码可以是 PHONE_TYPE_MOBILEPHONE_TYPE_HOMEPHONE_TYPE_WORK 之一。

每个元素上的“= 1”、“= 2”标记标识该字段在二进制编码中使用的唯一“标签”。标签号 1-15 比更高的数字少用一个字节进行编码,因此作为优化,您可以决定将这些标签用于常用或重复的元素,将标签 16 及更高的标签用于不太常用的可选元素。重复字段中的每个元素都需要重新编码标签号,因此重复字段是此优化的特别好的候选者。

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

如果字段是 repeated,则可以重复该字段任意次数(包括零次)。重复值的顺序将保存在 Protocol Buffer 中。将重复字段视为动态大小的数组。

您可以在 Protocol Buffer 语言指南 中找到编写 .proto 文件的完整指南——包括所有可能的字段类型。不过,不要去寻找类似于类继承的功能——Protocol Buffers 不支持。

编译您的 Protocol Buffers

现在您有了 .proto,接下来您需要做的是生成读取和写入 AddressBook(以及 PersonPhoneNumber)消息所需的类。为此,您需要在您的 .proto 上运行 Protocol Buffer 编译器 protoc

  1. 如果您尚未安装编译器,请 下载软件包 并按照 README 中的说明进行操作。

  2. 按照 其 README 中的说明安装 Dart Protocol Buffer 插件。可执行文件 bin/protoc-gen-dart 必须位于您的 PATH 中,以便 Protocol Buffer protoc 找到它。

  3. 现在运行编译器,指定源目录(应用程序源代码所在的目录——如果您不提供值,则使用当前目录)、目标目录(您希望生成的代码放在哪里;通常与 $SRC_DIR 相同)和 .proto 的路径。在这种情况下,您将调用

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

    因为您想要 Dart 代码,所以您使用 --dart_out 选项——为其他支持的语言提供了类似的选项。

这将在您指定的目标目录中生成 addressbook.pb.dart

Protocol Buffer API

生成 addressbook.pb.dart 为您提供了以下有用的类型

  • 一个 AddressBook 类,带有一个 List<Person> get people 获取器。
  • 一个 Person 类,带有所需 nameidemailphones 的访问器方法。
  • 一个 Person_PhoneNumber 类,带有所需 numbertype 的访问器方法。
  • 一个 Person_PhoneType 类,其中包含 Person.PhoneType 枚举中每个值的静态字段。

您可以在 Dart 生成代码指南 中详细了解生成的具体内容。

编写消息

现在让我们尝试使用您的 Protocol Buffer 类。您的地址簿应用程序首先需要能够做的事情是将个人详细信息写入您的地址簿文件。为此,您需要创建并填充 Protocol Buffer 类的实例,然后将其写入输出流。

这是一个程序,它从文件中读取一个 AddressBook,根据用户输入向其中添加一个新的 Person,并将新的 AddressBook 再次写回文件。直接调用或引用协议编译器生成的代码的部分已突出显示。

import 'dart:io';

import 'dart_tutorial/addressbook.pb.dart';

// This function fills in a Person message based on user input.
Person promptForAddress() {
  Person person = Person();

  print('Enter person ID: ');
  String input = stdin.readLineSync();
  person.id = int.parse(input);

  print('Enter name');
  person.name = stdin.readLineSync();

  print('Enter email address (blank for none) : ');
  String email = stdin.readLineSync();
  if (email.isNotEmpty) {
    person.email = email;
  }

  while (true) {
    print('Enter a phone number (or leave blank to finish): ');
    String number = stdin.readLineSync();
    if (number.isEmpty) break;

    Person_PhoneNumber phoneNumber = Person_PhoneNumber();

    phoneNumber.number = number;
    print('Is this a mobile, home, or work phone? ');

    String type = stdin.readLineSync();
    switch (type) {
      case 'mobile':
        phoneNumber.type = Person_PhoneType.PHONE_TYPE_MOBILE;
        break;
      case 'home':
        phoneNumber.type = Person_PhoneType.PHONE_TYPE_HOME;
        break;
      case 'work':
        phoneNumber.type = Person_PhoneType.PHONE_TYPE_WORK;
        break;
      default:
        print('Unknown phone type.  Using default.');
    }
    person.phones.add(phoneNumber);
  }

  return person;
}

// Reads the entire address book from a file, adds one person based
// on user input, then writes it back out to the same file.
main(List arguments) {
  if (arguments.length != 1) {
    print('Usage: add_person ADDRESS_BOOK_FILE');
    exit(-1);
  }

  File file = File(arguments.first);
  AddressBook addressBook;
  if (!file.existsSync()) {
    print('File not found. Creating new file.');
    addressBook = AddressBook();
  } else {
    addressBook = AddressBook.fromBuffer(file.readAsBytesSync());
  }
  addressBook.people.add(promptForAddress());
  file.writeAsBytes(addressBook.writeToBuffer());
}

读取消息

当然,如果无法从中获取任何信息,地址簿就没有多大用处!此示例读取上面示例创建的文件,并打印其中的所有信息。

import 'dart:io';

import 'dart_tutorial/addressbook.pb.dart';
import 'dart_tutorial/addressbook.pbenum.dart';

// Iterates though all people in the AddressBook and prints info about them.
void printAddressBook(AddressBook addressBook) {
  for (Person person in addressBook.people) {
    print('Person ID: ${ person.id}');
    print('  Name: ${ person.name}');
    if (person.hasEmail()) {
      print('  E-mail address:${ person.email}');
    }

    for (Person_PhoneNumber phoneNumber in person.phones) {
      switch (phoneNumber.type) {
        case Person_PhoneType.PHONE_TYPE_MOBILE:
          print('   Mobile phone #: ');
          break;
        case Person_PhoneType.PHONE_TYPE_HOME:
          print('   Home phone #: ');
          break;
        case Person_PhoneType.PHONE_TYPE_WORK:
          print('   Work phone #: ');
          break;
        default:
          print('   Unknown phone #: ');
          break;
      }
      print(phoneNumber.number);
    }
  }
}

// Reads the entire address book from a file and prints all
// the information inside.
main(List arguments) {
  if (arguments.length != 1) {
    print('Usage: list_person ADDRESS_BOOK_FILE');
    exit(-1);
  }

  // Read the existing address book.
  File file = new File(arguments.first);
 AddressBook addressBook = new AddressBook.fromBuffer(file.readAsBytesSync());
  printAddressBook(addressBook);
}

扩展 Protocol Buffer

在发布使用 Protocol Buffer 的代码后,您迟早会想要“改进” Protocol Buffer 的定义。如果您希望新的缓冲区向后兼容,并且旧的缓冲区向前兼容——而您几乎肯定希望这样——那么您需要遵循一些规则。在 Protocol Buffer 的新版本中

  • 不能更改任何现有字段的标签编号。
  • 可以删除字段。
  • 可以添加新字段,但必须使用新的标签编号(即在此 Protocol Buffer 中从未使用过的标签编号,即使已删除的字段也未曾使用过)。

(这些规则有一些例外情况,但很少使用。)

如果您遵循这些规则,旧代码将愉快地读取新消息并简单地忽略任何新字段。对于旧代码,已删除的单一字段将简单地具有其默认值,而已删除的重复字段将为空。新代码也将透明地读取旧消息。

但是,请记住,旧消息中将不存在新字段,因此您需要对默认值进行合理的处理。将使用特定于类型的默认值:对于字符串,默认值为空字符串。对于布尔值,默认值为 false。对于数字类型,默认值为零。