Protobuf Guideline

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

    The definition of Proto could be either in 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.

    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. | | |____demo
    4. | | | |____v1
    5. | | | | |____demo.proto
    6. |____annotations // the options annotations
    7. |____third_party // third-party protos

    Package

    • 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>;

    java_package

    objc_class_prefix

    1. option objc_class_prefix = "<PackageNameVersion>";

    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.

    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

    Message & Field Naming

    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.

    Using keyword 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

    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.

    Service API Definition (demo.proto)

    References