Google Protobuf Java API详解

阎自怡

2023-12-01

Google Protobuf Java API详解
转发自：https://my.oschina.net/pierrecai/blog/1329878

参考之前的教程：https://my.oschina.net/pierrecai/blog/873359 即可顺利构建出使用Protobuf进行序列化/反序列化所需的java类。

本文将更详细地讲解Google Protobuf提供的Java API，即我们可以通过生成的java类做什么。

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();

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();
        }
    }
}

如果希望使用流的话，调用流的api即可，这里不再举例。

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();
        }
    }
}