Protobuf语言指南

分类:CentOS运维 阅读:93131 次

²message_set_wire_format(message option):如果该值被设置为true,该消息将使用一种不同的二进制格式来与Google内部的MessageSet的老格式相兼容。对于Google外部的用户来说,该选项将不会被用到。如下所示:

message Foo {

option message_set_wire_format = true;

extensions 4 to max;

}

²packed(field option): 如果该选项在一个整型基本类型上被设置为真,则采用更紧凑的编码方式。当然使用该值并不会对数值造成任何损失。在2.3.0版本之前,解析器将会忽略那些 非期望的包装值。因此,它不可能在不破坏现有框架的兼容性上而改变压缩格式。在2.3.0之后,这种改变将是安全的,解析器能够接受上述两种格式,但是在 处理protobuf老版本程序时,还是要多留意一下。

²deprecated(field option): 如果该选项被设置为true,表明该字段已经被弃用了,在新代码中不建议使用。在多数语言中,这并没有实际的含义。在java中,它将会变成一个@Deprecated注释。也许在将来,其它基于语言声明的代码在生成时也会如此使用,当使用该字段时,编译器将自动报警。如:

Ø自定义选项

ProtocolBuffers允许自定义并使用选项。该功能应该属于一个高级特性,对于大部分人是用不到的。由于options是定在google/protobuf/descriptor.proto中的,因此你可以在该文件中进行扩展,定义自己的选项。如:

import "google/protobuf/descriptor.proto";

extend google.protobuf.MessageOptions {

optional string my_option = 51234;

}

message MyMessage {

option (my_option) = "Hello world!";

}

在上述代码中,通过对MessageOptions进行扩展定义了一个新的消息级别的选项。当使用该选项时,选项的名称需要使用()包裹起来,以表明它是一个扩展。在C++代码中可以看出my_option是以如下方式被读取的。

在Java代码中的读取方式如下:

正如上面的读取方式,定制选项对于Python并不支持。定制选项在protocol buffer语言中可用于任何结构。下面就是一些具体的例子:

import "google/protobuf/descriptor.proto";

extend google.protobuf.FileOptions {

optional string my_file_option = 50000;

}

extend google.protobuf.MessageOptions {

optional int32 my_message_option = 50001;

}

extend google.protobuf.FieldOptions {

optional float my_field_option = 50002;

}

extend google.protobuf.EnumOptions {

optional bool my_enum_option = 50003;

}

extend google.protobuf.EnumValueOptions {

optional uint32 my_enum_value_option = 50004;

}

extend google.protobuf.ServiceOptions {

optional MyEnum my_service_option = 50005;

}

extend google.protobuf.MethodOptions {

optional MyMessage my_method_option = 50006;

}

option (my_file_option) = "Hello world!";

message MyMessage {

option (my_message_option) = 1234;

optional int32 foo = 1 [(my_field_option) = 4.5];

optional string bar = 2;

}

enum MyEnum {

option (my_enum_option) = true;

FOO = 1 [(my_enum_value_option) = 321];

BAR = 2;

}

message RequestType {}

message ResponseType {}

service MyService {

option (my_service_option) = FOO;

rpc MyMethod(RequestType) returns(ResponseType) {

// Note: my_method_option has type MyMessage. We can set each field

// within it using a separate "option" line.

option (my_method_option).foo = 567;

option (my_method_option).bar = "Some string";

}

}

注:如果要在该选项定义之外使用一个自定义的选项,必须要由包名 + 选项名来定义该选项。如:

// foo.proto

import "google/protobuf/descriptor.proto";

package foo;

extend google.protobuf.MessageOptions {

optional string my_option = 51234;

}

// bar.proto

import "foo.proto";

package bar;

message MyMessage {

option (foo.my_option) = "Hello world!";

}

最后一件事情需要注意:因为自定义选项是可扩展的,它必须象其它的域或扩展一样来定义标识号。正如上述示例,[50000-99999]已经被占 用,该范围内的值已经被内部所使用,当然了你可以在内部应用中随意使用。如果你想在一些公共应用中进行自定义选项,你必须确保它是全局唯一的。可以通过protobuf-global-extension-registry@google.com来获取全局唯一标识号。

l生成访问类

可以通过定义好的.proto文件来生成Java、Python、C++代码,需要基于.proto文件运行protocol buffer编译器protoc。运行的命令如下所示:

·IMPORT_PATH声明了一个.proto文件所在的具体目录。如果忽略该值,则使用当前目录。如果有多个目录则可以对--proto_path写多次,它们将会顺序的被访问并执行导入。-I=IMPORT_PATH是它的简化形式。

·当然也可以提供一个或多个输出路径:

o--cpp_out在目标目录DST_DIR中产生C++代码,可以在 http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/reference /cpp-generated.html中查看更多。

o--java_out在目标目录DST_DIR中产生Java代码,可以在 http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/reference /java-generated.html中查看更多。

o--python_out在目标目录DST_DIR 中产生Python代码,可以在http://code.google.com/intl/zh-CN/apis/protocolbuffers /docs/reference/python-generated.html中查看更多。

作为一种额外的使得,如果DST_DIR是以.zip或.jar结尾的,编译器将输出结果打包成一个zip格式的归档文件。.jar将会输出一个 Java JAR声明必须的manifest文件。注:如果该输出归档文件已经存在,它将会被重写,编译器并没有做到足够的智能来为已经存在的归档文件添加新的文 件。

·你必须提供一个或多个.proto文件作为输入。多个.proto文件能够一次全部声明。虽然这些文件是相对于当前目录来命名的,每个文件必须在一个IMPORT_PATH中,只有如此编译器才可以决定它的标准名称。

from:http://www.open-open.com/home/space.php?uid=37924&do=blog&id=5873

=========================================================

ProtoBuf开发者指南:http://gashero.yeax.com/?p=108

官方:http://code.google.com/p/protobuf/

语言指南
http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html

风格
http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/style.html


把命令大全装进口袋

微信关注