Kratos Protobuf 規(guī)范

Protobuf 規(guī)范

這里主要進行修訂Proto規(guī)范約定和多語言之間特定商定，幫助大家寫出更標(biāo)準(zhǔn)的接口。

API接口統(tǒng)一以HTTP/GRPC為基礎(chǔ)，并通過Protobuf進行協(xié)議定義，包括完整的Request/Reply，以及對應(yīng)的接口錯誤碼（Errors）。

目錄結(jié)構(gòu)

API接口可以定義到項目，或者在統(tǒng)一倉庫中管理Proto，類似googleapis、envoy-api、istio-api；

項目中定義Proto，以api為包名根目錄：

kratos-demo：
|____api // 服務(wù)API定義
| |____kratos
| | |____demo
| | | |____v1
| | | | |____demo.proto

在統(tǒng)一倉庫中管理Proto，以倉庫為包名根目錄：

kratos-apis:
|____api // 服務(wù)API定義
| |____kratos
| | |____demo
| | | |____v1
| | | | |____demo.proto
|____annotations // 注解定義options
|____third_party // 第三方引用

包名

包名為應(yīng)用的標(biāo)識（APP_ID），用于生成gRPC請求路徑，或者Proto之間進行引用Message；

• my.package.v1，為API目錄，定義service相關(guān)接口，用于提供業(yè)務(wù)使用

// RequestURL: /<package_name>.<version>.<service_name>/{method}
package <package_name>.<version>;

• go_package

option go_package = "github.com/go-kratos/kratos/<package_name>;<version>";

• java_package

option java_multiple_files = true;
option java_package = "com.github.kratos.<package_name>.<version>";

• objc_class_prefix

option objc_class_prefix = "<PackageNameVersion>";

Version

該版本號為標(biāo)注不兼容版本，并且會在<package_name>中進行區(qū)分，當(dāng)接口需要重構(gòu)時一般會更新不兼容結(jié)構(gòu)；

Import

• 業(yè)務(wù)proto依賴，以根目錄進行引入對應(yīng)依賴的proto；
• third_party，主要為依賴的第三方proto，比如protobuf、google rpc、google apis、gogo定義；

命名規(guī)范

目錄結(jié)構(gòu)

包名為小寫，并且同目錄結(jié)構(gòu)一致，例如：my/package/v1/

package my.package.v1;

文件結(jié)構(gòu)

文件應(yīng)該命名為：?lower_snake_case.proto? 所有Proto應(yīng)按下列方式排列:

1. License header (if applicable)
2. File overview
3. Syntax
4. Package
5. Imports (sorted)
6. File options
7. Everything else

Message 和 字段命名

使用駝峰命名法（首字母大寫）命名 message，例子：SongServerRequest 使用下劃線命名字段，例子：song_name

message SongServerRequest {
  required string song_name = 1;
}

使用上述這種字段的命名約定，生成的訪問器將類似于如下代碼：

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

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

數(shù)組 Repeated

通過repeated關(guān)鍵字定義數(shù)組（List）：

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

枚舉 Enums

使用駝峰命名法（首字母大寫）命名枚舉類型，使用 “大寫下劃線大寫” 的方式命名枚舉值：

enum Foo {
  FIRST_VALUE = 0;
  SECOND_VALUE = 1;
}

每一個枚舉值以分號結(jié)尾，而非逗號。

服務(wù) Services

如果你在 .proto 文件中定義 RPC 服務(wù)，你應(yīng)該使用駝峰命名法（首字母大寫）命名 RPC 服務(wù)以及其中的 RPC 方法：

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

Comment

• Service，描述清楚服務(wù)的作用
• Method，描述清楚接口的功能特性
• Field，描述清楚字段準(zhǔn)確的信息

Examples

API Service接口定義(demo.proto)

syntax = "proto3";

package kratos.demo.v1;

// 多語言特定包名，用于源代碼引用
option go_package = "github.com/go-kratos/kratos/demo/v1;v1";
option java_multiple_files = true;
option java_package = "com.github.kratos.demo.v1";
option objc_class_prefix = "KratosDemoV1";

// 描述該服務(wù)的信息
service Greeter {
    // 描述該方法的功能
    rpc SayHello (HelloRequest) returns (HelloReply);
}
// Hello請求參數(shù)
message HelloRequest {
    // 用戶名字
    string name = 1;
}
// Hello返回結(jié)果
message HelloReply {
    // 結(jié)果信息
    string message = 1;
}