本文档提供.proto
文件的样式指南。通过遵循这些约定,将使protocol buffers
消息定义及其相应的类保持一致且易于阅读。
请注意,protocol buffers
样式随着时间的推移而发展,因此可能会看到以不同约定或样式编写的.proto
文件。修改这些文件时请尊重现有样式,一致性是关键。但是,在创建新的.proto
文件时,最好采用当前最佳样式。
文件应命名为lower_snake_case.proto
(小蛇式)
文件或变量命令方式:
- 大驼峰式:
CamelCase
- 小驼峰式:
camelCase
- 大蛇式:
GET_USER_NAME
- 小蛇式:
get_user_name
- 烤肉串式:
get-user-name
按照以下方式排序所有文件:
包名称应为小写,并且应与目录层次结构相对应。例如,如果文件在my/package/
中,那么包名应该是my.package
。
将CamelCase
(带有初始大写)用于消息名称。例如,SongServerRequest
。
将underscore_separated_names
用于字段名称(包括oneof
字段和扩展名称)。例如,song_name
。
message SongServerRequest {
required 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
字段使用复数名称。
repeated string keys = 1;
...
repeated MyMessage accounts = 17;
对于枚举类型名称使用CamelCase
(带有初始大写),对值名称使用CAPITALS_WITH_UNDERSCORES
(大蛇式):
enum Foo {
FOO_UNSPECIFIED = 0;
FOO_FIRST_VALUE = 1;
FOO_SECOND_VALUE = 2;
}
每个枚举值应以分号结束,而不是逗号。更喜欢为枚举值添加前缀,而不是将其包围在封闭消息中。零值枚举应具有后缀UNSPECIFIED
(缺省)。
如果.proto
定义了RPC服务,则应该对服务名称和任何RPC方法名称使用CamelCase
(带有初始大写):
service FooService {
rpc GetSomething(FooRequest) returns (FooResponse);
}