规范指引

参考 谷歌官方文档

文件名

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

样式规范

格式

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

包名

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

Message 和 字段命名

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

// 播放请求
message PlayReq {
    string play_name = 1;
}

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

重复字段 Repeated

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

message PlayRes {
    repeated string keys = 1;
  	...
  	repeated Reason reasons = 17;
}

枚举 Enums

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

// 状态码
enum Code {
  CODE_UNSPECIFIED  = 0;
  CODE_OK           = 1;
  CODE_UNAUTHORIZED = 2;
}

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

服务 Services

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

service User {
    // 获取所有用户
    rpc GetAll(GetAllReq) returns (GetAllRes) {}
    // 根据邮箱获取用户
    rpc GetOneByEmail(GetOneByEmailReq) returns (GetOneByEmailRes) {}
}

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

嵌套类型

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

// 自检响应
message SelfCheckRes {
    // 自检结果
    bool result = 1;
    // 自检异常
    enum SelfCheckReason {
        SELF_CHECK_UNSPECIFIED = 0; // 无效
        POWER_CHECK  = 1;  // 电源控制异常
        SWITCH_CHECK = 2;  // 开关机控制
    }
    // 自检失败时附带失败原因
    repeated SelfCheckReason reasons = 2;
}

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

IDE 配置自动格式化

VSCode 搜索插件

格式化还需要安装 clang-format，自行安装下，然后在 setting.json 中添加如下配置

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

所有配置参考 官网文档