Protobuf简介

普罗托布夫到底是什么?

议定书缓冲作为Protobuf 缩写。谷歌创造了它 作为一种数据描述语言。界定一种轻量级和高效构建的数据储存格式,它于2008年首次开放。可使用 Protobuf 构建数据字符串结构 。或者说 序列化 。它非常适合网络通信中的数据载体。它适合于数据储存和RPC数据交换格式。它包含少量数据,以K-V格式排序并保存下来。这和消息的版本很相容可用于通信协议和数据储存等领域的语言与平台一样不重要,同步数据类型可以缩放。开发者可以利用普罗托布夫(Protobuf)附加工具构建代码,并履行结构化数据排序功能。

信息是普罗托布夫语中最基本的数据单位,其结构与戈语相似,基本数据类型的成员可以嵌入信息或其他基本数据类型。

此程序将解释如何以协议缓存语言设计您的协议缓冲数据, 包括 .proto语法和如何发布内容.proto该课程在其Proto3版本中使用了《议定书》缓冲语言,用于生成数据的文档存取。

定义Message

让我们从一个基本例子开始:当您为搜索请求构建信息时,每次搜索请求都包含一个搜索短语, 返回页面上的结果, 以及设定的结果大小 。.proto文件中定义如下：

• .proto文件的第一行具体说明其预期用途。proto3语法: 如果协议缓冲汇编器未默认使用,proto2他必须是文件非解释性一行的第一行。
• SearchRequest规格有三个字段(名称/价值键对),每个字段都有自己的名称和类型。

指定字段类型

上面的例子中，在所有字段中,有两种整数类型(页数和结果_per_page)和一种文字类型(查询)。但是,您可以为字段定义一个复合类型。另一个组织者(_A)

指定字段编号

在信息定义中,为每个字段指定一个独有的编号。这些数字用于识别您创建的二进制消息中的字段。您的信息类型已被使用后, 它不应改变这些值 。当编码成二进制信件时, 字段 1-15 将使用一个字节 。16-2047年,将需要两个字节。因此,在信息的一些最常见的用途中,总是从第一个 1-15 字段编号开始 。

可以指定的最小数字是 1 。2E29-1(536,870,911)是最大的。其中19,00至199年为实地号码,供议定书缓冲使用,以便作出保留。无法关闭临时文件夹:%s。此外,您不得使用或保留任何在目前电文规格中已经使用或保留过的字段编号。

定义字段的规则

信息框必须遵守下列准则:

• 单项: 遵守单一规则的字段,结构完善的电文(编码电文)可包括0或1字段(但不超过)。这是 proto3 语法的默认字段规则 。这有点难以理解例如,上述三个实例是单型字段。在编码信件中,可能有零或查询字段。但不会有多个。）
• 重复: 遵循重复规则的字段在电文重量中可以具有任何数个字段值,而在电文重量中这些数值的顺序可以维持(即数组类型字段)

添加更多消息类型

在单个.proto文件可能指定一个以上的电文, 这将有助于创建多个相关电文。 例如, 我们定义它 。SearchRequest回应中反应的讯息SearchResponse,把它加到之前的.proto文件中。

添加注释

.proto文档中的笔记与 C, C++, 使用/ 和.. 我不知道你指的是什么。

保留字段

当您在信件中删除字段或对字段进行批注时,其他未来开发者可以在更改信件定义时重新编号上一个字段。如果他们无意地将其放在旧版本中,他们将能够重新编号。.proto文件将造成重大困难,如数据丢失、个人信息的披露等等。避免问题的一种办法是申报保留字段的数量和字段名称。如果今后使用这些字段标记,则协议缓冲器(即协议缓冲器)的汇编者将被混淆。

什么样的代码会产生原生?

当使用协议缓冲汇编器编辑时.proto汇编器将视文档时您是否在场而定。.proto给定编程语言的代码由文件中描述的信件类型创建。 生成的代码包括读取和设置字段值, 格式化信件类型到输出流, 从输入流中解析信件等等 。

• ForC++, the compiler generates a.hand.ccfile from each.proto, with a class for each message type described in your file.
• ForJava, the compiler generates a.javafile with a class for each message type, as well as a specialBuilderclasses for creating message class instances.
• Pythonis a little different – the Python compiler generates a module with a static descriptor of each message type in your.proto, which is then used with ametaclassto create the necessary Python data access class at runtime.
• ForGo, the compiler generates a.pb.gofile with a type for each message type in your file.
• ForRuby, the compiler generates a.rbfile with a Ruby module containing your message types.
• ForObjective-C, the compiler generates apbobjc.handpbobjc.mfile from each.proto, with a class for each message type described in your file.
• ForC#, the compiler generates a.csfile from each.proto, with a class for each message type described in your file.
• ForDart, the compiler generates a.pb.dartfile with a class for each message type in your file.

标量类型

我不知道您的意思。 Proto type notes C+ type Java type Python type [2] 转到 type ruby type C# type PHP type Dart type 。 Proto Type notes C+ Type Java type Python type [2] 转到 type ruby type C# type PHP type datt type负数编码是浪费的; 如果您的字段可能包含负值, 请避免编码它们 。请使用 Sint32 代替 。ixnum 或 Bignum(视需要) Int整整 It64 使用可变长度编码负数编码是浪费的; 如果您的字段可能包含负值, 请避免编码它们 。请使用 Sint64 代替 。Int64、int64和Bignum长整数/字符串[5] 采用可变长度编码,Int64和Sint32也是如此。签名的int值。它们比标准 It32 在编码负整数方面表现更好。Int32 int int 32 Fixnum 或 Bignum (如有必要) int Sint64 使用 Int32 int int int Int 32 fixnum 或 Bignum (如果必要) int整数 。签名的int值。它们比标准整数64在编码负整数方面表现更好。内图64如果在大多数情况下价值大于228,它比昆特32效率更高。调如果数字通常大于256,sfixed64 设置且不能超过232。弦弦 弦弦 | string | ByteString | str | []byte | String (ASCII-8BIT) | ByteString | string | List |

默认值

当编码信息正文中没有单字段时,相应的字段被设置为消息描述中字段的默认值。默认值因类型而异:

• 字符串的默认值为空字符串。
• 字节的默认值为空字节 。
• 布尔斯的默认值为假 。
• 数字类型的默认值为 0 。
• 查点的默认值是第一个宣布的数值,该数值必须是零。
• 信息字段未设定。 其精确值由语言决定。 详情请参见代码生成指南 。

枚举类型

在创建信件类型时,您可能希望一个字段在既定的值列表中只有一个值。例如,假设您想对其中的每个值都这样做。SearchRequest添加corpus字段，其中corpus它们可以是通用的、WW、IMAGES、LOCAL、WIS、PRODUCTS或VIDEO。 仅仅通过在信息描述中添加一个示例和每个潜在数字值的常数来实现这一点。

我们在下面的例子中增加了一个名字。Corpus的枚举类型，和一个Corpus类型的字段：

如你所见，Corpus查点的初始常数地图达到0:所有查点定义必须包含以0为常数地图作为定义的第一行,因为:

• 因为必须有零, 我们可以用零作为计数的默认值 。
• 要与 0 值保持一致,原数2 语法第一行的列表值总是默认值,必须是规格的第一行。

使用不同的电文类型。

如果您想要使用每个信件类型, 您可以使用它作为字段类型 。SearchResponse消息中携带类型为Result的消息，

你可以在同一个.proto文件中定义一个Result消息类型，然后在SearchResponse中指定一个Result类型的字段。

导入消息定义

在上面的示例中，Result消息类型在与SearchResponse同一文件定义 - 如果消息类型已经在另一个文件中用作字段类型 。.proto我们应当根据文件的指示做些什么?

您可以导入其它的. Proto 定义, 用于原型 。 要导入另一个 。 Proto 定义, 在文档首端添加一个导入语句 :

您只能默认使用直接输入的数据 。.proto尽管如此,有时你需要修订文件中的定义。.proto您无法删除文件夹:%s:没有此文件夹。但是,您可以在旧点放置虚拟文件夹。.proto文件，在文件中使用import public语法不是直接转让,而是将所有进口品转至新的地方。.proto更改后组织所有调用点并存档 。import public语句的proto例如,有档案的人可以传达依赖进口公共附属物的情况。

命令行参数将发送到编译器 。-I或者--proto-path查看所选文件夹 。.proto文件在目录中进行搜索,如果汇编者没有获得汇编者,则在目录中要求汇编者提供这些文件。--proto-path。对于所有导入,将数值设置为项目根目录,并适当指定名称。

使用 proto2 的邮件格式

您可以将 proto2 信件类型导入到 proto3 信件类型, 但无法将 proto3 信件类型导入到 proto2 信件类型 。 尽管如此, proto2 列表类型不能直接应用于 proto3 词汇 。

嵌套消息类型

如以下示例所示,可在其他各类电文中界定和使用电文类型:Result消息被定义在SearchResponse消息中

如果您想使用父母在信息中声明的孩子信息,请在外部使用。Parent.Type引用他们

任何信息层都可以嵌入 。

更新Message

如果现有类型的信件不再适合您当前的需求(例如,如果您想要在信件中添加一个额外字段),但您仍然想要使用由上一个版本的信件格式创建的代码,您可以。不用担心！记住以下规则信息定义可以很容易地更新,而不会破坏当前代码。

• 当前字段的字段编号不应更改 。
• 如果添加了新字段，使用旧信件格式版本创建的任何代码都会排序 。无法删除文件夹“{0}”。记住这些组件的默认值, 这些新生成的代码, 与由序列旧代码生成的信息适当互动 。类似的，新代码生成的信息也可能被旧版本所理解:在解析时,旧版本(二进制)只是忽略了新字段。详情见下文关于未知领域的一节。
• 只要未在修改后的信件类型中重新编号, 此字段就可以删除。 您也可以通过添加它来杀死名称部分 。OBSOLETE_前缀或按需要设置字段编号 。reserved这样可以确保未来的用户不会无意地对字段重新编号。

未知字段

未知字段是用于协议缓冲的、重新提供字段无法被分析员识别的协议缓冲的、格式清晰的序列数据。例如,当旧的二进制文件解释由新二进制文件以新字段发送的数据时,这些新字段在旧的二进制文件中成为未知字段。

最初,原型3信息在解析期间总是从未知字段丢失,但只在版本3中丢失,在版本3中,我们在版本5中重新引入了未知字段保留,以匹配原型2行为。在版本5和更高版本中,未知字段在解析期间被保存,并包含在序列输出中。

映射类型

协议缓冲为创建作为信件定义一部分的地图提供了直截了当的语法 。

key_type您可以是整数或字符串(浮动点和字节除外)。enum不是一个有效的key_type。value_type它可以是除制图以外的任何形式(协议缓冲介质不允许有混凝土地图)。

例如,如果你想绘制地图命名项目,Project信件与字符串密钥链接,可定义如下:

• 地图中的字段不能是结果模式(即,数组不能是地图中字段的价值)。
• 因为地图中的值是随机的, 它们无法受地图碎片顺序的影响 。
• 生成。 在处理本方案内容后, 进行地图密钥排序。 数字密钥按数字排序 。
• 当解析或合并一行时,如果有重复的地图密钥,则使用最后一个可见密钥。如果有重复的密钥,则在从文本格式解码地图时可能会失败 。
• 如果没有为绘图字段提供值,则字段排序时的行为取决于语言。在 C++ 中, Java 和 Python 的字段类型的默认值按字段值排序,尽管它们不是以其他语言排序的。

给消息取个名字

你可以在.proto包含可选文件 。package在信件类型之前避免名称冲突的 Amort

当定义信件字段时,请使用下面显示的软件包名称。

Cardage对生成代码的影响由编程语言决定。

定义服务

如果您想要使用 RPC (远程进程呼叫) 机制的信息类型, 您可以这样做 。 .proto文件宣布 RPC 服务界面, 协议缓冲汇编器将用您选择的编程语言建立服务界面代码和条块, 之后您可以定义一个服务, 并接受其中的一种方法 。SearchRequest消息返回SearchResponse消息，你可以在.proto该文件如何界定定义如下:

使用协议缓冲的最基本的RPC系统是gRPC谷歌的开放源码RPC系统, 语言和平台不可知性。gRPC专门设计用于协议缓冲并允许您使用协议缓冲编辑器插件.proto文件创建适当的 RPC 代码 。

如果你不想使用gRPC您可使用自己的 RPC 系统,有关如何创建 RPC 系统的更多信息,请访问 Proto2 语言手册。

JSON编解码

Proto3支持标准 JSON 编码,使各系统之间的数据交流更加容易。 编码标准在下表中按类型列出。

如果在 JSON 编码数据中缺少值,或者,它是无效的。这是我第一次 能够解决这个问题。它将作为等值默认值处理。如果协议缓冲中的字段有默认值,为了减少空间,该字段默认地被排除在JSON编码数据之外。在 JSON 代码输出中保留默认值的字段,以此为取代默认值的选项准备解码。

| proto3 | JSON | JSON example | Notes | | :--------------------- | :------------ | :--------------------------------------- | :----------------------------------------------------------- | | message | object |{"fooBar": v, "g": null,…}生成 JSON 对象。 将信件字段名称转换为小数, 并成为 JSON 对象密钥 。json_name提供的值在字段选项中用作一个密钥。 分析器接受小行的名称( 或由) 。json_name)以及原原字段名称null是所有字段类型的有效值,也是对应字段类型的默认值。字符串 enum"FOO_BAR"使用在 proto 中提供的列表值的名称。 分析器接受模拟名称和整数值。 对象映射图{"k": v, …}每个键都将转换为字符串 。[v, …]无效名将被空列表替换 。true, false| | | string | string |"Hello World!"| | | bytes | base64 string |"YWJjMTIzIT8kKiYoKSctPUB+"JSON 值将是使用填满的标准基准64 代码编码为字符串的数据。 接受有/ 没有填充的标准以及 URL safebase64 代码 。 编号 2, int32, fix32, int321, -10, 0| JSON value will be a decimal number. Either numbers or strings are accepted. | | int64, fixed64, uint64 | string |"1", "-10"| JSON value will be a decimal string. Either numbers or strings are accepted. | | float, double | number |1.1, -10.0, 0, "NaN","Infinity"| JSON value will be a number or one of the special string values "NaN", "Infinity", and "-Infinity". Either numbers or strings are accepted. Exponent notation is also accepted. | | Any |object|{"@type": "url", "f": v, … }| If the Any contains a value that has a special JSON mapping, it will be converted as follows:{"@type": xxx, "value": yyy}. Otherwise, the value will be converted into a JSON object, and the"@type"field will be inserted to indicate the actual data type. | | Timestamp | string |"1972-01-01T10:00:20.021Z"| Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. | | Duration | string |"1.000340012s", "1s"| Generated output always contains 0, 3, 6, or 9 fractional digits, depending on required precision, followed by the suffix "s". Accepted are any fractional digits (also none) as long as they fit into nano-seconds precision and the suffix "s" is required. | | Struct |object|{ … }| Any JSON object. Seestruct.proto. | | Wrapper types | various types |2, "2", "foo", true,"true", null, 0, …| Wrappers use the same representation in JSON as the wrapped primitive type, except thatnullis allowed and preserved during data conversion and transfer. | | FieldMask | string |"f.fooBar,h"| Seefield_mask.proto. | | ListValue | array |[foo, bar, …]| | | Value | value | | Any JSON value | | NullValue | null | | JSON null | | Empty | object | {} | An empty JSON object |

生成代码

您必须使用代码生成器生成 Java、 Python、 C++、 Go、 Ruby、 目标C 或 C# 代码 。.proto文件中指定的信息类型。 您必须...proto启动协议缓冲汇编程序 。protoc。如果您尚未安装编译器,请下载软件包, 并遵循 README 文件的指示 。对于Go，还需要为编译者安装一个特定的代码生成器插件,可以在GitHub的Golongg/Protobuf项目中找到并安装。

以下列方式提出了汇编者:

• IMPORT_PATH指定了在解析import命令时去哪里搜索.proto如果文件被忽略, 将在当前工作目录中搜索, 并可能多次传递 。--proto-path多个导入文件夹可以指定为参数, 汇编者将按指定的顺序搜索它们 。-I=IMPORT_PATH是--proto_path的简短形式。
• 您可以提供一个或多个输出命令 :
• --cpp_outgenerates C++ code inDST_DIR. See the C++ generated code reference for more.
• --java_outgenerates Java code inDST_DIR. See the Java generated code reference for more.
• --python_outgenerates Python code inDST_DIR. See the Python generated code reference for more.
• --go_outgenerates Go code inDST_DIR. See the Go generated code reference for more.
• --ruby_outgenerates Ruby code inDST_DIR. Ruby generated code reference is coming soon!
• --objc_outgenerates Objective-C code inDST_DIR. See the Objective-C generated code reference for more.
• --csharp_outgenerates C# code inDST_DIR. See the C# generated code reference for more.
• --php_outgenerates PHP code inDST_DIR. See the PHP generated code reference for more.
• 虽然文档是相对于当前目录命名的, 但每个文件必须存在于其中的 IMPORT_ PATH 中, 这样编纂者才能识别其指定名称 。 Proto 文件 。 您可以一次指定多个文件 。 Proto 文件 。 虽然一个文档是相对于当前目录命名的, 但每个文件必须存在于其中的 IMPORT_ PATH 中, 以便编纂者能够确定其指定名称 。