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 ordered in the following manner:

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

Message & Field Naming

Use CamelCase (with an initial capital) for message names, e.g., SongServerRequest.
Use underscore_separated_names for field names (including oneof field and extension names) , e.g., song_name.

  1. message SongServerRequest {
  2.   optional 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 Fields

Use pluralized names for repeated fields.

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

Enums

Use CamelCase (with an initial capital) for enum type names and CAPITALS_WITH_UNDERSCORES for value names:

  1. enum FooBar {
  2.   FOO_BAR_UNSPECIFIED = 0;
  3.   FOO_BAR_FIRST_VALUE = 1;
  4.   FOO_BAR_SECOND_VALUE = 2;
  5. }

Each enum value should end with a semicolon, not a comma. Prefer prefixing enum values instead of surrounding them in an enclosing message. The zero value enum should have the suffix UNSPECIFIED.

Services

If your .proto defines an RPC service, you should use CamelCase (with an initial capital) for both the service name and any RPC method names.

  1. service FooService {
  2.   rpc GetSomething(GetSomethingRequest) returns (GetSomethingResponse);
  3.   rpc ListSomething(ListSomethingRequest) returns (ListSomethingResponse);
  4. }

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";   //the name after ; is for relative code generation
  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