Protocol Buffer 基础:Kotlin

Kotlin 程序员使用 Protocol Buffers 的入门指南。

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

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

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

问题领域

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

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

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

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

在哪里找到示例代码

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

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

定义您的协议格式

要创建您的地址簿应用程序,您需要从 .proto 文件开始。.proto 文件中的定义很简单:您为要序列化的每个数据结构添加一个 message,然后为 message 中的每个字段指定名称和类型。在我们的示例中,定义消息的 .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 及更高用于不太常用的可选元素。重复字段中的每个元素都需要重新编码标记号,因此重复字段是此优化的特别好的候选者。

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

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

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

编译您的 Protocol Buffers

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

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

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

    protoc -I=$SRC_DIR --java_out=$DST_DIR --kotlin_out=$DST_DIR $SRC_DIR/addressbook.proto
    

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

请注意,如果您想生成 Kotlin 代码,则必须同时使用 --java_out--kotlin_out。这会在您指定的 Java 目标目录中生成一个 com/example/tutorial/protos/ 子目录,其中包含一些生成的 .java 文件,并在您指定的 Kotlin 目标目录中生成一个 com/example/tutorial/protos/ 子目录,其中包含一些生成的 .kt 文件。

Protocol Buffer API

针对 Kotlin 的 Protocol Buffer 编译器会生成 Kotlin API,这些 API 会添加到为 Java 的 Protocol Buffer 生成的现有 API 中。这确保了用 Java 和 Kotlin 混合编写的代码库可以与相同的 Protocol Buffer 消息对象进行交互,而无需任何特殊的处理或转换。

目前不支持其他 Kotlin 编译目标(如 JavaScript 和原生)的 Protocol Buffer。

编译 addressbook.proto 会在 Java 中生成以下 API

  • AddressBook
    • 在 Kotlin 中,它具有 peopleList : List<Person> 属性
  • Person
    • 在 Kotlin 中,它具有 nameidemailphonesList 属性
    • 具有 numbertype 属性的 Person.PhoneNumber 嵌套类
    • Person.PhoneType 嵌套枚举

还会生成以下 Kotlin API

  • addressBook { ... }person { ... } 工厂方法
  • 一个 PersonKt 对象,带有一个 phoneNumber { ... } 工厂方法

您可以在 Kotlin 生成的代码指南 中了解更多关于生成内容的详细信息。

编写消息

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

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

import com.example.tutorial.Person
import com.example.tutorial.AddressBook
import com.example.tutorial.person
import com.example.tutorial.addressBook
import com.example.tutorial.PersonKt.phoneNumber
import java.util.Scanner

// This function fills in a Person message based on user input.
fun promptPerson(): Person = person {
  print("Enter person ID: ")
  id = readLine().toInt()

  print("Enter name: ")
  name = readLine()

  print("Enter email address (blank for none): ")
  val email = readLine()
  if (email.isNotEmpty()) {
    this.email = email
  }

  while (true) {
    print("Enter a phone number (or leave blank to finish): ")
    val number = readLine()
    if (number.isEmpty()) break

    print("Is this a mobile, home, or work phone? ")
    val type = when (readLine()) {
      "mobile" -> Person.PhoneType.PHONE_TYPE_MOBILE
      "home" -> Person.PhoneType.PHONE_TYPE_HOME
      "work" -> Person.PhoneType.PHONE_TYPE_WORK
      else -> {
        println("Unknown phone type.  Using home.")
        Person.PhoneType.PHONE_TYPE_HOME
      }
    }
    phones += phoneNumber {
      this.number = number
      this.type = type
    }
  }
}

// Reads the entire address book from a file, adds one person based
// on user input, then writes it back out to the same file.
fun main(args: List) {
  if (arguments.size != 1) {
    println("Usage: add_person ADDRESS_BOOK_FILE")
    exitProcess(-1)
  }
  val path = Path(arguments.single())
  val initialAddressBook = if (!path.exists()) {
    println("File not found. Creating new file.")
    addressBook {}
  } else {
    path.inputStream().use {
      AddressBook.newBuilder().mergeFrom(it).build()
    }
  }
  path.outputStream().use {
    initialAddressBook.copy { peopleList += promptPerson() }.writeTo(it)
  }
}

读取消息

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

import com.example.tutorial.Person
import com.example.tutorial.AddressBook

// Iterates though all people in the AddressBook and prints info about them.
fun print(addressBook: AddressBook) {
  for (person in addressBook.peopleList) {
    println("Person ID: ${person.id}")
    println("  Name: ${person.name}")
    if (person.hasEmail()) {
      println("  Email address: ${person.email}")
    }
    for (phoneNumber in person.phonesList) {
      val modifier = when (phoneNumber.type) {
        Person.PhoneType.PHONE_TYPE_MOBILE -> "Mobile"
        Person.PhoneType.PHONE_TYPE_HOME -> "Home"
        Person.PhoneType.PHONE_TYPE_WORK -> "Work"
        else -> "Unknown"
      }
      println("  $modifier phone #: ${phoneNumber.number}")
    }
  }
}

fun main(args: List) {
  if (arguments.size != 1) {
    println("Usage: list_person ADDRESS_BOOK_FILE")
    exitProcess(-1)
  }
  Path(arguments.single()).inputStream().use {
    print(AddressBook.newBuilder().mergeFrom(it).build())
  }
}

扩展 Protocol Buffer

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

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

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

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

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