Google Protobuf Java API详解
生成目标文件
1、Maven依赖
想要正常地使用生成的Java类,我们需要导入protobuf的依赖:
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>3.1.0</version>
</dependency>
2、Protobuf Java API
本文以GPS信号为例,Gps.proto文件如下:
syntax = "proto2";
option java_package = "com.test.bean";
option java_outer_classname = "AddressBookProtos";
message Person {
required string name = 1;
required int32 id = 2;
optional string email = 3;
enum PhoneType {
MOBILE = 0;
HOME = 1;
WORK = 2;
}
message PhoneNumber {
required string number = 1;
optional PhoneType type = 2 [default = HOME];
}
repeated PhoneNumber phones = 4;
}
message AddressBook {
repeated Person people = 1;
}
2.1 Builders 和 Messages
使用Protobuf生成的每一个java类中,都会包含两种内部类:Msg和Msg包含的Builder。(.proto文件中定义的每一个message都会生成一个Msg,每一个Msg都对应一个Builder)
在上面的GPS信号的例子中,是下面的几个类:
AddressBookProtos.AddressBook、AddressBookProtos.Person、AddressBookProtos.Person.PhoneNumber
AddressBookProtos.AddressBook.Builder、AddressBookProtos.Person.Builder、
AddressBookProtos.Person.PhoneNumber.Builder
这两个类提供不同的API。具体来说:
Builder提供了构建类、查询类的API(set、get、has、clear等方法)
Msg提供了查询、序列化、反序列化的API(不提供set方法)
固在使用时,我们一般遵循以下程序:
使用Builder构建Msg
使用Msg生成字节流
接收字节流,使用Msg反序列化生成Msg实例
读取Msg实例
2.1.1使用Builder构建Msg
Builder的每一个set、add方法都返回了一个Builder实例,所以可以像“程序流”一样使用Builder,如下:
public class Main {
public static void main(String[] args) {
//使用builder构建一个Person对象
AddressBookProtos.Person john =
AddressBookProtos.Person.newBuilder()
.setId(1234)
.setName("John Doe")
.setEmail("jdoe@example.com")
.addPhones(
//内部类PhoneNumber同样使用其Builder构建,但是注意,不需要调用build()方法
AddressBookProtos.Person.PhoneNumber.newBuilder()
.setNumber("555-4321")
.setType(AddressBookProtos.Person.PhoneType.HOME))
//build()结束整个程序流,返回Person对象
.build();
System.out.println(john);
}
}
同时需要注意到Builder和Msg提供的API的差异:
//Msg只提供了get和has方法
String email = john.getEmail();
boolean hasEmail = john.hasEmail();
//而builder提供了add/set、get、has和clear方法
AddressBookProtos.Person.Builder builder = AddressBookProtos.Person.newBuilder();
builder.setEmail("jdoe@example.com");
boolean hasEmail1 = builder.hasEmail();
String email1 = builder.getEmail();
builder.clearEmail();
除此之外,Builder和Msg都提供了isInitialized()方法,用于检查是否所有的required字段都已经设置。
2.1.2使用Msg进行序列化、反序列化
所有的Msg类(注意,如之前所提及,在我们的例子中,有三个Msg类)都提供了序列化和反序列化方法,包括:
序列化:
byte[] toByteArray():生成字节数组
void writeTo(OutputStream output):序列化并写入到指定的输出流中
反序列化:
static Person parseFrom(byte[] data):解析二进制数组,反序列化出指定对象
static Person parseFrom(InputStream input):解析输入流,反序列化出指定对象
例如:
public class Main {
public static void main(String[] args) {
//使用builder()Msg类
AddressBookProtos.Person john =
AddressBookProtos.Person.newBuilder()
.setId(1234)
.setName("John Doe")
.setEmail("jdoe@example.com")
.addPhones(
AddressBookProtos.Person.PhoneNumber.newBuilder()
.setNumber("555-4321")
.setType(AddressBookProtos.Person.PhoneType.HOME))
.build();
try {
//序列化
byte[] bytes = john.toByteArray();
//反序列化
System.out.println(AddressBookProtos.Person.parseFrom(bytes));
} catch (InvalidProtocolBufferException e) {
e.printStackTrace();
}
}
}
2.2拼接两个Msg
所有的Builder类都提供了一个特殊的方法:mergeFrom(Message other)。
这个方法会:
对于单字段,会用other的对应字段覆盖原msg
对于复合字段,会进行融合
对于repeated字段,会拼接列表
public class Main {
public static void main(String[] args) {
//使用builder()Msg类
AddressBookProtos.Person john =
AddressBookProtos.Person.newBuilder()
.setId(1234)
.setName("John Doe")
.setEmail("jdoe@example.com")
.addPhones(
AddressBookProtos.Person.PhoneNumber.newBuilder()
.setNumber("555-4321")
.setType(AddressBookProtos.Person.PhoneType.HOME))
.build();
AddressBookProtos.Person cai =
AddressBookProtos.Person.newBuilder()
.setId(1234)
.setName("CAI")
.setEmail("CAI@test.com")
.addPhones(
AddressBookProtos.Person.PhoneNumber.newBuilder()
.setNumber("12345678")
.setType(AddressBookProtos.Person.PhoneType.HOME))
.build();
AddressBookProtos.Person merge = john.toBuilder().mergeFrom(cai).build();
System.out.println(merge);
}
}
最后会输出:
name: "CAI"
id: 1234
email: "CAI@test.com"
phones {
number: "555-4321"
type: HOME
}
phones {
number: "12345678"
}
3.使用Protobuf进行永久存储
有时候我们希望把一些数据以二进制的形式永久存储,以压缩其占据的空间。这时,码流的压缩程度、文件的读写速度、码流的错误率等都是我们需要考虑的问题。
Java自带的API,一方面在序列化的效率、码流的压缩程度上表现不佳,另一方面在文件读取方面也乏善可陈。而Protobuf提供了高效的压缩、写入和读取的API。
3.1写入流和读取解析流
写入文件主要使用的方法是:
writeDelimitedTo(OutputStream output)
这个方法和 writeTo(OutputStream)类似,但是他会在写入数据之前,先以一个varint写入整个消息体的长度。这样我们在解析时,就可以方便地读取出数据,也可以验证数据的完整性。
读取文件主要使用的方法是:
parseDelimitedFrom(InputStream in)
这个方法对应的,会在解析之前,先读取一个varint,看整个消息体的长度,然后再进行读取。使用这个方法读取的效率非常高(亲测比直接使用BufferedInputStream要快的多),但同时也会占据更多的内存。
例如;
public class Main {
public static void main(String[] args) {
//使用builder()Msg类
AddressBookProtos.Person john =
AddressBookProtos.Person.newBuilder()
.setId(1234)
.setName("John Doe")
.setEmail("jdoe@example.com")
.addPhones(
AddressBookProtos.Person.PhoneNumber.newBuilder()
.setNumber("555-4321")
.setType(AddressBookProtos.Person.PhoneType.HOME))
.build();
File file = new File("persons.data");
OutputStream outputStream = null;
//先写入文件
try {
outputStream = new FileOutputStream(file);
for (int i = 0; i < 100; i++) {
john.writeDelimitedTo(outputStream);
}
} catch (FileNotFoundException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} finally {
try {
outputStream.close();
} catch (IOException e) {
e.printStackTrace();
}
}
InputStream inputStream;
//读取文件
try {
inputStream = new FileInputStream(file);
AddressBookProtos.Person person = AddressBookProtos.Person.parseDelimitedFrom(inputStream);
System.out.println(person);
int count = 1;
while (inputStream.available()!=0){
person = AddressBookProtos.Person.parseDelimitedFrom(inputStream);
count++;
}
System.out.println(count);
} catch (FileNotFoundException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}
}
}
当然在大文件读写的时候,还需要注意及时清理内存,这里不再赘述。
4.和JSON格式相互转换
在web项目中,和前台交互时,我们通常还是使用JSON格式。这就要求我们能在protobuf和json之间进行转换。
注意:
并没有测试过,使用protobuf的JSON API是否会比常用的fastJson、Jackson等等更快,其效率可能更低
如果不使用protobuf提供的JSON API,而使用fastJson等,直接序列化Msg对象,会报错。如果希望使用第三方的JSON API,可以重新定义一个实体类,抽取需要的字段。
4.1依赖
导入额外依赖
<!-- https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java-util -->
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java-util</artifactId>
<version>3.1.0</version>
</dependency>
4.2使用
public class Main {
public static void main(String[] args) {
//使用builder()Msg类
AddressBookProtos.Person john =
AddressBookProtos.Person.newBuilder()
.setId(1234)
.setName("John Doe")
.setEmail("jdoe@example.com")
.addPhones(
AddressBookProtos.Person.PhoneNumber.newBuilder()
.setNumber("555-4321")
.setType(AddressBookProtos.Person.PhoneType.HOME))
.build();
//获取Printer对象用于生成JSON字符串
JsonFormat.Printer printer = JsonFormat.printer();
//获取parser对象用于解析JSON字符串
JsonFormat.Parser parser = JsonFormat.parser();
try {
//生成JSON字符串
String jsonStr = printer.print(john);
System.out.println(jsonStr);
//解析JSON字符串
//解析方法接收一个JSON字符串,并把其写入指定的builder
AddressBookProtos.Person.Builder builder = AddressBookProtos.Person.newBuilder();
parser.merge(jsonStr,builder);
AddressBookProtos.Person person = builder.build();
System.out.println(person);
} catch (InvalidProtocolBufferException e) {
e.printStackTrace();
}
}
}