Summary of how to write .proto files used in gRPC

--In gRPC, data is exchanged by serializing in the Protocol Buffers format. --You can define the schema in the .proto file and generate code using the tool. Therefore, if this .proto file can be shared by each client and server, it is possible to proceed with development without any deviation in specifications. --In this article, I will briefly summarize the syntax of .proto files.

Whole sample

• GitHub

//Version definition
syntax = "proto3";

//Package definition
package sample;

// import
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

//Service and RPC method definition
service SampleService {
    rpc Sample (SampleRequest) returns (SampleResponse);

    //Server streaming RPC
    rpc SampleServerStreamMethod (SampleRequest) returns (stream SampleResponse);

    //Client Streaming RPC
    rpc SampleClientStreamMethod (stream SampleRequest) returns (SampleResponse)

    //Bidirectional streaming RPC
    rpc SampleBidirectionalMethod (stream SampleRequest) returns (stream SampleResponse)
}

message SampleRequest {
    string name = 1;
}

message SampleResponse {
    Sample sample = 1;
}


//Message type
//The number on the right is the "tag number"
message Sample {
    //Scalar type
    //There are numbers, strings, booleans, byte arrays
    int32 id = 1;
    string name = 2;
    bool isBool = 3;

    //deprecated Specify fields that are deprecated and deprecated
    string duplicated_field = 4 [deprecated = true]

    //reserved identifier Discontinued tag number
    reserved 7, 8, 10 to 12;

    //List (array)
    //Multidimensional array cannot be defined
    repeated SampleList sample_list = 5;

    //Map (associative array)
    map<string, string> sample_map = 6;

    //Any one from multiple
    oneof message {
        string one = 1;
        string other = 2;
    }

    // Well Known Types
    google.protobuf.Duration sample_duration = 9;
    google.protobuf.Timestamp create_time = 13;

    //Enum
    enum SampleEnum {
        UNKNOWN = 0;
        TEST1 = 1;
        TEST2 = 2;
        TEST3 = 3;
    }

}

Version definition

syntax = "proto3";

Package definition

--You can set the package name to avoid name conflicts, such as when using messages defined in other .proto files.

package sample;

import --Use when you want to use the message type defined in another .proto file --Here, we are importing a .proto file created by Google.

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

Services and RPC methods

--API definition body --Define a service called SampleService --Defines a method called Sample that takes SampleRequest as an argument and returns SampleResponse. --If you want to stream, add stream to the argument and return value. --One-way streaming --Server streaming RPC (set stream as return value) --The server side returns multiple responses asynchronously --Client Streaming RPC (set stream as an argument) --Send multiple requests asynchronously from the client side, and return one response on the server side --Bidirectional streaming --Add stream to both argument and return value

service SampleService {
    rpc Sample (SampleRequest) returns (SampleResponse);

    //Server streaming RPC
    rpc SampleServerStreamMethod (SampleRequest) returns (stream SampleResponse);

    //Client Streaming RPC
    rpc SampleClientStreamMethod (stream SampleRequest) returns (SampleResponse);

    //Bidirectional streaming RPC
    rpc SampleBidirectionalMethod (stream SampleRequest) returns (stream SampleResponse);
}

Scalar type

--Numeric value, character string, boolean value, byte array are as data types -Details of data types and correspondence of data types after compiling in each language

• Default value

Message type

--Type with multiple fields --Tag number --The number to the right of the field. --Must be unique within the same message --reserved identifier --Enter the tag number that was discontinued due to field deletion etc. --deprecated option --Specify deprecated and deprecated fields

message Sample {
    //Scalar type
    //There are numbers, strings, booleans, byte arrays
    int32 id = 1;
    string name = 2;
    bool isBool = 3;

    //deprecated Specify fields that are deprecated and deprecated
    string duplicated_field = 4 [deprecated = true]

    //reserved identifier Discontinued tag number
    reserved 7, 8, 10 to 12;

　　//~ Omitted ~
}

List (array)

--An array can be defined by prefixing the type with repeated --Can be used for both scalar type and message type --Multidimensional arrays cannot be defined

    //List (array)
    //Multidimensional array cannot be defined
    repeated SampleList sample_list = 5;

Map (associative array)

--Only integer values, strings, and boolean values can be used for keys. --map cannot be an array

    map<string, string> sample_map = 6;

Enum

--Enums can be defined by prefixing the type with enum

    //Enum
    enum SampleEnum {
        UNKNOWN = 0;
        TEST1 = 1;
        TEST2 = 2;
        TEST3 = 3;
    }

oneof --By adding oneof, you can define one from multiple things. --Here it is a message type that returns ʻone or ʻother

    oneof message {
        string one = 1;
        string other = 2;
    }

Well Known Types --Google-defined message type --There are things such as the date and time / period and the fact that the return value is not returned

    google.protobuf.Duration sample_duration = 9;
    google.protobuf.Timestamp create_time = 13;

Code generation

--Based on the .proto file defined above, generate boilerplate code using the protoc command for each language on both sides of the client server.

reference

-Starting gRPC

• Protocol Buffers：Language Guide (proto3)