proto文件来预先定义的消息格式。数据包是按照proto文件所定义的消息格式完成二进制码流的编码和解码。proto文件,简单地说,就是一个消息的协议文件,这个协议文件的后缀文件名为“.proto”。 作为演示,下面介绍一个非常简单的proto文件:仅仅定义一个消息结构体,并且该消息结构体也非常简单,仅包含两个字段。实例如下:
// [开始头部声明]
syntax = "proto3";
packagecom.crazymakercircle.netty.protocol;
// [结束头部声明]
// [开始 java选项配置]
option java_package = "com.crazymakercircle.netty.protocol";
option java_outer_classname = "MsgProtos";
// [结束 java选项配置]
// [开始消息定义]
message Msg {
uint32 id = 1; //消息ID
string content = 2;//消息内容
}
// [结束消息定义]
在“.proto”文件的头部声明中,需要声明“.proto”所使用的Protobuf协议版本,这里使用的是"proto3"。也可以使用旧一点的版本"proto2",两个版本的消息格式有一些细微的不同。
默认的协议版本为"proto2"。
Protobuf支持很多语言,所以它为不同的语言提供了一些可选的声明选项,选项的前面有option关键字。
“java_package”选项的作用为:在生成“proto”文件中消息的POJO类和Builder(构造者)的Java代码时,将Java代码放入指定的package中。
“java_outer_classname”选项的作用为:在生成“proto”文件所对应Java代码时,所生产的Java外部类的名称。 在“proto”文件中,使用message这个关键字来定义消息的结构体。在生成“proto”对应的Java代码时,
每个具体的消息结构体都对应于一个最终的Java POJO类。消息结构体的字段对应到POJO类的属性。也就是说,每定义一个“message”结构体相当于声明一个Java中的类。并且message中可以内嵌message,就像java的内部类一样。 每一个消息结构体可以有多个字段。定义一个字段的格式,简单来说就是“类型名称=编号”。
例如“string content=2;”,表示该字段是string类型,名为content,序号为2。字段序号表示为:在Protobuf数据包的序列化、反序列化时,该字段的具体排序。 在每一个“.proto”文件中,可以声明多个“message”。大部分情况下,会把有依赖关系或者包含关系的message消息结构体写入一个.proto文件。将那些没有关联关系的message消息结构体,分别写入不同的文件,这样便于管理。
原文链接:https://blog.csdn.net/qq_41358574/article/details/123903840
一、基本结构
proto文件主要由以下几部分组成:
- 语法版本(Syntax):
- 指定proto文件所使用的语法版本,目前常用的是
proto3
。这一声明必须放在proto文件的第一行。
- 指定proto文件所使用的语法版本,目前常用的是
- 包名(Package):
- 指定生成的代码所在的包(对于C++来说是namespace)。包名通常用于防止命名冲突,并且与生成的代码的组织结构紧密相关。
- 导入语句(Import):
- 用于导入其他proto文件,以实现模块化和复用。
- 选项(Option):
- 用于定义一些全局的或特定于文件的选项,如Java类文件的生成规则等。
- 消息(Message):
- 定义数据结构的主要方式,类似于面向对象编程中的类。在消息中可以定义字段(field),指定字段的类型和名称,还可以添加注释等元数据。
- 枚举(Enum):
- 定义了一组具名的整数常量,可以作为消息字段的取值范围或者服务方法的选项。
- 服务(Service):
- 定义了一组可供远程调用的方法(method)。每个方法都有输入和输出参数,可以在服务中定义多个方法。
二、消息(Message)
在proto文件中,消息是定义数据结构的主要方式。每个消息由一组字段组成,每个字段都有一个唯一的标识符(通常是一个整数)和一个类型。字段类型可以是基本类型(如int32、string等)、枚举类型、其他消息类型等。
字段的修饰符包括:
- 可选字段(Optional):在proto3中,所有字段默认都是可选的,不再需要使用
optional
关键字进行修饰。但在proto2中,optional
关键字用于表示该字段为可选项,可以传也可以不传。 - 重复字段(Repeated):表示该字段可以接收或返回多个值,类似于数组或列表。
- 必需字段(Required):在proto2中,
required
关键字用于表示该字段为必需字段,不设置会导致编解码异常。但在proto3中,required
修饰符已被废弃,不再推荐使用。
三、枚举(Enum)
枚举类型定义了一组具名的整数常量,用于表示一组有限的取值。枚举值在定义时会被赋予一个唯一的整数编号,但在使用时通常是通过枚举名来引用。
四、服务(Service)
服务定义了一组远程调用的方法。每个方法都有输入和输出参数,输入参数和输出参数都是之前定义的消息类型。服务通常与RPC(远程过程调用)系统结合使用,以实现分布式系统的通信。
五、编译与生成代码
proto文件可以通过protobuf编译器(protoc)编译成多种编程语言的源代码,包括Java、C++、Python等。生成的代码包含数据访问类和序列化/反序列化代码,使得在不同编程语言中使用相同的数据结构和接口定义成为可能。
六、示例
以下是一个简单的proto文件示例:
syntax = "proto3";
package example;
// 定义消息类型
message Person {
string name = 1;
int32 age = 2;
repeated string hobbies = 3;
}
// 定义枚举类型
enum Gender {
UNKNOWN = 0;
MALE = 1;
FEMALE = 2;
}
// 定义服务
service PersonService {
rpc GetPersonById(PersonIdRequest) returns (PersonResponse);
}
// 定义服务方法的输入参数
message PersonIdRequest {
int32 id = 1;
}
// 定义服务方法的输出参数
message PersonResponse {
Person person = 1;
string message = 2;
}
在这个示例中,我们定义了一个Person
消息类型,包含姓名、年龄和爱好三个字段;定义了一个Gender
枚举类型,包含三个取值;定义了一个PersonService
服务,包含一个GetPersonById
方法,该方法接受一个PersonIdRequest
作为输入参数,返回一个PersonResponse
作为输出参数。