[翻译] ProtoBuf 官方文档(一)- 开发者指南

翻译查阅外网资料过程中遇到的比较优秀的文章和资料,一是作为技术参考以便日后查阅,二是训练英文能力。

此文翻译自 Protocol Buffers 官方文档 Developer Guide 部分

翻译为意译,不会照本宣科的字字对照翻译
以下为原文内容翻译

开发者指南

欢迎使用 protocol buffers 的开发者文档, protocol buffers 是一种语言无关、平台无关、可扩展的序列化结构数据的方法,它可用于通信协议、数据存储等。

这篇文档面向那些希望在自己的应用程序中使用 protocol buffers 的 Java、C++ 或 Python 开发者们。这篇概论(指南)将介绍 protocol buffers 并且告诉你迈出第一步所需要的工作-你之后可以学习具体的 开发教程 或更为深入的学习 protocol buffer 编码规则。同时我们为所有三种语言都提供了相应的 API 参考文档,以及编写 .proto 文件的语法和风格指南。

protocol buffers 是什么?

protocol buffers 是一种灵活,高效,自动化机制的结构数据序列化方法-可类比 XML,但是比 XML 更小、更快、更为简单。你可以定义数据的结构,然后使用特殊生成的源代码轻松的在各种数据流中使用各种语言进行编写和读取结构数据。你甚至可以更新数据结构,而不破坏根据旧数据结构编译而成并且已部署的程序。

它是如何工作的?

你可以通过在 .proto 文件中定义 protocol buffer message 类型,来指定你想如何对序列化信息进行结构化。每一个 protocol buffer message 是一个信息的小逻辑记录,包含了一系列的 name-value 对。这里有一个非常基础的 .proto 文件样例,它定义了一个包含 "person" 相关信息的 message:

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 格式很简单 - 每种 message 类型都有一个或多个具有唯一编号的字段,每个字段都有一个名称和一个值类型,其中值类型可以是数字(整数或浮点数),布尔值,字符串,原始字节,甚至(如上例所示)其它 protocol buffer message 类型,这意味着允许你分层次地构建数据。你可以指定 optional 字段,required 字段和 repeated 字段。 你可以在 Protocol Buffer 语言指南 中找到有关编写 .proto 文件的更多信息。

译者注:
proto3 已舍弃 required 字段,optional 字段也无法显示使用(因为缺省默认就设置为 optional)

一旦定义了 messages,就可以在 .proto 文件上运行 protocol buffer 编译器来生成指定语言的数据访问类。这些类为每个字段提供了简单的访问器(如 name()和 set_name()),以及将整个结构序列化为原始字节和解析原始字节的方法 - 例如,如果你选择的语言是 C++,则运行编译器上面的例子将生成一个名为 Person 的类。然后,你可以在应用程序中使用此类来填充,序列化和检索 Person 的 messages。于是你可以写一些这样的代码:

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);

之后,你可以重新读取解析你的 message

fstream input("myfile", ios::in | ios::binary);
Person person;
person.ParseFromIstream(&input);
cout << "Name: " << person.name() << endl;
cout << "E-mail: " << person.email() << endl;

你可以在 message 格式中添加新字段,而不会破坏向后兼容性;旧的二进制文件在解析时只是忽略新字段。因此,如果你的通信协议使用 protocol buffers 作为其数据格式,则可以扩展协议而无需担心破坏现有代码。
你可以在 API 参考部分 中找到使用生成的 protocol buffer 代码的完整参考,你可以在 协议缓冲区编码 中找到更多关于如何对 protocol buffer messages 进行编码的信息。

为什么不使用 XML?

对于序列化结构数据,protocol buffers 比 XML 更具优势。Protocol buffers:

  • 更简单
  • 小 3 ~ 10 倍
  • 快 20 ~ 100 倍
  • 更加清晰明确
  • 自动生成更易于以编程方式使用的数据访问类

例如,假设你想要为具有姓名和电子邮件的人建模。在XML中,你需要:

<person>
    <name>John Doe</name>
    <email>jdoe@example.com</email>
</person>

而相对应的 protocol buffer message(参见 protocol buffer 文本格式)是:

# Textual representation of a protocol buffer.
# This is *not* the binary format used on the wire.
person {
  name: "John Doe"
  email: "jdoe@example.com"
}

当此消息被编码为 protocol buffer 二进制格式 时(上面的文本格式只是为了调试和编辑的方便而用人类可读的形式表示),它可能是 28 个字节长,需要大约 100-200 纳秒来解析。如果删除空格,XML版本至少为 69 个字节,并且需要大约 5,000-10,000 纳秒才能解析。
此外,比起 XML,操作 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 在某种程度上也是自我描述的。只有拥有 message 定义(.proto文件)时,protocol buffer 才有意义。

介绍 proto3

我们最新的版本3 release ,它引入了新的语言版本 - Protocol Buffers 语言版本3(又称 proto3),并且添加了现有语言版本(又称 proto2)的一些新功能。Proto3 简化了 Protocol Buffers 语言,既易于使用,又可以在更广泛的编程语言中使用:这个版本允许你使用 Java,C ++,Python,Java Lite,Ruby,JavaScript,Objective-C 和 C# 生成 protocol buffer 代码。此外,你可以使用最新的 Go protoc 插件为 Go 生成 proto3 代码,该插件可从 github 库 golang/protobuf 获得。更多语言正在筹备中。

请注意,两种语言版本的 API 不完全兼容。为避免给现有用户带来不便,我们将继续在新版本的 protocol buffers 中支持以前的语言版本。

你可以在 发行说明 中看到与当前默认版本的主要差异,并在 Proto3 语法指引 中了解proto3 语法)。proto3 的完整文档即将推出!

(如果名称 proto2 和 proto3 看起来有点令人困惑,那是因为当我们最初开源 protocol buffers 时,它实际上是 Google 的第二个语言版本 - 也称为 proto2。这也是为什么我们的开源版本从 v2.0.0 开始)。

一点点历史

Protocol buffers 最初是在 Google 开发的,用于处理索引服务器请求/响应协议。在 protocol buffer 之前,有一种请求和响应的格式,它手动进行编组/解组,并支持许多版本的协议。这导致了一些非常丑陋的代码,例如:

 if (version == 3) {
   ...
 } else if (version > 4) {
   if (version == 5) {
     ...
   }
   ...
 }

明确格式化的协议也使新协议版本的推出变得复杂,因为开发人员必须确保请求的发起者和处理请求的实际服务器之间的所有服务器都能理解新协议,然后才能切换开关以开始使用新协议。

协议缓冲区旨在解决这些问题:

  • 可以轻松引入新字段,中间服务器不需要检查数据,可以简单地解析它并传递数据而无需了解所有字段。
  • 格式更具自我描述性,可以用各种语言处理(C ++,Java 等)

但是,用户仍然需要手写自己的解析代码。

随着系统的发展,它获得了许多其他功能和用途:

  • 自动生成的序列化和反序列化代码避免了手动解析的需要。
  • 除了用于短期 RPC(远程过程调用)请求之外,人们还开始使用 protocol buffers 作为一种方便的自描述格式,用于持久存储数据(例如在 Bigtable 中)。
  • 服务器 RPC 接口开始被声明为协议文件的一部分,protocol 编译器生成存根类,用户可以使用服务器接口的实际实现来覆盖这些类。

Protocol buffers 现在是 Google 的数据通用语言 - 在撰写本文时,Google 代码树中有 12183 个 .proto 文件,其中一共定义了 48162 种不同的 message 类型。它们既可用于 RPC 系统,也可用于各种存储系统中的数据持久存储。

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 203,271评论 5 476
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 85,275评论 2 380
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 150,151评论 0 336
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,550评论 1 273
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,553评论 5 365
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,559评论 1 281
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 37,924评论 3 395
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,580评论 0 257
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 40,826评论 1 297
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,578评论 2 320
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,661评论 1 329
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,363评论 4 318
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 38,940评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,926评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,156评论 1 259
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 42,872评论 2 349
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,391评论 2 342

推荐阅读更多精彩内容