Protocol Buffer 编码风格指南

虽然每个人都可以有自己的编码风格，但使用行业内通用的编码风格有利于其他人阅读、交流。

本文介绍了 Protocol Buffer 官方推荐的编码风格，补充了更多的示例。

标准文件格式

• 文件命名格式为：lower_snake_case.proto。

• 每行最长 80 个字符。

• 使用 2 空格 缩进。

• 字符串使用双引号。

文件结构

所有 .proto 文件中，应当按照以下顺序组织内容：

1. License Header（如果有的话）

2. 文件级别的描述注释

3. Syntax

4. Package

5. Imports (需要排序)

6. File options

7. 其他内容（Message、Enum...）

例：

syntax = "proto3";

package imgrender.poster.v1;

import "google/api/annotations.proto";

option go_package = "api/shop/admin/v1;v1";

message RenderPosterReq {}

message RenderPosterReply {}

Package

• Package name 采用 lowercase 格式（全小写）。

• Package name 在项目内唯一。

• 尽快可能包含文件路径。

例如，在 imgrender 项目中，存在如下文件结构：

├── api
│   ├── imgrender
│   │   ├── poster
│   │   │   ├── v1
│   │   │   |    ├── poster.proto

则 poster.proto 的 Package 可以命名为 imgrender.poster.v1。

Message 和字段的命名

Message 的命名：

• 格式为 CamelCase，即所有单词首字母大写。例如， SongServerRequest。

字段的命名：

• 格式为 underscore_separated_names，即所有字母小写，并使用下划线分割单词。例如，song_name。

• 如果字段名称中包含数字，则数字应当直接写在字母最后，不需要使用下划线分割。例如，song_name1，而不应该是song_name_1。

• repeated 字段的名称应当使用复数形式。例如：repeated string keys = 1;

完整示例：

message SongServerRequest {
  optional string song_name = 1;
  string song_name2 = 2;
  repeated string keys = 3;
}

枚举

枚举使用 CamelCase（首字母大写） 格式命名，成员使用 CAPITALS_WITH_UNDERSCORES 格式命名：

enum FooBar {
  FOO_BAR_UNSPECIFIED = 0;
  FOO_BAR_FIRST_VALUE = 1;
  FOO_BAR_SECOND_VALUE = 2;
}

• 每个枚举值都应该以分号结尾。

• 零值枚举应该有后缀 UNSPECIFIED。

• 推荐为枚举值添加前缀来表明哪一 Message 在使用，不推荐直接将枚举嵌套到 Message 中。

服务

Service 和 RPC methods 都应当采用 CamelCase 格式命名。

service FooService {
  rpc GetSomething(GetSomethingRequest) returns (GetSomethingResponse);
  rpc ListSomething(ListSomethingRequest) returns (ListSomethingResponse);
}

原文链接：https://developers.google.com/protocol-buffers/docs/style

关注公众号，第一时间获取更新

关注前沿科技，分享独立开发故事。欢迎一起寻找利基市场，构建小而美的生意