Protobuf Guideline

This documentation is the guideline of Protobuf definition which recommended in Kratos project.

The API definition is based on HTTP and gRPC, written with Protobuf format They should includes all the Request, Reply and the corresponding Errors.

Directory Structure

The definition of Proto could be either in api directory of the project or in a unified repository, likes googleapis, envoy-api,istio-api.

For the proto in project, the api should be used as the root of package name.

  1. kratos-demo：
  2. |____api // The definition of service's API
  3. | |____kratos
  4. | | |____demo
  5. | | | |____v1
  6. | | | | |____demo.proto

For the proto in unified repository, the repository name should be used as the root of package name.

  1. kratos-apis:
  2. |____api // The definition of service's API
  3. | |____kratos
  4. | | |____demo
  5. | | | |____v1
  6. | | | | |____demo.proto
  7. |____annotations // the options annotations
  8. |____third_party // third-party protos

Package

The name of the package (APP_ID) will be used for generate the request path of gRPC API or the path for proto importing.

  • my.package.v1 is the API’s directory, which defines the API of the services.

For example.

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

go_package

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

java_package

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

objc_class_prefix

  1. option objc_class_prefix = "<PackageNameVersion>";

Version

This version is for incompatible version and always used with <package_name>. It should be modified for API breaking changes.

Import

  • the proto dependencies’ import path should be started from root path.
  • third_party, includes the proto from third-party such as protobuf, google rpc,google apis, gogo etc.

Naming Convention

Directory Structure

The package name should be lower-case, consist with the project directory structure, e.g., my/package/v1/

  1. package my.package.v1;

File Structure

The name of proto files should be lower_snake_case.proto The contents of proto file should be arranged as follows.

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

Message & Field Naming

The name of message should be PascalCase, e.g., SongServerRequest. The name of field should be snake_case, e.g., song_name

  1. message SongServerRequest {
  2.   required string song_name = 1;
  3. }

Corresponding with the definitions which mentioned above, the generated code can be shown as follows.

  1. C++:
  2.   const string& song_name() { ... }
  3.   void set_song_name(const string& x) { ... }
  5. Java:
  6.   public String getSongName() { ... }
  7.   public Builder setSongName(String v) { ... }

Repeated

Using keyword repeated to define an array(List):

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

Enums

The name of enums should be PascalCase, and the enum values’ name should be UPPER_CASE_SNAKE_CASE.

  1. enum Foo {
  2.   FIRST_VALUE = 0;
  3.   SECOND_VALUE = 1;
  4. }

Every line must be end with a semicolon (;) rather than comma.

Services

In the .proto file, PascalCase should be applied on names of RPC services and the methods of the services.

  1. service FooService {
  2.   rpc GetSomething(FooRequest) returns (FooResponse);
  3. }

Comment

  • Service describes the functions of this service.
  • Method describe the functions of this API.
  • Field describe the information of this field.

Examples

Service API Definition (demo.proto)

  1. syntax = "proto3";
  3. package kratos.demo.v1;
  5. // specifying the package names for importing from multiple programming language
  6. option go_package = "github.com/go-kratos/kratos/demo/v1;v1";
  7. option java_multiple_files = true;
  8. option java_package = "com.github.kratos.demo.v1";
  9. option objc_class_prefix = "KratosDemoV1";
  11. // Definition of the service
  12. service Greeter {
  13.     // definition the function of API
  14.     rpc SayHello (HelloRequest) returns (HelloReply);
  15. }
  16. // the request of Hello
  17. message HelloRequest {
  18.     // user's name
  19.     string name = 1;
  20. }
  21. // the response of Hello 
  22. message HelloReply {
  23.     // result data
  24.     string message = 1;
  25. }

References