Protocol Buffers 编码风格

Table of Contents

1 文件标准格式

  • 单行不超过 80 字符
  • 使用 2 空格缩进

2 文件结构

文件应该命名成这样: lower_snake_case.proto

所有的文件内容应该按照下面的顺序排列:

  1. 头部 License(如果需要的话)
  2. 文件概述
  3. Syntax
  4. Package
  5. Imports (sorted)
  6. File options
  7. 其它

3 Packages

名称小写,与目录结构相对应。比如文件路径是 my/package ,包名应该为 my.package

4 消息和字段命名

  • 消息名使用驼峰(CamelCase)且首字母大写的方式,比如 SongServerRequest
  • 字段名使用小写单词下划线分隔的方式 underscore_separated_names 包括 oneof 字段和扩展命名。如 sone_name

但实际生成的语言代码会根据语言自身常用的命名方式来。如:

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

5 重复字段(Repeated)

使用复数。

6 枚举

枚举名称使用驼峰(CamelCase)且首字母大写的方式,枚举类型使用全部大写加下划线的方式。

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

每个枚举值使用分号结尾,而不是逗号。枚举值命名包含的枚举名称应该放在最前面,而不是放在中间,零值枚举应该以 UNSPECIFIED 结束。

7 服务(Services)

如果你的 .proto 需要定义 RPC 服务,你应该使用驼峰(且首字母大写)的方式来命名服务名和 RPC 方法名。

8 应该避免的

  • Required 字段(只针对 proto2)
  • Groups(只针对 proto2)

First created: 2020-05-21 11:20:01
Last updated: 2020-05-21 Thu 15:19
Power by Emacs 26.2 (Org mode 9.1.9)