六、protobuf的使用和原理

2019-01-13  本文已影响0人  yongfutian

protobuf详解

1、安装

2、定义×××.proto文件

package example;

enum FOO { X = 17; };

message Test {
    required string label = 1;
    optional int32 type = 2 [default=77];
    repeated int64 reps = 3;
    optional group OptionalGroup = 4 {
        required string RequiredField = 5;
    }
}

生成.pb.go文件

protoc --go_out=. *.proto　//如果这个命令执行过程中出现 protoc-gen-go: program not found or is not executable 这个错误，表示该protoc-gen-go没有被加入到Path环境变量中，应该把该文件的所在目录加入Path变量中。该文件存放在环境变量GOPATH目录下的bin子目录里

golang中可用的protobuf的接口

在使用之前，我们先了解一下每个 Protobuf 消息在 Golang 中有哪一些可用的接口：
1.  每一个 Protobuf 消息对应一个 Golang 结构体
2. 消息中域名字为 camel_case 在对应的 Golang 结构体中为 CamelCase
3. 消息对应的 Golang 结构体中不存在 setter 方法，只需要直接对结构体赋值即可，赋值时可能使用到一些辅助函数，例如： msg.Foo = proto.String("hello")
4. 消息对应的 Golang 结构体中存在 getter 方法，用于返回域的值，如果域未设置值，则返回一个默认值****
5. 消息中非 repeated 的域都被实现为一个指针，指针为 nil 时表示域未设置消息中 repeated 的域被实现为 slice
6. 访问枚举值时，使用“枚举类型名_枚举名”的格式（更多内容可以直接阅读生成的源码）
7. 使用 proto.Marshal 函数进行编码，使用 proto.Unmarshal 函数进行解码

3、定义一个消息类型

syntax = "proto3";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}

当然，你也可以为字段指定其他的合成类型，包括枚举（enumerations）或其他消息类型

最小的标识号可以从1开始，最大到2^29 - 1, or 536,870,911。

    不可以使用其中的[19000－19999]，即从：
    FieldDescriptor::kFirstReservedNumber 到 FieldDescriptor::kLastReservedNumber　的标识号

Protobuf协议实现中对这些进行了预留。如果非要在.proto文件中使用这些预留标识号，编译时就会报警。同样你也不能使用早期保留的标识号。

    singular：一个格式良好的消息应该有0个或者1个这种字段（但是不能超过1个）。
    repeated：在一个格式良好的消息中，这种字段可以重复任意多次（包括0次）。重复的值的顺序会被保留。

在proto3中，repeated的标量域默认情况虾使用packed。
你可以了解更多的pakced属性在Protocol Buffer 编码

标量数值类型
一个标量消息字段可以含有一个如下的类型——该表格展示了定义于.proto文件中的类型，以及与之对应的、在自动生成的访问类中定义的类型：

.proto Type Notes C++ Type Java Type Python Type[2] Go Type Ruby Type C# Type PHP Type
double double double float float64 Float double float
float float float float float32 Float float float
int32 使用变长编码，对于负值的效率很低，如果你的域有可能有负值，请使用sint64替代 int32 int int int32 Fixnum 或者 Bignum（根据需要） int integer
uint32 使用变长编码 uint32 int int/long uint32 Fixnum 或者 Bignum（根据需要） uint integer
uint64 使用变长编码 uint64 long int/long uint64 Bignum ulong integer/string
sint32 使用变长编码，这些编码在负值时比int32高效的多 int32 int int int32 Fixnum 或者 Bignum（根据需要） int integer
sint64 使用变长编码，有符号的整型值。编码时比通常的int64高效。 int64 long int/long int64 Bignum long integer/string
fixed32 总是4个字节，如果数值总是比总是比228大的话，这个类型会比uint32高效。 uint32 int int uint32 Fixnum 或者 Bignum（根据需要） uint integer
fixed64 总是8个字节，如果数值总是比总是比256大的话，这个类型会比uint64高效。 uint64 long int/long uint64 Bignum ulong integer/string
sfixed32 总是4个字节 int32 int int int32 Fixnum 或者 Bignum（根据需要） int integer
sfixed64 总是8个字节 int64 long int/long int64 Bignum long integer/string
bool bool boolean bool bool TrueClass/FalseClass bool boolean
string 一个字符串必须是UTF-8编码或者7-bit ASCII编码的文本。 string String str/unicode string String (UTF-8) string string
bytes 可能包含任意顺序的字节数据。 string ByteString str []byte String (ASCII-8BIT) ByteString string

可以在文章Protocol Buffer 编码中，找到更多“序列化消息时各种类型如何编码”的信息。

1 在java中，无符号32位和64位整型被表示成他们的整型对应形似，最高位被储存在标志位中。
2  对于所有的情况，设定值会执行类型检查以确保此值是有效。
3  64位或者无符号32位整型在解码时被表示成为ilong，但是在设置时可以使用int型值设定，在所有的情况下，值必须符合其设置其类型的要求。
4  python中string被表示成在解码时表示成unicode。但是一个ASCIIstring可以被表示成str类型。
5 Integer在64位的机器上使用，string在32位机器上使用

    对于strings，默认是一个空string
    对于bytes，默认是一个空的bytes
    对于bools，默认是false
    对于数值类型，默认是0
    对于枚举，默认是第一个定义的枚举值，必须为0;

    对于消息类型（message），域没有被设置，确切的消息是根据语言确定的，详见generated code guide

    对于可重复域的默认值是空（通常情况下是对应语言中空列表）。

    注：对于标量消息域，一旦消息被解析，就无法判断域释放被设置为默认值（例如，例如boolean值是否被设置为false）还是根本没有被设置。你应该在定义你的消息类型时非常注意。例如，比如你不应该定义boolean的默认值false作为任何行为的触发方式。也应该注意如果一个标量消息域被设置为标志位，这个值不应该被序列化传输。

    查看generated code guide选择你的语言的默认值的工作细节。

枚举常量必须在32位整型值的范围内。因为enum值是使用可变编码方式的，对负数不够高效，因此不推荐在enum中使用负数。如上例所示，可以在 一个消息定义的内部或外部定义枚举——这些枚举可以在.proto文件中的任何消息定义里重用。当然也可以在一个消息中声明一个枚举类型，而在另一个不同 的消息中使用它——采用MessageType.EnumType的语法格式。
当对一个使用了枚举的.proto文件运行protocol buffer编译器的时候，生成的代码中将有一个对应的enum（对Java或C++来说），或者一个特殊的EnumDescriptor类（对 Python来说），它被用来在运行时生成的类中创建一系列的整型值符号常量（symbolic constants）。
在反序列化的过程中，无法识别的枚举值会被保存在消息中，虽然这种表示方式需要依据所使用语言而定。在那些支持开放枚举类型超出指定范围之外的语言中（例如C++和Go），为识别的值会被表示成所支持的整型。在使用封闭枚举类型的语言中（Java），使用枚举中的一个类型来表示未识别的值，并且可以使用所支持整型来访问。在其他情况下，如果解析的消息被序列号，未识别的值将保持原样。
关于如何在你的应用程序的消息中使用枚举的更多信息，请查看所选择的语言generated code guide

如果你想在它的父消息类型的外部重用这个消息类型，你需要以Parent.Type的形式使用它，如：

    message SomeOtherMessage {
      SearchResponse.Result result = 1;
    }

4、导入定义

对于给定的消息类型的默认类型URL是type.googleapis.com/packagename.messagename。
不同语言的实现会支持动态库以线程安全的方式去帮助封装或者解封装Any值。例如在java中，Any类型会有特殊的pack()和unpack()访问器，在C++中会有PackFrom()和UnpackTo()方法。

    // Storing an arbitrary message type in Any.
    NetworkErrorDetails details = ...;
    ErrorStatus status;
    status.add_details()->PackFrom(details);
     
    // Reading an arbitrary message from Any.
    ErrorStatus status = ...;
    for (const Any& detail : status.details()) {
      if (detail.Is<NetworkErrorDetails>()) {
        NetworkErrorDetails network_error;
        detail.UnpackTo(&network_error);
        ... processing network_error ...
      }
    }

目前，用于Any类型的动态库仍在开发之中
如果你已经很熟悉proto2语法，使用Any替换拓展

然后你可以增加oneof字段到 oneof 定义中. 你可以增加任意类型的字段, 但是不能使用repeated 关键字.
在产生的代码中, oneof字段拥有同样的 getters 和setters， 就像正常的可选字段一样. 也有一个特殊的方法来检查到底那个字段被设置. 你可以在相应的语言API指南中找到oneof API介绍.
Oneof 特性
设置oneof会自动清楚其它oneof字段的值. 所以设置多次后，只有最后一次设置的字段有值.

    SampleMessage message;
    message.set_name("name");
    CHECK(message.has_name());
    message.mutable_sub_message();   // Will clear name field.
    CHECK(!message.has_name());

如果解析器遇到同一个oneof中有多个成员，只有最会一个会被解析成消息。
oneof不支持repeated.
反射API对oneof 字段有效.

5、JSON 映射

原始链接：https://www.cnblogs.com/tohxyblog/p/8974763.html

上一篇 下一篇

猜你喜欢

热点阅读