样式指南

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

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

标准文件格式

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

文件结构

文件应命名lower_snake_case.proto

所有文件应按以下方式排版：

  1. 许可标头（如果适用）
  2. 文件总览
  3. 句法
  4. 包
  5. 导入（分类）
  6. 文件选项
  7. 其他一切

包

软件包名称应为小写，并且应与目录层次结构相对应。例如，如果文件在其中my/package/，则软件包名称应为my.package。

消息和字段名称

将CamelCase（带有初始大写）用于消息名称 - 例如，SongServerRequest。 将underscore_separated_names用于字段名称 - 例如，song_name。

  1. message SongServerRequest {
  2.   required string song_name = 1;
  3. }

对字段名称使用此命名约定可为您提供以下访问器：

  1. C++:
  2.   const string& song_name() { ... }
  3.   void set_song_name(const string& x) { ... }
  5. Java:
  6.   public String getSongName() { ... }
  7.   public Builder setSongName(String v) { ... }

如果您的字段名称包含数字，则该数字应出现在字母之后而不是下划线之后。例如，使用song_name1代替song_name_1

重复的字段

对重复的字段使用复数名称。

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

枚举

对于枚举类型名称使用CamelCase（带有初始大写），对值名称使用CAPITALS_WITH_UNDERSCORES：

  1. enum Foo {
  2.   FIRST_VALUE = 0;
  3.   SECOND_VALUE = 1;
  4. }

每个枚举值应以分号结束，而不是逗号。

服务

如果.proto定义了RPC服务，则应该对服务名称和任何RPC方法名称使用CamelCase（带有初始大写）：

  1. service FooService {
  2.   rpc GetSomething(FooRequest) returns (FooResponse);
  3. }

避免的事情

  • 必填字段（仅适用于proto2）
  • 组（仅适用于proto2）