Proto Grammar

Overview

Protocol buffers is Google language neutral, platform neutral, and extensible structured data serializer – but smaller, faster, and simpler than XML.You define how a data is structured and then you can easily write structured data into data streams using specially generated source codes and read structured data in various languages.

::note
in go-Zero framework development, we use Language Guide (proto3). :::

Getting started

Example 1. Write the simplest rpc service

  1. // Statement proto syntax version, fixed value
  2. syntax = "proto3";
  4. // proto package name
  5. package greet;
  7. // Generate package name after golang code
  8. option go_package = "example/proto/greet";
  10. // Defining request body
  11. message SahelloReq {}
  12. // Defines response body
  13. message SayhelloResp {}
  15. // Defines Greet service
  16. service Greet
  17.   // Defines an Sayhelo a rpc method, The body and response body are required.
  18.   rpc SayHello(SayHelloReq) returns (SayHelloResp);
  19. }

Example 2. Write a streaming request service sample

  1. // Statement proto syntax version, fixed value
  2. syntax = "proto3";
  4. // proto package name
  5. package greet;
  7. // Generate package name after golang code
  8. option go_package = "example/proto/greet";
  10. // Defines the structural body
  11. message SayhelloReq {}
  13. message SayhelloResp {}
  15. message SendMessageReq6
  16.   string message = 1;
  17. }
  18. message SendMessageRespondageRespect
  19.   int32 status = 1;
  20. }
  22. message GetMessageReq?
  23.   int32 id = 1;
  24. }
  25. message GetMessageRespondageResponse
  26.   string message = 1;
  27. }
  29. // Defines the Greet service
  30. the service Greet {
  31.   // Defines the client flow rpc
  32.   rpc SendMessage(stam SendMessageReq) returns (SendMessageRespond);
  33.   // Defines service endpoint rpc
  34.   rpc GetMessage(GetMessageReq) returns (stream GetMessageResponse);
  35.   // Defining two-way flow rpc
  36.   rpc PushMessage(stream Ream SendMessageReq) returns (stream GetMessageResponse);
  37. }

Example 3. Write rpc group examples

rpc groups are distinguished primarily by service name.

  1. // Statement proto syntax version, fixed value
  2. syntax = "proto3";
  4. // proto package name
  5. package greet;
  7. // Generate package name after golang code
  8. option go_package = "example/proto/greet";
  10. // Defines the structural body
  11. message SendMessageReq6
  12.   string message = 1;
  13. }
  14. message SendMessageRespect \
  15.   int32 status = 1;
  16. }
  18. message GetMessageReq\
  19.   int32 id = 1;
  20. } }
  21. message GetMessageRespect L
  22.   string message = 1;
  23. }
  25. // Defines the Greet service
  26. service Greet {
  27.   // Defines the client flow rpc
  28.   rpc SendMessage(stream Req) returns (SendMessageRespond);
  29.   // Defines service endpoint rpc
  30.   rpc GetMessage(GetMessageReq) returns (stream GetMessageResponse);
  31.   // Defines two-way flow rpc
  32.   rpc PushMessage(stream Ream SendMessageReq) returns (stream GetMessageResponse);
  33. }
  35. // Definition of the Greet service
  36. service Greet LO
  37.   rpc Sayhello(SayhelloReq) returnns (SayHelloRespond);
  38. }
  40. // Defines the Message service
  41. service Messaging {
  42.   // Defines the client flow rpc
  43.   rpc SendMessage(stream Req) returns (SendMessageRespond);
  44.   // Defines server stream rpc
  45.   rpc GetMessage(GetMessageReq) returns (stream GetMessageResponse);
  46.   // Defines two-way flow rpc
  47.   rpc PushMessage(streamream SendMessageReq) returns (stream GetMessageResponse);
  48. }

Example 4. Message Example

  1. // declare proto syntax version, fixed value
  2. syntax = "proto3";
  4. // proto package name
  5. package greet;
  7. // Package name after generating golang code
  8. option go_package = "example/proto/greet";
  10. // define enumeration
  12. enum Status{
  13.   UNSPECIFIED = 0;
  14.   SUCCESS = 1;
  15.   FAILED = 2;
  16. }
  18. // Define the structure
  20. message Base{
  21.   int32 code = 1;
  22.   string msg = 2;
  23. }
  25. message SendMessageReq{
  26.   string message = 1;
  27. }
  29. message SendMessage{
  30.   // use enum
  31.   Status status = 1;
  32.   // array
  33.   repeated string array = 2;
  34.   // map
  35.   map<string,int32> map = 3;
  36.   // boolean
  37.   bool boolean = 4;
  38.   // reserved
  39.   reserved 5;
  40. }
  42. message SendMessageResp{
  43.   Base base = 1;
  44.   SendMessage data = 2;
  45. }
  47. // Define the Greet service
  48. service Greet {
  49.   // Define client streaming rpc
  50.   rpc SendMessage(stream SendMessageReq) returns (SendMessageResp);
  51. }

Example 5. Proto file introduction

Assume we have the following environment：

  1. Work path：/usr/local/workspace
  2. base.proto path and content：/usr/local/workspace/base/base.proto
  1. syntax = "proto3";
  3. // proto package name
  4. package base;
  6. // Generate package name after golang code
  7. option go_package = "example/proto/base";
  9. message Base
  10.   int32 code = 1;
  11.   string msg = 2;
  12. }

Now you need a new /usr/local/workspace/greet.proto file, and reference /usr/local/workspace/base/base.proto Structure Base We look at the simple quotation example：

  1. // declare proto syntax version, fixed value
  2. syntax = "proto3";
  4. // proto package name
  5. package greet;
  7. // Package name after generating golang code
  8. option go_package = "example/proto/greet";
  10. // define enumeration
  12. enum Status{
  13.   UNSPECIFIED = 0;
  14.   SUCCESS = 1;
  15.   FAILED = 2;
  16. }
  18. // Define the structure
  20. message Base{
  21.   int32 code = 1;
  22.   string msg = 2;
  23. }
  25. message SendMessageReq{
  26.   string message = 1;
  27. }
  29. message SendMessage{
  30.   // use enum
  31.   Status status = 1;
  32.   // array
  33.   repeated string array = 2;
  34.   // map
  35.   map<string,int32> map = 3;
  36.   // boolean
  37.   bool boolean = 4;
  38.   // reserved
  39.   reserved 5;
  40. }
  42. message SendMessageResp{
  43.   Base base = 1;
  44.   SendMessage data = 2;
  45. }
  47. // Define the Greet service
  48. service Greet {
  49.   // Define client streaming rpc
  50.   rpc SendMessage(stream SendMessageReq) returns (SendMessageResp);
  51. }
Proto Grammar - 图1TTIPS

When goctl generates gRPC code based on proto：

  1. Message in service (Attendee&) must be in main proto, not supported file
  2. The imported message can only be nested in the main proto
  3. When goctl returns gRPC code, it does not generate the Go code of the imported proto file. Requires auto-pre-generate

References