Spring Boot 项目中使用 Protobuf 序列化

Spring Boot项目中使用Protobuf序列化

1. Protobuf 简介与优势

Protocol Buffers（Protobuf）是 Google 推出的一种语言无关、平台无关、可扩展 的二进制序列化协议。相比 JSON/XML，它通常可将数据体积压缩 50% 以上 （极端场景达 90%），解析速度比反射式 JSON 解析器快 5-10 倍 ，同时内置 Schema Evolution 机制，确保新旧服务无缝升级。特别适用于微服务通信、消息队列、IoT 与移动端等对性能及带宽敏感的场景。

2. 项目结构与依赖配置

2.1 项目结构说明

bash 复制代码

src
│   ├── main
│   │   ├── java
│   │   │   └── cn
│   │   │       └── protobuf
│   │   │           ├── demo
│   │   │           │   └── UserProtosSamples.java    # 示例代码
│   │   │           ├── proto
│   │   │           │   └── UserProtos.java           # 编译生成的类
│   │   │           └── ProtobufApplication.java      # Spring Boot入口
│   │   ├── proto
│   │   │   └── user.proto                           # Protobuf schema定义
│   │   └── resources
│   │       └── bootstrap.yml                        # 配置文件
│   └── test
│       └── java
pom.xml

2.2 Maven 依赖与插件配置

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>springboot-protobuf</artifactId>
    <version>1.0-SNAPSHOT</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.0.2</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        <spring-boot.version>3.0.2</spring-boot.version>
        <spring-cloud.version>2022.0.0</spring-cloud.version>
        <spring-cloud-alibaba.version>2022.0.0.0</spring-cloud-alibaba.version>

        <protobuf.version>3.25.6</protobuf.version>
        <protobuf-plugin.version>0.6.1</protobuf-plugin.version>
    </properties>


    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-alibaba-dependencies</artifactId>
                <version>${spring-cloud-alibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>

        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-bootstrap</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>


        <!--任何使用protobuf的项目都必须引入-->
        <dependency>
            <groupId>com.google.protobuf</groupId>
            <artifactId>protobuf-java</artifactId>
            <version>${protobuf.version}</version>
        </dependency>
        <!--需要把protobuf对象直接转成JSON、或接收JSON再转回protobuf时使用-->
        <dependency>
            <groupId>com.google.protobuf</groupId>
            <artifactId>protobuf-java-util</artifactId>
            <version>${protobuf.version}</version>
        </dependency>



    </dependencies>


    <build>
        <finalName>springboot-protobuf</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.10.1</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring-boot.version}</version>
                <configuration>
                    <mainClass>cn.protobuf.ProtobufApplication</mainClass>
                </configuration>
                <executions>
                    <execution>
                        <id>repackage</id>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>


            <plugin>
                <groupId>org.xolstice.maven.plugins</groupId>
                <artifactId>protobuf-maven-plugin</artifactId>
                <version>0.6.1</version>
                <configuration>
                    <!--告诉插件去哪里找 .proto 源文件${basedir}就是Maven项目的根目录,因此它会扫描 <项目根>/src/main/proto/*.proto-->
                    <protoSourceRoot>${basedir}/src/main/proto</protoSourceRoot>
                    <!--自动下载并调用 protoc 编译器-->
                    <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
                    <!--自动下载gRPC Java 插件（protoc-gen-grpc-java）用于根据 .proto 中的 service 定义生成 gRPC 服务端/客户端的接口和桩代码（Stub） 同样根据操作系统自动选可执行文件-->
                    <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.43.1:exe:${os.detected.classifier}</pluginArtifact>
                    <!--生成的 Java 源码输出目录 这里设为 src/main/java, 生成的类会跟手写代码放在一起；IDE 刷新后即可直接引用 -->
                    <outputDirectory>src/main/java</outputDirectory>
                    <!--构建前不清空输出目录，避免误删你已有的源码 设为 true 则每次都会先删再生成-->
                    <clearOutputDirectory>false</clearOutputDirectory>
                    <!--给gRPC插件起一个内部id,protobuf-maven-plugin 用它区分不同自定义插件,可保持默认即可-->
                    <pluginId>grpc-java</pluginId>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>compile</goal>
                            <goal>compile-custom</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>


        </plugins>
        <resources>
            <resource>
                <directory>src/main/java</directory>
                <excludes>
                    <exclude>**/*.java</exclude>
                </excludes>
            </resource>
            <resource>
                <directory>src/main/resources</directory>
            </resource>
        </resources>


        <!--
            让 Maven 在构建最开始时自动检测当前操作系统和 CPU 架构，并生成一组以 os.detected.* 开头的属性,供后续插件或依赖使用
            为了 protobuf-maven-plugin 里的这两行占位符${os.detected.classifier}
            没有 os-maven-plugin,${os.detected.classifier} 无法解析.Maven 就会报错找不到对应平台的可执行文件
        -->
        <extensions>
            <extension>
                <groupId>kr.motd.maven</groupId>
                <artifactId>os-maven-plugin</artifactId>
                <version>1.7.1</version>
            </extension>
        </extensions>



    </build>

</project>

2.3 其他文件代码

① user.proto

ini 复制代码

syntax = "proto3";  //声明proto3语法版本（最新主流版本）  
package cn.proto.demo; //proto层面的包名,主要用于避免不同,proto文件里消息重名  
  
option java_package = "cn.protobuf.proto"; //Java真正生成的包路径,编译后生成的类都在这个Java包下  
option java_outer_classname = "UserProtos";  //生成的最外层Java类名,默认会把所有消息放在UserProtos.java里  
  
//定义一个地址结构体，含3个字符串字段。  
//数字1、2、3 是字段编号（二进制里用来识别字段,必须唯一且尽量小）  
message Address {  
  string street  = 1;  
  string city    = 2;  
  string zip     = 3;  
}  
  
message User {  
  //基本标量类型：int64、string、int32  
  int64  id          = 1;  
  string name        = 2;  
  string email       = 3;  
  int32  age         = 4;  
  //repeated → 表示数组/List  在Java中会变成List<Address>  
  repeated Address addresses = 5;  
  //同样是数组,但加了[packed = true]：把所有int64打包成紧凑二进制,节省空间Java中仍是List<Long>  
  repeated int64  scores     = 6 [packed = true];  
  //map类型，等价于Java的 Map<String, String>  map<string, string> ext = 7;  
}

② ProtobufApplication.java

java 复制代码

package cn.protobuf;  
  
  
import org.springframework.boot.SpringApplication;  
import org.springframework.boot.autoconfigure.SpringBootApplication;  
  
@SpringBootApplication  
public class ProtobufApplication {  
    public static void main(String[] args) {  
        SpringApplication.run(ProtobufApplication.class, args);  
    }  
}

③ bootstrap.yml

yml 复制代码

server:  
  port: 10001

2.4 编译生成 UserProtos.java

在上面代码准备就绪后执行执行 mvn compile 命令 , 就可以生成 UserProtos.java,

我这里生成的UserProtos.java, 有2912行, 就不放代码了

2.5 测试 UserProtos.java

UserProtosSamples.java

java 复制代码

package cn.protobuf.demo;  
  
import cn.protobuf.proto.UserProtos;  
import com.google.protobuf.util.JsonFormat;  
  
  
  
public final class UserProtosSamples {  
  
    public static void main(String[] args) throws Exception {  
        UserProtos.User user = buildSampleUser();     // ① 构造  
        byte[] bytes = serialize(user);               // ② 序列化  
        UserProtos.User parsed = deserialize(bytes);  // ③ 反序列化  
        printUser(parsed);                            // ④ 打印内容  
        String json = toJson(parsed);                 // ⑤ protobuf → JSON        UserProtos.User fromJson = fromJson(json);    // ⑥ JSON → protobuf        printUser(fromJson);                          // ⑦ 再打印一次  
    }  
  
    // ① 构造示例 User    public static UserProtos.User buildSampleUser() {  
        return UserProtos.User.newBuilder()  
                .setId(1L)  
                .setName("Tom")  
                .setEmail("tom@example.com")  
                .setAge(18)  
                .addAddresses(UserProtos.Address.newBuilder()  
                        .setStreet("中关村大街")  
                        .setCity("北京")  
                        .setZip("100080")  
                        .build())  
                .addScores(90L)  
                .addScores(95L)  
                .putExt("vip", "true")  
                .build();  
    }  
  
    // ② 序列化：User → byte[]  
    public static byte[] serialize(UserProtos.User user) {  
        return user.toByteArray();  
    }  
  
    // ③ 反序列化：byte[] → User  
    public static UserProtos.User deserialize(byte[] bytes) throws Exception {  
        return UserProtos.User.parseFrom(bytes);  
    }  
  
    // ④ 打印 User 的字段、地址列表、扩展 map    public static void printUser(UserProtos.User user) {  
        System.out.println("----- User -----");  
        System.out.printf("id=%d, name=%s, email=%s, age=%d%n",  
                user.getId(), user.getName(), user.getEmail(), user.getAge());  
        for (UserProtos.Address addr : user.getAddressesList()) {  
            System.out.printf("  address: %s, %s, %s%n",  
                    addr.getStreet(), addr.getCity(), addr.getZip());  
        }  
        user.getExtMap().forEach((k, v) ->  
                System.out.printf("  ext[%s]=%s%n", k, v));  
    }  
  
    // ⑤ protobuf → JSON    public static String toJson(UserProtos.User user) throws Exception {  
        return JsonFormat.printer().print(user);  
    }  
  
    // ⑥ JSON → protobuf    public static UserProtos.User fromJson(String json) throws Exception {  
        UserProtos.User.Builder builder = UserProtos.User.newBuilder();  
        JsonFormat.parser().merge(json, builder);  
        return builder.build();  
    }  
  
    private UserProtosSamples() {} // 防止实例化  
}

执行后输出:

sql 复制代码

----- User -----
id=1, name=Tom, email=tom@example.com, age=18
  address: 中关村大街, 北京, 100080
  ext[vip]=true
----- User -----
id=1, name=Tom, email=tom@example.com, age=18
  address: 中关村大街, 北京, 100080
  ext[vip]=true

Process finished with exit code 0