Proto3：风格

Posted 2021-03-14 lianshuiwuyi

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

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

标准文件格式

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

文件结构

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

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

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

包

包名称应该小写，并且应该与目录层次结构相对应。例如，如果文件在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）