GRpc-Proto3语法

 

 

  1. syntax = “proto3”;
    文本之率先行指定了而用的是proto3的语法:如果你莫点名,protocol
    buffer
    编译器就会看你采取的凡proto2的语法。这个讲话必须出现在.proto文件的非空非注释的首先执。
  2. message SearchRequest {……}
    message 定义实体
  3. 主导数据列
    图片 1

     

  4. 诠释符号: 双倾线,如://xxxxxxxxxxxxxxxxxxx

  5. 字段唯一数字标识(用于在亚前进制格式中分辨各个字段,上线后不宜再变更):Tags
    1到15动一个字节来编码,包括标识数字与字段类型(你得以Protocol
    Buffer
    编码中查阅更多详细);16顶2047占有用有限独字节。因此定义proto文件时应有保留1交15,用作出现最频繁之音讯类型的标识。记得也明天会面延续加码并可能频出现的因素留一点儿标识区间,也就是说,不要一下子将1—15举用完,为前留一点儿。
    标识数字之法定范围:最小是1,最可怜是 229 –
    1,或者536,870,911。
    此外,不克下19000 到
    19999里头的数字(FieldDescriptor::kFirstReservedNumber through
    FieldDescriptor::kLastReservedNumber),因为它们为Protocol
    Buffers保留下
  6. 字段修饰符:
    required:值不得吗空
    optional:可选字段
    singular:符合语法规则之信息包含零个或者一个这么的字段(最多一个)
    repeated:一个字段在官方的信息中可以又出现一定次数(包括零次)。重复出现的价值的程序将为封存。在proto3中,重复出现的值类型字段默认使用压缩编码。你可以于此间找到更多关于压缩编码的东西: Protocol
    Buffer
    Encoding。
    默认值: optional PhoneType type = 2 [default = HOME];
  7. 代理类生成
    1. C++, 每一个.proto 文件可以十分成一个 .h 文件及一个 .cc 文件
    2. Java, 每一个.proto文件可以挺成一个 .java 文件
    3. Python,
      每一个.proto文件特别成一个模块,其中也各国一个信类型变更一个静态的描述器,在运作时,和一个metaclass一起使用来创造必要之Python数据访问类
    4. Go, 每一个.proto生成一个 .pb.go 文件
    5. Ruby, 每一个.proto生成一个 .rb 文件
    6. Objective-C, 每一个.proto 文件可以非常成一个 pbobjc.h
      和一个pbobjc.m 文件
    7. C#, 每一个.proto文件可以很成一个.cs文件.
  8. 配段默认值
    1. strings, 默认值是空字符串(empty string)
    2. bytes, 默认值是空bytes(empty bytes)
    3. bools, 默认值是false
    4. numeric, 默认值是0
    5. enums, 默认值是首先单枚举值(value必须为0)
    6. message fields, the field is not set. Its exact value is
      langauge-dependent. See the generated code guide for details.
    7. repeated fields,默认值为empty,通常是一个空list
  9. 枚举
    图片 2 
第一个元素的value必须为0;
  1. Maps字段类型:map<key_type, value_type> map_field = N;
    1. map字段未能够是repeated.
    2. Wire format ordering and map iteration ordering of map values is
      undefined, so you cannot rely on your map items being in a
      particular order.
    3. When generating text format for a .proto, maps are sorted by
      key. Numeric keys are sorted numerically.
    4. When parsing from the wire or when merging, if there are
      duplicate map keys the last key seen is used. When parsing a map
      from text format, parsing will fail if there are duplicate keys.
    1. 更新.proto文件
      当原有的.proto结构不能够满足工作需要时,可以修改.proto文件,重新转代理类,修改时用以以下原则:
    2. 未克改就在字段的绝无仅有数字标识符(tags)
    3. If you add new fields, any messages serialized by code using
      your “old” message format can still be parsed by your new
      generated code. You should keep in mind the default values for
      these elements so that new code can properly interact with
      messages generated by old code. Similarly, messages created by
      your new code can be parsed by your old code: old binaries
      simply ignore the new field when parsing. Note that unknown
      fields are discarded when the message is deserialized, so if the
      message is passed on to new code, the new fields will not still
      be available (this is different behaviour to proto2, where
      unknown fields are serialized along with the message).
    4. 针对遗弃之字段,它的tags不能被再次用,可以免去,而是于字段添加“OBSOLETE_
      ”前缀,这样可免将来又祭这个tags
    5. int32, uint32, int64, uint64,
      和bool是截然匹配的,这些字段类型中可直接修改
    6. sint32 和 sint64 是匹配的,但是与任何的数字型不兼容
    7. string 和 bytes 是匹配的,由于bytes也是 UTF-8格式
    8. Embedded messages are compatible with bytes if the bytes contain
      an encoded version of the message.
    9. fixed32 和 sfixed32兼容, fixed64和sfixed64兼容
    10. enum 和 int32, uint32, int64, and uint64 in terms of wire format
      (note that values will be truncated if they don’t fit). However
      be aware that client code may treat them differently when the
      message is deserialized: for example, unrecognized proto3 enum
      types will be preserved in the message, but how this is
      represented when the message is deserialized is
      language-dependent. Int fields always just preserve their value.
  2. Packages支持
  3. 定义Services
  4. 其他Options:

    1. java_package(file option):option java_package =
      “com.example.foo”;
    2. java_outer_classname(file option ):option
      java_outer_classname = “Ponycopter”;
    3. optimize_for(file option ):值为SPEED,
      CODE_SIZE或LITE_RUNTIME;如:option optimize_for =
      CODE_SIZE;

        • SPEED (default): The protocol buffer compiler will
          generate code for serializing, parsing, and performing
          other common operations on your message types. This code
          is extremely highly optimized.
        • CODE_SIZE: The protocol buffer compiler will generate
          minimal classes and will rely on shared,
          reflection-based code to implement serialialization,
          parsing, and various other operations. The generated
          code will thus be much smaller than with SPEED, but
          operations will be slower. Classes will still implement
          exactly the same public API as they do in SPEED mode.
          This mode is most useful in apps that contain a very
          large number .proto files and do not need all of them
          to be blindingly fast.
        • LITE_RUNTIME: The protocol buffer compiler will
          generate classes that depend only on the “lite” runtime
          library (libprotobuf-lite instead of libprotobuf).
          The lite runtime is much smaller than the full library
          (around an order of magnitude smaller) but omits certain
          features like descriptors and reflection. This is
          particularly useful for apps running on constrained
          platforms like mobile phones. The compiler will still
          generate fast implementations of all methods as it does
          in SPEED mode. Generated classes will only implement
          the MessageLite interface in each language, which
          provides only a subset of the methods of the
          full Message interface.
    4. cc_enable_arenas (file option ): 生成C++代码时启用arena
      allocation.

    5. objc_class_prefix (file option ): 设置 Objective-C
      class前缀,which is prepended to all Objective-C generated
      classes and enums from this .proto. There is no default. You
      should use prefixes that are between 3-5 uppercase characters as
      recommended by Apple. Note that all 2 letter prefixes are
      reserved by Apple.
    6. deprecated (field option):
      如果安也true,则该字段被置为“deprecated”,在新的代码中无可知为延续采取,In
      most languages this has no actual effect. In Java, this becomes
      a @Deprecated annotation. In the future, other language-specific
      code generators may generate deprecation annotations on the
      field’s accessors, which will in turn cause a warning to be
      emitted when compiling code which attempts to use the field. If
      the field is not used by anyone and you want to prevent new
      users from using it, consider replacing the field declaration
      with a reserved statement.
      int32 old_field = 6 [deprecated=true];

 

示例:

 图片 3

 

 

 图片 4