Style Guide 代码风格

Style Guide

This document provides a style guide for .proto files. By following these conventions, you'll make your protocol buffer message definitions and their corresponding classes consistent and easy to read.本文档提供了.proto文件的样式指南。通过遵循这些约定，可以使协议缓冲区消息定义及其相应的类保持一致并易于阅读。

Note that protocol buffer style has evolved over time, so it is likely that you will see .proto files written in different conventions or styles.Please respect the existing style when you modify these files. Consistency is key.However, it is best to adopt the current best style when you are creating a new .proto file.请注意，protocol buffer样式已随着时间而发展，因此您可能会看到以不同约定或样式编写的.proto文件。修改这些文件时，请尊重现有样式。一致性是关键。但是，在创建新的.proto文件时，最好采用当前的最佳样式。

Standard file formatting 标准文件格式

• Keep the line length to 80 characters.保持行长为80个字符。
• Use an indent of 2 spaces.缩进2个空格。

File structure文件结构

Files should be named lower_snake_case.proto文件应命名为lower_snake_case.proto

All files should be ordered in the following manner:所有文件应按以下方式：

1. License header (if applicable) 许可头（如果适用）
2. File overview档案总览
3. Syntax
4. Package
5. Imports (sorted)
6. File options
7. Everything else

Packages

Package name should be in lowercase, and should correspond to the directory hierarchy. e.g., if a file is in my/package/, then the package name should be my.package.程序包名称应为小写，并且应与目录层次结构相对应。例如，如果文件位于my/package/ 中，则包名称应为my.package。

Message and field names

Use CamelCase (with an initial capital) for message names – for example, SongServerRequest. Use underscore_separated_names for field names (including oneof field and extension names) – for example, song_name.使用CamelCase（首字母大写）作为消息名称-例如，SongServerRequest。使用underscore_separated_names作为字段名称（包括字段名和扩展名之一），例如song_name。

message SongServerRequest { 
    required string song_name = 1; 
}

Using this naming convention for field names gives you accessors like the following:使用字段名称的这种命名约定，可以使访问器如下所示：

C++:
  const string& song_name() { ... }
  void set_song_name(const string& x) { ... }

Java:
  public String getSongName() { ... }
  public Builder setSongName(String v) { ... }

If your field name contains a number, the number should appear after the letter instead of after the underscore. e.g., use song_name1 instead of song_name_1.如果您的字段名称包含数字，则该数字应出现在字母之后而不是下划线之后。例如，使用song_name1代替song_name_1

Repeated fields

Use pluralized names for repeated fields.对重复的字段使用复数名称。

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

 Enums

Use CamelCase (with an initial capital) for enum type names and CAPITALS_WITH_UNDERSCORES for value names:使用CamelCase（以大写字母开头）作为枚举类型名称，并使用CAPITALS_WITH_UNDERSCORES作为值名称：

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

Each enum value should end with a semicolon, not a comma. Prefer prefixing enum values instead of surrounding them in an enclosing message. The zero value enum should have the suffix UNSPECIFIED.每个枚举值都应以分号（而不是逗号）结尾。优先为枚举值添加前缀，而不是将其包含在封闭消息中。零值枚举应带有后缀UNSPECIFIED。

Services

If your .proto defines an RPC service, you should use CamelCase (with an initial capital) for both the service name and any RPC method names:如果您的.proto定义了RPC服务，则应该对服务名称和任何RPC方法名称都使用CamelCase（以大写字母开头）：

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

Things to avoid 避免的事情

• Required fields (only for proto2)
• Groups (only for proto2)