Protobuf 命名约定

Question

除了 Google 提供的相当简短的样式指南之外，以下是我对命名的想法Google Protocol Buffer 消息。

1. 在消息类型名称末尾使用“消息”。

   • 这使得在源代码中很容易看出一个类是 protobuf 生成的类。这还有一个优点，如果我有一个丰富的域特定类，那么它可以有真实的名称，比如 protobuf 类的 AddressBookMes​​sage 和真实类的 AddressBook。

2. 对于 Java 用户来说，以 Protos 结尾的 java_outer_classname 似乎是标准的。

   • 我最初没有注意到这一点，所以我当前的 protobuf 类位于 com.example.project.protobuf.MyProtos 中，但我认为没有理由将其保留在那里，因为我们需要有一个包含类，因此可以将其移动到com.example.protobuf.MyProtos，除非项目的顶级包中没有类。

3. 从 0 开始枚举以匹配 C/C++。

4. 对重复字段使用单一名称。

   • 大多数生成的方法使用单一字段名称听起来更好，即使它是重复的，例如 message->add_child()，而不是 message->add_children()（如果有重复的子字段）。

人们还使用其他标准或与这些标准不同吗？

Answer 1

免责声明：来自每天使用 protobuf 的 Google 员工的回答。我绝不以任何方式代表谷歌。

1. 不要那样做。编译的协议缓冲区只是您所使用的语言指定的类定义，并进行了一些改进。添加“消息”会显得更加冗长。通常，您只使用协议缓冲区而不使用其他类定义，即使您使用其他类定义，也只需导入 java_outer_classname 并从中做一个点。您甚至可以在代码中放入某个事物的完整路径来删除一行导入，没问题。

2. 虽然没有正式指定，但这听起来是一个很好的建议，因为通常你会在一个文件夹中放置多个原型。

3. 通常从 0 开始。请参阅协议缓冲区语言指南。

4. 您可以使用复数来表示重复的字段名称。阅读以下内容以了解使用它的一些感受：https://developers.google.com/协议缓冲区/docs/javatutorial

Answer 2

我不同意答案 4。在链接的文章中，我只能找到这样的示例：

repeated PhoneNumber phones = 4;
repeated Person people = 1;

甚至在 https://developers.google.com/protocol-buffers/docs/proto3 我们只找到复数：

repeated Result results = 1;
repeated string snippets = 3;

Answer 3

您要寻找的是https://cloud.google.com/apis/ design/ 讨论了 Google 自己的 API 中使用的 protobuf/gRPC 设计约定。

protobuf 风格指南 (https://developers.google.com/protocol-buffers/docs /style) 正如你所说，相当短。

Answer 4

Google 似乎在 https://developers.google.com/protocol-buffers/docs/style 同时：

对重复字段使用复数名称。

重复字符串键 = 1;
...
重复的 MyMessage 帐户 = 17；

它为 add_ 成员函数生成一个错误的函数名称：

// Bad method name.
auto* const newKey = msg.add_keys();
// OK!
auto* const anotherNewKey = msg.mutable_keys()->Add();
// OK!
auto const * const allKeys = msg.keys();
auto const& firstKeys = msg.keys(0);

有人可能会认为第一个方法无论如何都是多余的。通过使用 mutable_ 成员函数，如果将复数字段名称用于重复 字段，我不会发现任何有关难看的方法名称的问题。

因此，从现在开始我将尝试遵循这个指导方针。另一个原因：我们也倾向于在 C++ 中使用复数变量名来表示容器/集合，例如

auto keys = std::vector<std::string>{};