风格指南

提供有关如何最佳地构建 proto 定义的方向。

本文档提供了一个 .proto 文件的风格指南。通过遵循这些约定,您将使您的协议缓冲区消息定义及其相应的类保持一致且易于阅读。

请注意,协议缓冲区的风格随着时间的推移而发展,因此您可能会看到以不同约定或风格编写的 .proto 文件。当您修改这些文件时,**请尊重现有风格**。**一致性是关键**。但是,当您创建新的 .proto 文件时,最好采用当前的最佳风格。

标准文件格式

  • 将行长保持在 80 个字符。
  • 使用 2 个空格缩进。
  • 更喜欢对字符串使用双引号。

文件结构

文件应命名为 lower_snake_case.proto

所有文件都应按以下方式排序

  1. 许可证标题(如果适用)
  2. 文件概述
  3. 语法
  4. 导入(排序)
  5. 文件选项
  6. 其他所有内容

包名称应为小写。包名称应基于项目名称具有唯一名称,并且可能基于包含协议缓冲区类型定义的文件的路径。

消息和字段名称

对消息名称使用 PascalCase(以大写字母开头):SongServerRequest。更喜欢将缩写大写为单个单词:GetDnsRequest 而不是 GetDNSRequest。对字段名称使用 lower_snake_case,包括 oneof 字段和扩展名:song_name

message SongServerRequest {
  optional string song_name = 1;
}

使用此字段名称命名约定,您可以访问如下所示的两个代码示例中的访问器。

C++

const string& song_name() { ... }
void set_song_name(const string& x) { ... }

Java

public String getSongName() { ... }
public Builder setSongName(String v) { ... }

如果您的字段名称包含数字,则数字应出现在字母之后而不是下划线之后。例如,使用 song_name1 而不是 song_name_1

重复字段

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

repeated string keys = 1;
  ...
  repeated MyMessage accounts = 17;

枚举

对枚举类型名称使用 PascalCase(以大写字母开头),对值名称使用 CAPITALS_WITH_UNDERSCORES

enum FooBar {
  FOO_BAR_UNSPECIFIED = 0;
  FOO_BAR_FIRST_VALUE = 1;
  FOO_BAR_SECOND_VALUE = 2;
}

每个枚举值都应以分号结尾,而不是逗号。更喜欢对枚举值进行前缀而不是将它们包含在封闭消息中。由于某些语言不支持在“结构”类型内部定义枚举,因此这可确保跨绑定语言采用一致的方法。

零值枚举应后缀为 UNSPECIFIED,因为收到意外枚举值的服务器或应用程序将在 proto 实例中将该字段标记为未设置。然后,字段访问器将返回默认值,对于枚举字段,该值为第一个枚举值。有关未指定枚举值的更多信息,请参阅Proto 最佳实践页面

服务

如果您的 .proto 定义了 RPC 服务,则应对服务名称和任何 RPC 方法名称都使用 PascalCase(以大写字母开头)

service FooService {
  rpc GetSomething(GetSomethingRequest) returns (GetSomethingResponse);
  rpc ListSomething(ListSomethingRequest) returns (ListSomethingResponse);
}

有关更多与服务相关的指南,请参阅 API 最佳实践主题中的为每个方法创建唯一的 Proto不要在顶级请求或响应 Proto 中包含基本类型,以及 Proto 最佳实践中的在单独的文件中定义消息

需要避免的事项

  • 必需字段(仅适用于 proto2)
  • 组(仅适用于 proto2)