google protobuf definition service (service)

l Define Service (Service)

If you want to use the message type in the RPC (remote method call) system, you can define an RPC service interface in the .proto file, and the protocol buffer compiler will generate service interface codes and stubs according to the different languages selected. For example, if you want to define an RPC service and have a method that can receive SearchRequest and return a SearchResponse, you can define the following in the .proto file:

service SearchService {

rpc Search (SearchRequest) returns (SearchResponse);

}

The protocol compiler will generate an abstract interface SearchService and a corresponding stub implementation. The stub points all calls to RpcChannel, which is an abstract interface that must be implemented in the RPC system. For example, RpcChannel can be implemented to complete the serialization of the message and send it to a server via HTTP. In other words, the generated stub provides a type-safe interface to complete RPC calls based on protocolbuffer, rather than restricting you to a specific RPC implementation. The code in C++ is as follows:

using google::protobuf;

protobuf::RpcChannel* channel;
protobuf::RpcController* controller;
SearchService* service;
SearchRequest request;
SearchResponse response;

void DoSearch() {
// You provide classes MyRpcChannel and MyRpcController, which implement
// the abstract interfaces protobuf::RpcChannel and protobuf::RpcController.
channel = new MyRpcChannel("somehost.example.com:1234");
controller = new MyRpcController;

// The protocol compiler generates the SearchService class based on the
// definition given above.

service = new SearchService::Stub(channel);
// Set up the request.
request.set_query("protocol buffers");

// Execute the RPC.
service->Search(controller, request, response, protobuf::NewCallback(&Done));
}

void Done() {
delete service;
delete channel;
delete controller;
}

All service classes must implement the Service interface, which provides a way to call specific methods, that is, you do not need to know the method name and its input and output types during compilation. On the server side, it can be used to implement an RPC Server through service registration.

using google::protobuf;

class ExampleSearchService : public SearchService {
public:
void Search(protobuf::RpcController* controller,
const SearchRequest* request,
SearchResponse* response,
protobuf::Closure* done) {
if (request->query() == "google") {
response->add_result()->set_url("http://www.google.com");
} else if (request->query() == "protocol buffers") {
response->add_result()->set_url("http://protobuf.googlecode.com");
}
done->Run();
}
};

int main() {
// You provide class MyRpcServer. It does not have to implement any
// particular interface; this is just an example.
MyRpcServer server;

protobuf::Service* service = new ExampleSearchService;
server.ExportOnPort(1234, service);
server.Run();

delete service;
return 0;
}

l Options

A series of options can be marked when defining the .proto file. Options does not change the meaning of the entire document statement, but it can affect the way it is handled in a specific environment. The full range of available options can be google/protobuf/descriptor.protofound here.

Some options are file-level, meaning that they can be applied to the outermost scope and are not included in any message, enum, or service definition. Some options are at the message level, which means they can be used inside the message definition. Of course, some options can be applied to domains, enum types, enum values, service types, and service methods. So far, there is no effective option that can be applied to all types.

Here are some commonly used choices:

² java_package (file option): This option indicates the package where the java class is generated. If java_package is not explicitly declared in the .proto file, the default package name is used. Of course, the java package name generated by the default method is not the best method, and it is sorted according to the reverse order of the application name. If you do not need to generate java code, this option will have no effect. Such as:

option java_package = "com.example.foo";

² java_outer_classname (file option): 该选项表明想要生成Java类的名称。如果在.proto文件中没有明确的java_outer_classname定义，生成的class名称将会根据.proto文件的名称采用驼峰式的命名方式进行生成。如（foo_bar.proto生成的java类名为FooBar.java）,如果不生成java代码，则该选项不起任何作用。如：

option java_outer_classname = "Ponycopter";

² optimize_for (fileoption): 可以被设置为 SPEED, CODE_SIZE,or LITE_RUNTIME。这些值将通过如下的方式影响C++及java代码的生成：

· SPEED (default): protocol buffer编译器将通过在消息类型上执行序列化、语法分析及其他通用的操作。这种代码是最优的。

· CODE_SIZE: protocol buffer编译器将会产生最少量的类，通过共享或基于反射的代码来实现序列化、语法分析及各种其它操作。采用该方式产生的代码将比SPEED要少得多，但是操作要相对慢些。当然实现的类及其对外的API与SPEED模式都是一样的。这种方式经常用在一些包含大量的.proto文件而且并不盲目追求速度的应用中。

· LITE_RUNTIME: protocol buffer编译器依赖于运行时核心类库来生成代码（即采用libprotobuf-lite 替代libprotobuf）。这种核心类库由于忽略了一些描述符及反射，要比全类库小得多。这种模式经常在移动手机平台应用多一些。编译器采用该模式产生的方法实现与SPEED模式不相上下，产生的类通过实现 MessageLite接口，但它仅仅是Messager接口的一个子集。

option optimize_for = CODE_SIZE;

² cc_generic_services, java_generic_services, py_generic_services (file options): 在C++、java、python中protocol buffer编译器是否应该基于服务定义产生抽象服务代码。由于历史遗留问题，该值默认是true。但是自2.3.0版本以来，它被认为通过提供代码生成器插件来对RPC实现更可取，而不是依赖于“抽象”服务。

// This file relies on plugins to generate service code.

option cc_generic_services = false;

option java_generic_services = false;

option py_generic_services = false;

² 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老版本程序时，还是要多留意一下。

repeated int32 samples = 4 [packed=true];

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

optional int32 old_field = 6 [deprecated=true];

Ø 自定义选项

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是以如下方式被读取的。

string value = MyMessage::descriptor()->options().GetExtension(my_option);

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

String value = MyProtoFile.MyMessage.getDescriptor().getOptions().getExtension(MyProtoFile.myOption);

正如上面的读取方式，定制选项对于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。运行的命令如下所示：

protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_out=DST_DIR path/to/file.proto

· 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中，只有如此编译器才可以决定它的标准名称。

l 定义服务(Service)

如果想要将消息类型用在RPC(远程方法调用)系统中，可以在.proto文件中定义一个RPC服务接口，protocol buffer编译器将会根据所选择的不同语言生成服务接口代码及存根。如，想要定义一个RPC服务并具有一个方法，该方法能够接收 SearchRequest并返回一个SearchResponse，此时可以在.proto文件中进行如下定义：

service SearchService {

rpc Search (SearchRequest) returns (SearchResponse);

}

protocol编译器将产生一个抽象接口SearchService以及一个相应的存根实现。存根将所有的调用指向RpcChannel，它是一个抽象接口，必须在RPC系统中对该接口进行实现。如，可以实现RpcChannel以完成序列化消息并通过HTTP方式来发送到一个服务器。换句话说，产生的存根提供了一个类型安全的接口用来完成基于protocolbuffer的RPC调用，而不是将你限定在一个特定的RPC的实现中。C++中的代码如下所示：

using google::protobuf;

protobuf::RpcChannel* channel;
protobuf::RpcController* controller;
SearchService* service;
SearchRequest request;
SearchResponse response;

// The protocol compiler generates the SearchService class based on the
// definition given above.

service = new SearchService::Stub(channel);
// Set up the request.
request.set_query("protocol buffers");

// Execute the RPC.
service->Search(controller, request, response, protobuf::NewCallback(&Done));
}

void Done() {
delete service;
delete channel;
delete controller;
}

所有service类都必须实现Service接口，它提供了一种用来调用具体方法的方式，即在编译期不需要知道方法名及它的输入、输出类型。在服务器端，通过服务注册它可以被用来实现一个RPC Server。

l 选项（Options）

在定义.proto文件时能够标注一系列的options。Options并不改变整个文件声明的含义，但却能够影响特定环境下处理方式。完整的可用选项可以在google/protobuf/descriptor.proto找到。

一些选项是文件级别的，意味着它可以作用于最外范围，不包含在任何消息内部、enum或服务定义中。一些选项是消息级别的，意味着它可以用在消息定义的内部。当然有些选项可以作用在域、enum类型、enum值、服务类型及服务方法中。到目前为止，并没有一种有效的选项能作用于所有的类型。

如下就是一些常用的选择：

² java_package (file option): 这个选项表明生成java类所在的包。如果在.proto文件中没有明确的声明java_package，就采用默认的包名。当然了，默认方式产生的 java包名并不是最好的方式，按照应用名称倒序方式进行排序的。如果不需要产生java代码，则该选项将不起任何作用。如：

option java_package = "com.example.foo";

option java_outer_classname = "Ponycopter";

² optimize_for (fileoption): 可以被设置为 SPEED, CODE_SIZE,or LITE_RUNTIME。这些值将通过如下的方式影响C++及java代码的生成：

· SPEED (default): protocol buffer编译器将通过在消息类型上执行序列化、语法分析及其他通用的操作。这种代码是最优的。

option optimize_for = CODE_SIZE;

// This file relies on plugins to generate service code.

option cc_generic_services = false;

option java_generic_services = false;

option py_generic_services = false;

message Foo {

option message_set_wire_format = true;

extensions 4 to max;

}

repeated int32 samples = 4 [packed=true];

optional int32 old_field = 6 [deprecated=true];

Ø 自定义选项

import "google/protobuf/descriptor.proto";

extend google.protobuf.MessageOptions {

optional string my_option = 51234;

}

message MyMessage {

option (my_option) = "Hello world!";

}

string value = MyMessage::descriptor()->options().GetExtension(my_option);

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

String value = MyProtoFile.MyMessage.getDescriptor().getOptions().getExtension(MyProtoFile.myOption);

正如上面的读取方式，定制选项对于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!";

}

l 生成访问类

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

protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_out=DST_DIR path/to/file.proto

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

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中查看更多。