03-样式指南

本文档提供.proto文件的样式指南。通过遵循这些约定,将使protocol buffers消息定义及其相应的类保持一致且易于阅读。

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

0.1. 标准文件格式

  • 保持行长度为80个字符。
  • 使用2个空格的缩进。

0.2. 文件结构

文件应命名为lower_snake_case.proto(小蛇式)

文件或变量命令方式:

  • 大驼峰式:CamelCase
  • 小驼峰式:camelCase
  • 大蛇式:GET_USER_NAME
  • 小蛇式:get_user_name
  • 烤肉串式:get-user-name

按照以下方式排序所有文件:

  1. 许可证标题(如果适用)
  2. 文件概述
  3. 句法(syntax)
  4. 包(package)
  5. 导入(分类,import)
  6. 文件选项
  7. 其他

0.3. 包

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

0.4. 消息和字段名称

  • 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

0.5. Repeated 字段

repeated字段使用复数名称。

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

0.6. 枚举

对于枚举类型名称使用CamelCase(带有初始大写),对值名称使用CAPITALS_WITH_UNDERSCORES(大蛇式):

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

每个枚举值应以分号结束,而不是逗号。更喜欢为枚举值添加前缀,而不是将其包围在封闭消息中。零值枚举应具有后缀UNSPECIFIED(缺省)。

0.7. Servies(服务)

如果.proto定义了RPC服务,则应该对服务名称和任何RPC方法名称使用CamelCase(带有初始大写):

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

0.8. 要避免的事情

  • Required字段(仅适用于proto2)
  • Groups(仅适用于proto2)
上次修改: 14 April 2020