风格指南
本文档提供了一个 .proto
文件的风格指南。通过遵循这些约定,您将使您的协议缓冲区消息定义及其相应的类保持一致且易于阅读。
请注意,协议缓冲区的风格随着时间的推移而发展,因此您可能会看到以不同约定或风格编写的 .proto
文件。当您修改这些文件时,**请尊重现有风格**。**一致性是关键**。但是,当您创建新的 .proto
文件时,最好采用当前的最佳风格。
标准文件格式
- 将行长保持在 80 个字符。
- 使用 2 个空格缩进。
- 更喜欢对字符串使用双引号。
文件结构
文件应命名为 lower_snake_case.proto
。
所有文件都应按以下方式排序
- 许可证标题(如果适用)
- 文件概述
- 语法
- 包
- 导入(排序)
- 文件选项
- 其他所有内容
包
包名称应为小写。包名称应基于项目名称具有唯一名称,并且可能基于包含协议缓冲区类型定义的文件的路径。
消息和字段名称
对消息名称使用 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)