规范指引

参考 谷歌官方文档

文件名

Protobuf 文件使用snake_case 规则命名（小写字母+下划线），以 .proto 为后缀。比如：player_info.proto

样式规范

格式

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

包名

包名称应为小写，并且应与目录层次结构相对应，例如：my.package

Message 和 字段命名

使用驼峰命名法（首字母大写）命名 message，例子：PlayReq
使用下划线命名字段，例子：play_name

  1. // 播放请求
  2. message PlayReq {
  3.     string play_name = 1;
  4. }

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

重复字段 Repeated

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

  1. message PlayRes {
  2.     repeated string keys = 1;
  3.       ...
  4.       repeated Reason reasons = 17;
  5. }

枚举 Enums

使用驼峰命名法（首字母大写）命名枚举类型，使用 “大写下划线大写” 的方式命名枚举值，以分号结尾，枚举必须从0开始。

  1. // 状态码
  2. enum Code {
  3.   CODE_UNSPECIFIED  = 0;
  4.   CODE_OK           = 1;
  5.   CODE_UNAUTHORIZED = 2;
  6. }

优先通过给枚举值添加前缀来区分，而不是将它们包围在封闭的 message 中。
因为枚举的默认值是零值，所以零值枚举应该设置成ENUN_TYPE_UNSPECIFIED。

服务 Services

使用驼峰命名法（首字母大写）命名 RPC 服务以及其中的 RPC 方法

  1. service User {
  2.     // 获取所有用户
  3.     rpc GetAll(GetAllReq) returns (GetAllRes) {}
  4.     // 根据邮箱获取用户
  5.     rpc GetOneByEmail(GetOneByEmailReq) returns (GetOneByEmailRes) {}
  6. }

为了方便阅读，方法的请求与响应必须与方法名相同，并增加对应的后缀 Req 或 Res

嵌套类型

不可复用的特定的枚举或消息可使用嵌套写法，方便阅读

  1. // 自检响应
  2. message SelfCheckRes {
  3.     // 自检结果
  4.     bool result = 1;
  5.     // 自检异常
  6.     enum SelfCheckReason {
  7.         SELF_CHECK_UNSPECIFIED = 0; // 无效
  8.         POWER_CHECK  = 1;  // 电源控制异常
  9.         SWITCH_CHECK = 2;  // 开关机控制
  10.     }
  11.     // 自检失败时附带失败原因
  12.     repeated SelfCheckReason reasons = 2;
  13. }

复用可重复的枚举或消息，改为通用，只保留一个即可

IDE 配置自动格式化

VSCode 搜索插件
image.png
格式化还需要安装 clang-format，自行安装下，然后在 setting.json 中添加如下配置

  1. "clang-format.style": "{ IndentWidth: 2, ColumnLimit: 80, BasedOnStyle: google, Language: Proto, AlignConsecutiveAssignments: true, AlignConsecutiveDeclarations: true }",

所有配置参考 官网文档