Published on

Protocol Buffer 编码风格指南

Authors
  • avatar
    Name
    工程师Ali
    Twitter

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

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

Table of Contents

标准文件格式

  • 文件命名格式为:lower_snake_case.proto

  • 每行最长 80 个字符。

  • 使用 2 空格 缩进。

  • 字符串使用双引号。

文件结构

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

  1. License Header(如果有的话)

  2. 文件级别的描述注释

  3. Syntax

  4. Package

  5. Imports (需要排序)

  6. File options

  7. 其他内容(Message、Enum...)

例:

poster.proto
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