我们要使用的示例，是一个狠简单的"地址本"应用程序，它能够将联系人的信息写入到文件中，并且在日后读取回来。地址本中的每个人物，都拥有一个名字、编号、邮件地址和联系电话号码。

妳会如何对这样的结构化数据进行序列化及读取？对于这个问题，有多种解决方法：

• •.使用Java自带的序列化功能（Serialization）。这是默认手段，因为，语言里自带了这种功能。但是它存在着一堆广为人知的问题(阅读Josh Bloch 的Effective Java，213 页)。并且，当妳需要与C++或Python 写的程序分享数据时，就不好搞了。

• •. 妳可以自己发明一种格式，用来将数据内容编码成一个单个的字符串——例如，将4个整数编码为"12:3:-23:67"。这种方法，狠简单也狠灵活，不过，它需要编写一次性的编码及解码代码，并且，解码过程要耗费一些运行时资源。对于非常简单的数据，这种方式最好。

• •. 将数据序列化为XML。这种方式，狠有吸引力，因为，XML是(某种程度上)人眼可读的，并且，狠多语言中都提供了对应的处理库。如果妳想与其它程序/项目共享数据的话，这是一个好方法。然而，XML有一个公认的毛病，那就是，太占用空间，并且，对它进行编码/解码也非常显著地影响到程序的性能。另外，对XML DOM 树进行遍历，也比对一般的类中的字段进行遍历要来得复杂。

Protocol buffers 就是专门为解决这种问题而开发的灵活、高效、自动的解决方案。 在使用 protocol buffers 的过程中， 妳编写一个 .proto 文件，用来描述妳想要存储的数据结构。根据那个文件， protocol buffer编译 器会生成一个类， 这个类会自动 以高效的二进制格式来对那个 protocol buffer 数据结构进行编码 及解码。 所生成的类，会提供针对 该protocol buffer 中 各个字段 的取值方法（ getters ） 和 设值方法（ setters ），并且 会处理好读取和写入过程中的各个细节，以便将该protocol buffer 作为一个单元来处理。 还有一个重要的特性，那就是， protocol buffer格式支持 妳在日后对该格式进行扩展，使得， 妳的代码仍然能够读取以旧格式编码的数据。

要开发妳的地址本程序，首先要创建一个 .proto 文件。 .proto 文件 中的定义是狠简单的 ：对于 妳想要序列化的每种数据结构，都加入一个消息定义（ message ），然后 ，为该消息中的每个字段指定一个名字和类型。 以下便是本教程中使用的 .proto 文件， addressbook.proto 。

package tutorial;

option java_package = "com.example.tutorial";

option java_outer_classname = "AddressBookProtos";

message Person {

required string name = 1;

required int32 id = 2;

optional string email = 3;

enum PhoneType {

MOBILE = 0;

HOME = 1;

WORK = 2;

}

message PhoneNumber {

required string number = 1;

optional PhoneType type = 2 [default = HOME];

}

repeated PhoneNumber phone = 4;

}

message AddressBook {

repeated Person person = 1;

}

妳应该感受到了，它的语法与C++或Java类似。让我们来详细研究一下这个文件中的各个部分，看看它们分别起到什么作用。

.proto 文件 的开头是一个包名声明， 它可以用来避免多个项目之间的命名冲突。 在 Java 中，开头声明 的包名会作为 所生成的Java 包的包名，除非 妳显式地指定一 个 java_package ， 我们在此教程里就是这么做的。即使 妳显式地提供了一个 java_package ， 妳仍然应当定义一个标准的 package ，以避免在Protocol Buffers 和其它非Java 的语言的命名空间中产生冲突。

包名定义之后 ，可以看到两 个 仅适用于Java 的选项： java_package 和 java_outer_classname 。 java_package ，指定的是，要将生成 的类放置到哪个Java 包中。如果 妳不显式地指定这个，那么， 它就会借用 package 声明 中指定的包名，但是 ，那个地方所声明的名字通常并不适合作为 Java包名使用(因为它们通常 不是以域名开头的 ) 。 java_outer_classname 选项 ，定义的是，用来包含 此文件中定义的所有类的类。如果 妳不显式指定 java_outer_classname ，那么 ， 它会将文件名转换成驼峰风格，并作为对应的类名。例如 ， "my_proto.proto" ，默认情况下，会使用"MyProto"作为外层类名。

接下来，就是消息定义了。消息，实际 上就是一个包含了一组各种类型的字段的聚合体。 有狠多标准的简单数据类型都可以作为字段类型来使用，包括： bool 、 int32 、 float 、 double 和 string 。 妳还可以将其它 的消息类型作为字段类型加入到妳的消息中—— 在上面的示例中， Person 消息 里包含着 PhoneNumber 消息， 而 AddressBook 消息 中又包含着 Person 消息 。 妳甚至还可以将消息类型嵌套地定义于其它消息内部——在本示例中， PhoneNumber 类型 即是定义于 Person 内部。 妳还可以定义枚举 （ enum ） 类型， 以确保某个字段 只取预定义列表中的某个值—— 本示例中， 我们指定了，电话号码 可以是 MOBILE 、 HOME 或 WORK 。

每个元素中" = 1"、" = 2"的标记，用来指定该字段在二进制编码中使用的唯一标识（"tag"）。1-15的标记值，要比其它的标记值少占用一个字节的编码空间，因此，作为一种优化手段，妳可以将这些标记值用于常用元素或重复元素，而将16及更大数字的标记值用于较少使用的可选元素。重复字段中的每个元素都需要将其标记值重新编码，因此，重复字段尤其适合于采用这种优化手段。

每个字段，必须使用以下某个修饰符来注解：

• •. required ： 此字段必须提供，否则 ， 该消息会被认为是“未初始化的”（"uninitialized"）。尝试构造 一个未初始化的消息，则会抛出 RuntimeException 异常。 对一个未初始化的消息进行解析，会抛出 IOException 异常。 除此之外，必选（required）字段与可选（optional）字段的行为完全相同。

• •. optional ：此字段可以存在，也可以不存在。如果 某个可选（optional）字段的值未被设置， 则， 会使用默认值。对于简单 的类型，妳可以指定自己的默认值， 在本示例中，我们就对电话号码（phone number）的 type 字段指定了默认值。如果 妳未指定默认值，则会使用系统默认值：数字类型 的默认值是0；字符串类型的默认值是空字符串；逻辑类型的默认值是假。对于嵌套 的消息，其默认值一定是 其消息的“默认实例”（"default instance"）或“原型”（"prototype"）， 即，任何字段都未设置。调用取值函数 去获取一个未显式设置值的可选（或必选）字段的值，会取到该字段的默认值。

• •. repeated ： 此字段可以重复任意次数 (包括 0次 ) 。那些 被重复的字段值，会在protocol buffer 中保留原有的顺序。 可以将重复字段当作动态改变尺寸的数组来看待。

必选（Required）属性是永久生效的。妳应当谨慎地将字段标记为必选（ required ）。如果，有朝一日，妳想要停止写入或发送某个必选字段的话，那么，在尝试将该字段变成可选字段的过程中就会遇到问题——旧的代码会将那些不包含该字段的消息当成是不完整的，因而会拒绝或丢弃对应的消息。妳应当考虑写一些与当前应用程序相关的自定义验证代码来验证消息的完整性，而不是依赖必选字段。Google某些的工程师认为，使用required，其带来的害处比好处要大；它们倾向于只使用optional和repeated。不过，这只是部分人的看法。

现在 ，已经写好了 .proto 。那么，下一个要做的事就是，生成对应 的类， 以便用来读取及写入 AddressBook (当然 还包括 Person 和 PhoneNumber )消息 。 为了完成这件事，妳需要针对妳的 .proto 文件来运行 protocol buffer 的编译器 protoc ：

生成 的代码中，包含一个名为 PhoneType 的Java 5 枚举，并且嵌套到 Person 中：

public static enum PhoneType {

MOBILE( 0 , 0 ),

HOME( 1 , 1 ),

WORK( 2 , 2 ),

;

...

}

而嵌套类 Person.PhoneNumber 呢，如妳所料，是被嵌套到 Person 中。

protocol buffer 编译 器生成的消息类，是只读的（ immutable ）。 一旦某个消息对象被创建出来了，它就不可再被修改了，就像Java  String 一样。 要想构造一个消息，妳必须先构造一个构建器， 将妳想设置的任何字段设置成对应的值，然后调用构建器的 build() 方法。

妳应该注意到了，在构建器中，每个能够修改该消息的方法，都返回另一个构建器实例。所返回的对象，实际上就是妳对其调用方法的同一个构建器对象。此处将它返回，是为了便于在同一行代码中串联式调用多个设值函数。

以下代码，展示了如何创建 Person 实例：

Person john =

Person .newBuilder()

.setId( 1234 )

.setName( "John Doe" )

.setEmail( "jdoe@example.com" )

.addPhone(

Person . PhoneNumber .newBuilder()

.setNumber( "555-4321" )

.setType( Person . PhoneType .HOME))

.build();

每个消息和构建器类，都还包含了一些其它方法，可用来检查或操作整个消息。这些方法包括：

• •. isInitialized() ：检查是否所有必选字段都已被设置。

• •. toString() ：返回一个人眼可读的字符串，用于描述该消息，对于调试尤其有用。

• •. mergeFrom(Message other) ： ( 仅适用于构建器 ) 将 other 中的内容合并到本消息中，具体 就是， 对单值字段进行覆盖，对重复字段进行串接。

• •. clear() ： ( 仅适用于构建器 ) 将所有字段清除，恢复到空白状态。

好了，让我们来试着使用一下妳的protocol buffer 类。妳想要利用地址本程序来做的第一件事就是，向地址本文件中写入人物的详细信息。要实现这一点，妳需要创建那些protocol buffer 类的实例，并且填充其中的数据，然后将它们写入到某个输出流中。

以下这个程序，从文件中读入一个 AddressBook ，根据用户 的输入向其中加入一个新的 Person ，然后 将新的 AddressBook 重新写入到文件中。那些直接调用 或引用由编译 器 生成的代码的部分，已经高亮显示。

import com.example.tutorial. AddressBookProtos . AddressBook;

import com.example.tutorial. AddressBookProtos . Person;

import java.io.BufferedReader;

import java.io.FileInputStream;

import java.io.FileNotFoundException;

import java.io.FileOutputStream;

import java.io.InputStreamReader;

import java.io.IOException;

import java.io.PrintStream;

class AddPerson {

// 这个函数，根据用户的输入来填充一个Person 消息。

static Person PromptForAddress ( BufferedReader stdin,

PrintStream stdout) throws IOException {

Person . Builder person = Person .newBuilder() ;

stdout. print ( "Enter person ID: " );

person.setId ( Integer .valueOf(stdin.readLine()));

stdout. print ( "Enter name: " );

person.setName (stdin.readLine());

stdout. print ( "Enter email address (blank for none): " );

String email = stdin.readLine();

if (email.length() > 0 ) {

person.setEmail (email);

}

while ( true ) {

stdout. print ( "Enter a phone number (or leave blank to finish): " );

String number = stdin.readLine();

if (number.length() == 0 ) {

break ;

}

Person . PhoneNumber . Builder phoneNumber =

Person . PhoneNumber .newBuilder().setNumber(number) ;

stdout. print ( "Is this a mobile, home, or work phone? " );

String type = stdin.readLine();

if (type.equals( "mobile" )) {

phoneNumber.setType( Person . PhoneType .MOBILE) ;

} else if (type.equals( "home" )) {

phoneNumber.setType( Person . PhoneType .HOME) ;

} else if (type.equals( "work" )) {

phoneNumber.setType( Person . PhoneType .WORK) ;

} else {

stdout.println( "Unknown phone type.  Using default." );

}

person.addPhone(phoneNumber) ;

}

return person.build() ;

}

// 主函数：从文件中读入整个地址本，

//   根据用户 的输入来加入一个联系人，然后将地址本重新写入到同一个文件中。

public static void main( String [] args) throws Exception {

if (args.length != 1 ) {

System .err.println( "Usage:  AddPerson ADDRESS_BOOK_FILE" );

System . exit (- 1 );

}

AddressBook . Builder addressBook = AddressBook .newBuilder() ;

// 读入已有的地址本。

try {

addressBook.mergeFrom ( new FileInputStream (args[ 0 ]));

} catch ( FileNotFoundException e) {

System . out .println(args[ 0 ] + ": File not found.  Creating a new file." );

}

// 加入 一个地址。

addressBook.addPerson (

PromptForAddress ( new BufferedReader ( new InputStreamReader ( System . in )),

System . out ));

// 将新的地址本重新写入到磁盘中。

FileOutputStream output = new FileOutputStream (args[ 0 ]);

addressBook.build().writeTo (output);

output.close();

}

}

显然，一个地址本，如果妳无法读取其中的内容，那么，它就一点卵用也没有！以下示例代码，从上面示例所创建的文件中读取信息，并且输出到终端。

import com.example.tutorial. AddressBookProtos . AddressBook;

import com.example.tutorial. AddressBookProtos . Person;

import java.io.FileInputStream;

import java.io.IOException;

import java.io.PrintStream;

class ListPeople {

// 遍历AddressBook 中的所有联系人，并且输出它们的信息。

static void Print ( AddressBook addressBook) {

for ( Person person: addressBook.getPersonList()) {

System . out .println( "Person ID: " + person.getId() );

System . out .println( "  Name: " + person.getName() );

if (person.hasEmail()) {

System . out .println( "  E-mail address: " + person.getEmail() );

}

for ( Person . PhoneNumber phoneNumber : person.getPhoneList() ) {

switch ( phoneNumber.getType() ) {

case MOBILE :

System . out . print ( "  Mobile phone #: " );

break ;

case HOME :

System . out . print ( "  Home phone #: " );

break ;

case WORK :

System . out . print ( "  Work phone #: " );

break ;

}

System . out .println( phoneNumber.getNumber() );

}

}

}

// 主函数： 从文件中读取整个地址本，然后输出其中的所有信息。

public static void main( String [] args) throws Exception {

if (args.length != 1 ) {

System .err.println( "Usage:  ListPeople ADDRESS_BOOK_FILE" );

System . exit (- 1 );

}

// 读取已有 的地址本。

AddressBook addressBook =

AddressBook .parseFrom ( new FileInputStream (args[ 0 ]));

Print (addressBook);

}

}

在发布了以妳的protocol buffer 为基础的代码之后，迟早妳会发现，妳想要“改善”该protocol buffer 的定义。如果妳希望新的数据格式向后兼容，同时旧的数据格式向前兼容——妳一定想要实现这种效果——的话，那么，妳需要遵守一些规则。在新版本的protocol buffer 中：

• •. 妳 不可以 改变任何已有字段 的标记（tag）数字。

• •. 妳 不可以 新加入或删除任何必选（required）字段。

• •. 妳 可以 删除可选 （optional）或重复（repeated）字段。

• •. 妳 可以 添加 新的可选（optional）或重复（repeated）字段，但是 ， 妳必须使用新的标记（ tag ）数字 ( 也就是说，必须使用之前从未在该 protocol buffer 中使用的标记数字，甚至 连已经被删除的字段的标记值也不能使用 ) 。