首页 > 技术文章 > Language Guide (proto3) | proto3 语言指南(十四)选项

itheo 2021-01-13 18:18 原文

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(文件选项):如果为false,则只为该.proto文件生成一个.java文件,并且为顶级消息、服务和枚举生成的所有Java类/枚举等将嵌套在外部类中(请参见java_outer_classname)。如果为true,则将为为顶级消息、服务和枚举生成的每个Java类/枚举等生成单独的.java文件,并且为此.proto文件生成的java“外部类”将不包含任何嵌套类/枚举等。这是一个默认为false的布尔选项。如果不生成Java代码,则此选项无效。
option java_multiple_files = true;
  • optimize_for(文件选项):可以设置为SPEED, CODE_SIZE,或LITE_RUNTIME。这将以如下方式影响C++和Java代码生成器(可能还有第三方生成器):
    • SPEED(默认值):协议缓冲区编译器将生成用于序列化、解析和对消息类型执行其他常见操作的代码。这段代码是高度优化的。
    • CODE_SIZE:协议缓冲区编译器将生成最小的类,并依赖共享的、基于反射的代码来实现序列化、解析和各种其他操作。因此,生成的代码将比使用SPEED时小得多,但操作将更慢。类仍将实现与在SPEED模式下完全相同的公共API。这种模式在包含大量.proto文件的应用程序中非常有用,而且不需要所有文件都非常快。
    • LITE_RUNTIME:协议缓冲区编译器将生成仅依赖于lite运行时库(libprotobuf-lite而不是libprotobuf)的类。lite运行时比完整库要小得多(大约小一个数量级),但省略了某些特性,如描述符和反射。这对于运行在手机等受限平台上的应用程序特别有用。编译器仍然会像在速度模式下一样生成所有方法的快速实现。生成的类将只在每种语言中实现MessageLite接口,它只提供完整message接口的方法子集。
option optimize_for = CODE_SIZE;
  • cc_enable_arenas(文件选项):为C++生成的代码启用arena allocation
  • objc_class_prefix(文件选项):设置Objective-C类前缀,该前缀位于此.proto中所有Objective-C生成的类和枚举之前。没有默认值。你应该使用Apple推荐的3-5个大写字符的前缀。请注意,所有2个字母前缀都由Apple保留。
  • deprecated(文件选项):如果设置为true,则表示该字段已弃用,不应由新代码使用。在大多数语言中,这没有实际效果。在Java中,这变成了@Deprecated注释。将来,其他特定于语言的代码生成器可能会在字段的访问器上生成弃用注释,这反过来会导致在编译试图使用该字段的代码时发出警告。如果该字段没有被任何人使用,并且您想阻止新用户使用它,请考虑用reserved语句替换字段声明。
int32 old_field = 6 [deprecated = true];

自定义选项

协议缓冲区还允许您定义和使用自己的选项。这是大多数人不需要的高级功能。如果您确实认为需要创建自己的选项,请参阅Proto2语言指南了解详细信息。请注意,创建自定义选项会使用扩展,这些扩展只允许用于proto3中的自定义选项。

原文:https://www.cnblogs.com/itheo/p/14273574.html

作者:Theo·Chan
版权:本文版权归作者和博客园共有
转载:欢迎转载,但未经作者同意,必须保留此段声明;必须在文章中给出原文连接;否则必究法律责任

推荐阅读