本文介绍.proto文件的编码风格。遵循下面的惯例,可以使你的protocol buffer消息定义和它们对应的类连贯且已读。

注意,protocol buffer风格随时间变化一直在进步,所以可能你会在写成的.proto文件看到不同的惯例或风格。在你修改这些文件时请考虑已有风格连贯是关键。然而在创建新的.proto文件时,最好是采用目前最流行的风格。

标准文件格式

  • 每行最多80个字母。
  • 缩进使用2个空格。

文件结构

文件命名应该使用lower_snake_case.proto格式。

所有的文件都应该最受下列方式:

  1. 许可头(如果有的话)
  2. 文件概览
  3. 语法
  4. 导入项(排序后的)
  5. 文件选项
  6. 剩下的

包名称应该小写,并且应该与目录层次结构相对应。例如,如果文件在my/package/中,那么包名应该是my.package

消息和字段名称

使用驼峰(首字母大写)命名消息名称 – 例如,SongServerRequest。使用下划线连接命名字段名(包括oneof字段和扩展名称) – 例如,song_name

message SongServerRequest {
    string song_name = 1;
}

字段使用命名规范会生成如下格式的访问器:

const string& song_name() { ... }
void set_song_name(const string& x) { ... }
public String getSongName() { ... }
public Builder setSongName(String v) { ... }

如果你的字段名称包含数字,那数字应该紧在最后一个字母后面而不是下划线,例如,要用song_name1而不是song_name_1

重复字段

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

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

枚举

使用驼峰(首字母大写)命名枚举类型,使用大写加下划线命名变量名称:

enum Foo {
  FOO_UNSPECIFIED = 0;
  FOO_FIRST_VALUE = 1;
  FOO_SECOND_VALUE = 2;
}

每个枚举变量都应该使用分号结束,而不是逗号。使用前缀枚举值,不用闭包消息包围。0值得枚举值应该有UNSPECIFIED后缀。

服务

.proto中定义RPC服务,对于服务名称和RPC方法名称,你应该使用驼峰(首字母大写)命名。

service FooService {
  rpc GetSomething(FooRequest) returns (FooResponse);
}

要避免的事

  • Required字段(仅针对proto2,应为proto3从语法层面取消了required)
  • Groups(仅针对proto2)

声明:本作品采用署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)进行许可,使用时请注明出处。
Author: mengbin92
Github: mengbin92
cnblogs: 恋水无意