Protobuf语言指南

²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]已经被占 用，该范围内的值已经被内部所使用，当然了你可以在内部应用中随意使用。如果你想在一些公共应用中进行自定义选项，你必须确保它是全局唯一的。可以通过[email protected]来获取全局唯一标识号。

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