Protocol Buffers文档翻译:开发者指南,Developer Guide
欢迎阅读协议缓冲区(protocol buffers)的开发者文档, protocol buffers是一个与语言无关的、与平台无关的、可扩展的结构化数据序列化工具,可用于通信协议、数据存储等等。
此文档是针对那些想要在它们的应用程序中使用 protocol buffers 的Java、C++ 或Python 开发者的。 这篇概述会向妳介绍 protocol buffers ,并且说明妳该如何开始——然后, 妳可以跟随 教程 进行学习,或者,深入研究 protocol buffer编码 。 另外 也为三种语言提供了 API 参考文档 ,以及, 在编写 .proto 文件时用得上的 语言 和 风格 指南。
Protocol buffers是一种用来将结构化数据序列化的灵活、高效、自动化的工具——想一下XML吧,但是它比XML更小、更快、更简单。妳只需要一次性定义妳的数据的结构,然后,就可以在多种语言中使用特殊生成的源代码来轻松地将结构化数据向多种数据流中读取或写入。甚至,妳可以更新妳的数据结构,而无需变动那些针对“旧”格式编译的已部署的程序。
妳在 .proto 文件中定义protocol buffer 消息类型,以指定要序列化的信息的结构。每个 protocol buffer消息 都是一个小小的信息逻辑记录,其中包含 着一系列的名字/值对。 以下是一个狠基本的 .proto 文件示例, 它定义的消息中包含着关于单个人儿的信息:
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;
}
如妳所见,消息格式狠简单——每个消息类型 中,有一个或多个唯一的以数字标识的字段,每个字段 有 一个名字和值类型,其中 ,值类型可以是数字 (整数 或浮点数 ) 、逻辑值、字符串、原始字节序列,甚至 ( 就像上面示例中展示的那样 ) 可以是其它的 protocol buffer消息类型 , 这样妳就可以将妳的数据嵌套地组织起来了。 妳可以指定可选字段、 必选字段 及重复字段。 妳可在 Protocol Buffer语言指南 中找到更多关于如何编写 .proto 文件的信息。
当妳定义完了消息之后, 就可以运行 protocol buffer编译 器,来利用 .proto 文件针对妳的应用程序的语言生成对应的数据访问类了。 这些类,针对每个字段都提供了简单的访问器 (例如 name() 和 set_name() ) , 还提供了将整个结构进行序列化为原始字节数组和从原始字节数组解析出整个结构的方法—— 举个例子,如果妳选择的语言是 C++ ,那么, 对上面那个示例代码运行编译器的话,会生成一个名为 Person 的类。然后 , 妳就可以在自己的程序中使用这个类来填充、序列化及获取 Person 的 protocol buffer消息 了。 妳可以编写如下的代码:
Person person;
person.set_name("John Doe");
person.set_id(1234);
person.set_email("jdoe@example.com");
fstream output("myfile", ios::out | ios::binary);
person.SerializeToOstream(&output);
日后,可以这样将它读取回来:
fstream input("myfile", ios::in | ios::binary);
Person person;
person.ParseFromIstream(&input);
cout << "Name: " << person.name() << endl;
cout << "E-mail: " << person.email() << endl;
妳可以向消息格式中加入新的字段,这样并不会打破后向兼容性;旧的程序会在解析时直接忽略掉新的字段。所以,如果妳的通信协议中使用 protocol buffers 来表示数据格式的话,那么,妳可以放心地扩展自己的协议,无需担心影响到已有的代码。
在 应用编程接口参考小节 ,可找到一份完整的参考手册,说明的是,如何使用生成的protocol buffer 代码 。另外,在 Protocol Buffer编码 ,可找到更多关于protocol buffer 消息如何被编码的信息。
对于将结构化数据序列化这个任务,Protocol buffers相对于XML有狠多优点。Protocol buffers:
•.更简单
•. 在尺寸上小3到10倍
•.速度上快20到100倍
•.歧义更少
•.生成数据访问类,更易于在程序代码中使用
例如, 妳想表达一个人儿( person ),它有名字( name )和邮箱( email )。 在 XML 中,需要这样做:
<person>
<name>John Doe</name>
<email>jdoe@example.com</email>
</person>
而对应的 protocol buffer消息( 以 protocol buffer 文本格式 表示) 则是:
# 对一个protocol buffer 的文本表示。
# 这 并不是 将要在传输信道中使用的二进制格式。
person {
name: "John Doe"
email: "jdoe@example.com"
}
当这个消息 被编码为 protocol buffer 二进制格式 ( 上面展示的文本格式只是 一种方便 的人眼可读的格式,用于调试及编辑 )之后 ,大约 会是 28 个字节的长度,并且需要约 100 ~ 200 纳秒来进行解析。 对应的 XML版本 ,在去掉空白字符的情况下,最少为 69 个字节的长度,需要 约 5000 ~ 10000 纳秒来解析。
同时,对一个protocol buffer 进行操作也简单得多:
cout << "Name: " << person.name() << endl;
cout << "E-mail: " << person.email() << endl;
而对于XML呢,妳可能需要写些这样的代码:
cout << "Name: "
<< person.getElementsByTagName( "name" )->item( 0 )->innerText()
<< endl;
cout << "E-mail: "
<< person.getElementsByTagName( "email" )->item( 0 )->innerText()
<< endl;
然而 , protocol buffers 并非在所有方面都比 XML 要强——例如, protocol buffers 不适合于用来表示 带标记的文本文档 (例如HTML) ,因为,妳无法轻易地将结构与文本交错在一起。另外 , XML 是人眼可读的,也是人类可编辑的; protocol buffers ,最少其原始格式,不具有此特点。另外 , XML—— 在某种程度上——是自解释的。对于 protocol buffer 呢,只有在妳拥有其消息定义( .proto 文件)的情况下才有意义。
下载软件 包 ——其中包含 了针对Java 、 Python 和 C++的protocol buffer 编译器的完整代码,以及, 在I/O 和测试中所需要的那些类 的代码 。 要构建及安装妳的编译器,则按照README 中的指示来操作。
当妳准备完毕之后,试着按照 妳所选择的语言的 教程 来学习—— 它会指引妳创建一个使用protocol buffers 实现的简单应用程序。
我们 最新的版本 3 基本测试 版 ,引入了一个新的语言版本—— Protocol Buffers语言版本3( 也被称作 proto3) , 也在已有的语言版本( 也被称作 proto2)中引入了一些新特性。 Proto3简化 了 protocol buffer语言 ,提升 了易用性,并且 ,支持更多 的编程语言: 我们当前的测试版本,在 带有某些限制 的情况下, 可以生成Java 、 C++ 、 Python 、 JavaNano 和 Ruby 的代码。另外 , 妳还可以使用最新的Go protoc 插件来生成针对Go 的proto3 代码,该插件可在 golang/protobuf Github 仓库获取。 我们还在开发支持更多的语言。
我们目前只建议在以下情况下尝试proto3:
•. 妳想要在我们支持的某种新语言中试用protocol buffers。
•. 妳想要试用我们的新的开源 RPC实现 gRPC (目前 也是测试版本 )—— 我们建议对于所有 新的gRPC 服务器和客户端使用 proto3 ,以避免发生兼容性问题。
注意,这两个语言版本的应用编程接口并不是完全兼容的。为了避免给已有的用户造成不便,我们会在新的protocol buffers 版本中继续支持之前的语言版本。
妳可以在 发布说明 查看它与当前默认版本之间的主要差异,并且 在 Proto3语言指南 学习更多关于proto3 的语法。 狠快将会有 proto3 的完整文档了!
(如果proto2 和 proto3 这两个名字让妳感到困惑的话,在此解释一下, 当我们开始给protocol buffers 开源时,它实际上是Google 内部使用的该语言的 第二 个 版本——也被称作proto2。 也是因为这个原因, 我们的开源版本号从v2.0.0 开始 ) 。
Protocol buffers最初是Google 内部开发的,用来实现一个索引服务器的请求/响应协议。在开发protocol buffers之前,也有一个处理请求和响应的格式,那个格式中是手动对请求和响应进行编码及解码的,并且那个格式中要支持该协议的多个版本。于是,就产生了狠丑的代码,例如:
if (version == 3 ) {
...
} else if (version > 4 ) {
if (version == 5 ) {
...
}
...
}
这种显式格式化的协议,也增加了部署新版本协议的复杂度,因为,开发者必须先确认,在发起请求的服务器与实际处理请求的服务器之间的所有服务器都理解该新版协议,然后才能打开某个开关以使用新版协议。
Protocol buffers被设计于用来解决以下问题:
•.可以轻易地引入新的字段,而那些不需要解析该数据的中间服务器呢,可以轻易地解析它,并且中转该数据而无需理解所有的字段。
•.格式带有一定的自解释特性,并且可以被多种语言(C++、Java等等)所处理。
然而,用户仍然需要手写自己的解析代码。
随着这个系统的进化,它拥有了一些其它的特性及用途:
•.自动生成的序列化和解序列化代码,避免了手动解析数据包。
•. 除了用于短周期的远程进程调用(RPC (Remote Procedure Call))请求之外,人们还开始将protocol buffers作用一个存储持久(例如,存储于Bigtable中)数据的便利的自解释格式。
•.服务器RPC接口开始被声明为协议文件的一部分,在这种用法中,协议编译器生成根类,然后,用户使用实际的实现来覆盖它们,以形成该服务器的接口。
Protocol buffers现在 是 Google 的数据交换的 通用 语—— 在撰写本文的时刻, 在 Google 的代码树中有 12183 个 .proto 文件,定义了 48162 个不同的消息类型。 它们被用于 RPC系统 ,以及用于 在不同的存储系统中存储持久数据。
https://twitter.com/Mk05Happy/status/620063196389322752/photo/1
未知美人
高跟美女模特Sara
Your opinionsHxLauncher: Launch Android applications by voice commands