gRPC-Protocol语法指南 (6)

在C#中,除非转换为.proto文件中明确提供选项csharp_namespace,否则在转换为PascalCase之后,该程序包将用作命名空间。例如,Open将位于命名空间Foo.Bar中。

软件包和名称解析

协议缓冲语言中的类型名称解析类似于C ++:首先搜索最里面的作用域,然后搜索最里面的作用域,依此类推,每个包都被视为其父包“内部”。领先的“。” (例如.foo.bar.Baz)表示从最外面的范围开始。

协议缓冲区编译器通过解析导入的.proto文件来解析所有类型名称。每种语言的代码生成器都知道如何引用该语言中的每种类型,即使它具有不同的范围规则。

Defining Services

如果要将消息类型与RPC(远程过程调用)系统一起使用,则可以在.proto文件中定义RPC服务接口,并且协议缓冲区编译器将以您选择的语言生成服务接口代码和存根。 因此,例如,如果要使用接收SearchRequest并返回SearchResponse的方法来定义RPC服务,则可以在.proto文件中对其进行定义,如下所示:

service SearchService { rpc Search(SearchRequest) returns (SearchResponse); }

与协议缓冲区一起使用的最直接的RPC系统是gRPC:这是Google开发的与语言和平台无关的开源RPC系统。 gRPC与协议缓冲区配合使用特别好,并允许您使用特殊的协议缓冲区编译器插件直接从.proto文件生成相关的RPC代码。

如果您不想使用gRPC,也可以在自己的RPC实现中使用协议缓冲区。 您可以在《 Proto2语言指南》中找到有关此内容的更多信息。

还有许多正在进行的第三方项目正在为协议缓冲区开发RPC实现。 有关我们知道的项目的链接列表,请参见第三方加载项Wiki页面。

JSON Mapping

Proto3支持JSON中的规范编码,从而使在系统之间共享数据更加容易。 下表按类型对编码进行了描述。

如果JSON编码的数据中缺少某个值,或者该值为null,则在解析为协议缓冲区时,它将被解释为适当的默认值。 如果字段在协议缓冲区中具有默认值,则默认情况下会在JSON编码数据中将其省略以节省空间。 一个实现可以提供选项,以在JSON编码的输出中发出具有默认值的字段。

gRPC-Protocol语法指南

JSON options

一个proto3 JSON实现可以提供以下选项:

发出具有默认值的字段:默认情况下,proto3 JSON输出中省略具有默认值的字段。 一个实现可以提供一个选项,以使用其默认值覆盖此行为和输出字段。

忽略未知字段:默认情况下,Proto3 JSON解析器应拒绝未知字段,但可以提供在解析时忽略未知字段的选项。

使用proto字段名称代替lowerCamelCase名称:默认情况下,proto3 JSON打印机应将字段名称转换为lowerCamelCase并将其用作JSON名称。 一个实现可以提供一个选项,改为使用原型字段名称作为JSON名称。 Proto3 JSON解析器必须接受转换后的lowerCamelCase名称和原型字段名称。

将枚举值作为整数而不是字符串发送:枚举值的名称在JSON输出中默认使用。 可以提供一个选项来代替使用枚举值的数字值。

Options

.proto文件中的各个声明可以使用许多选项进行注释。 选项不会改变声明的整体含义,但可能会影响在特定上下文中处理声明的方式。 可用选项的完整列表在google / protobuf / descriptor.proto中定义。

一些选项是文件级选项,这意味着它们应在顶级范围内编写,而不是在任何消息,枚举或服务定义内。 一些选项是消息级别的选项,这意味着它们应该写在消息定义中。 一些选项是字段级选项,这意味着它们应在字段定义中编写。 选项也可以写在枚举类型,枚举值,字段,服务类型和服务方法中; 但是,目前没有针对这些功能的有用选项。

以下是一些最常用的选项:

java_package(文件选项):要用于生成的Java类的包。 如果.proto文件中未提供显式的java_package选项,则默认情况下将使用proto软件包(在.proto文件中使用“ package”关键字指定)。 但是,proto软件包通常不能作为Java包,因为proto软件包不应以反向域名开头。 如果未生成Java代码,则此选项无效。

option java_package = "com.example.foo";

java_multiple_files(文件选项):使顶级消息,枚举和服务在程序包级别定义,而不是在以.proto文件命名的外部类内部定义。

option java_multiple_files = true;

java_outer_classname(文件选项):您要生成的最外层Java类的类名(以及文件名)。 如果在.proto文件中未指定显式的java_outer_classname,则通过将.proto文件名转换为驼峰式大小写来构造类名(因此foo_bar.proto变为FooBar.java)。 如果未生成Java代码,则此选项无效。

option java_outer_classname = "Ponycopter";

内容版权声明:除非注明,否则皆为本站原创文章。

转载注明出处:https://www.heiqu.com/zwjwyp.html