Full Example of Proto Definition

Proto Example

The following example is from Language Guide (proto3)

  1. // Statement proto use syntax
  2. syntax = "proto3";
  4. // proto package name
  5. package demo;
  7. // golang package name
  8. option go_package = "github. om/zeroicro/example/proto/demo";
  10. // Structure
  11. // SearchRequest Message definition specifies three fields (name/value), each field corresponds to each of the data to be included in such messages.Each field has a name and type.
  12. message SearchRequest {
  13.   string = 1;
  14.   int32 page_number = 2;
  15.   int32 result_per_page = 3;
  16. }
  18. // If required. Roto file add annotations, use C/C++ style // / *...*/ syntax.
  19. /* SearchRequest presents a search query, with identification options to
  20.  * indicating which results to include in the response. */
  22. message SearchRequest {
  23.   string = 1;
  24.   int32 page_number = 2; // Which page number do we want?
  25.   int32 result_per_page = 3; // Number of results to return per page.
  26. }
  28. // Keep the field writing sample
  29. // If you update the message type by completely removing or annoying a field, future users will be free to update the field number to
  30. // that type.If users load later older versions of the same .proto (including data breaks, privacy bugs etc.),
  31. // this may cause serious problems.One way to ensure that this does not happen is to reserve the field number
  32. // (and/or the name that may also cause JSON serialization problems) that has been deleted.If any future user attempts to use these words
  33. // segment identifier, the protocol buffer compiler will complain.
  34. message Foo {
  35.   reserved 2, 15, 9 to 11;
  36.   reserved "foo", "bar";
  37. }
  39. // Enums
  40. // In defining message type, you may want a field to have only one predefined list of values.For example, suppose you want to add a corpus field for each 
  41. // SearchRequest where the body can be UNIVERSAL, WEB, IMAGES, LOCAL,
  42. //NEWS, PRODUCTS or VIDEO.For this, you simply need to add enum in the message definition and add a constant to each possible value.
  44. // In the following example, we've added a field named Corpus (containing all possible values) and Corpus type：
  45. / / as you see, the first constant map of the Corpus enumeration to zero：each item must contain a first constant to zero as its
  46. // first element.The reason is the following：
  47. // 
  48. // 1. Must have a zero value so that we can use 0 as a default value for numbers.
  49. // Zero must be the first element to be compatible with proto2 in which the first value is always the default.
  51. enum Corpus {
  52.   CORPUS_UNSPECIFIED = 0;
  53.   CORPUS_UNIVERSAL = 1;
  54.   CORPUS_WEB = 2;
  55.   CORPUS_IMAGES = 3;
  56.   CORPUS_LOCAL = 4;
  57.   CORPUS_NEWS = 5;
  58.   CORPUS_PRODUCTS = 6;
  59.   CORPUS_VIDEO = 7;
  60. }
  62. message SearchRequest {
  63.   string query = 1;
  64.   int32 page_number = 2;
  65.   int32 result_per_page = 3;
  66.   Corpus corps = 4;
  67. }
  69. // Use other message type
  70. // You can use other message types as field type.message SearchResponse {
  71.   repeated Result results = 1;
  72. }
  74. message Result {
  75.   string url = 1;
  76.   string title = 2;
  77.   repeated string snippets = 3;
  78. }
  80. message SearchResponse {
  81.   message Result {
  82.     string url = 1;
  83.     string title = 2;
  84.     repeated string snippets = 3;
  85.   }
  86.   repeated Result results = 1;
  87. }
  89. // map
  90. message SearchResponse {
  91.     map<string, Project> projects = 1;
  92. }For example, if you want to use the method of accepting SearchRequest
  93. // and return SearchResponse to define RPC services, it can be defined in a .proto file as shown below in：
  94. service SearchService 6
  95.   rpc Search(SearchRequest) returns (Search);
  96. }