java使用protobuf-maven-plugin的插件編譯proto文件詳解

更新時間：2025年07月08日 11:03:56 作者：程序猿CKeen

這篇文章主要介紹了java使用protobuf-maven-plugin的插件編譯proto文件,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教

protobuf文件作為數(shù)據(jù)傳輸和存儲的協(xié)議

已經(jīng)使用的越來越廣泛了。使用protobuf有如下的優(yōu)勢：

protocol buffers 是一種語言無關(guān)、平臺無關(guān)、可擴(kuò)展的序列化結(jié)構(gòu)數(shù)據(jù)。
相比XML，有編碼后體積更小，編解碼速度更快的優(yōu)勢；相比于 Json，Protobuf 有更高的轉(zhuǎn)化效率，時間效率和空間效率都是 JSON 的 3-5 倍。
protobuf還提供了不同語言的protoc的編譯工具，使用簡單的編譯指令就更生成支持不同語言的調(diào)用包。

主要介紹在java使用maven編譯proto文件的插件

protobuf-maven-plugin

我們在工程目錄下創(chuàng)建一個lib的module，用來統(tǒng)一管理proto的包和編譯后生成的java包。然后我們在跟java同級的目錄創(chuàng)建proto的文件夾，用來存放.proto文件（如下圖）

在pom的build中配置proto的編譯插件

// pom.xml

<build>
        <extensions>
            <extension>
                <groupId>kr.motd.maven</groupId>
                <artifactId>os-maven-plugin</artifactId>
                <version>${os.plugin.version}</version>
            </extension>
        </extensions>
        <plugins>
            <plugin>
                <groupId>org.xolstice.maven.plugins</groupId>
                <artifactId>protobuf-maven-plugin</artifactId>
                <version>${protobuf.plugin.version}</version>
                <extensions>true</extensions>
                <configuration>
                    <!-- 工具版本 -->
                   <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
                    <!--默認(rèn)值，proto源文件路徑-->
                    <protoSourceRoot>${project.basedir}/src/main/proto</protoSourceRoot>
                    <!--默認(rèn)值，proto目標(biāo)java文件路徑-->
                    <outputDirectory>${project.basedir}/src/main/java</outputDirectory>
                    <!--設(shè)置是否在生成java文件之前清空outputDirectory的文件，默認(rèn)值為true，設(shè)置為false時也會覆蓋同名文件-->
                    <clearOutputDirectory>false</clearOutputDirectory>

                </configuration>
                <executions>
                    <execution>
                        <!--在執(zhí)行mvn compile的時候會執(zhí)行以下操作-->
                        <phase>compile</phase>
                        <goals>
                            <!--生成OuterClass類-->
                            <goal>compile</goal>
                            <!--生成Grpc類-->
                            <!--goal>compile-custom</goal-->
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

該配置先使用os-maven-plugin插件，該插件主要是為了識別不同的操作系統(tǒng)，這樣插件可以根據(jù)不同的平臺加載不同protoc編譯器文件。google的protobuf團(tuán)隊(duì)也是用該插件來識別protoc的運(yùn)行操作系統(tǒng)信息
后面配置了protobuf-maven-plugin編譯參數(shù)，下面我說下主要的幾個參數(shù)。詳細(xì)的參數(shù)可以參考官方文檔：Maven Protocol Buffers Plugin – protobuf:compile

protobuf-maven-plugin插件主要參數(shù)介紹：

從上文的配置中，我們可以看到主要的配置參數(shù)如下：

protocArtifact： protoc編譯器工具的格式規(guī)范，groupId:artifactId:version[:type[:classifier]]。如果指定了該參數(shù)，protoc將嘗試按照指定的參數(shù)對文件proto文件進(jìn)行編譯'
protocExecutable：配置protoc的編譯執(zhí)行程序的路徑
protocPluginDirectory: protoc的執(zhí)行文件目錄
protoSourceRoot：原始proto文件的路徑，比如${project.basedir}/src/main/proto
outputDirectory：編譯后生成.java文件的路徑，比如：${project.basedir}/src/main/java
temporaryProtoFileDirectory: 臨時使用目錄
clearOutputDirectory：設(shè)置是否在生成java文件之前清空outputDirectory的文件，默認(rèn)值為true，設(shè)置為false時也會覆蓋同名文件
additionalProtoPathElement：附加的源proto文件定義路徑，如果設(shè)備源路徑?jīng)]找到，會到該目錄找
excludes：排除不需要編譯的文件列表
includes：包含需要編譯的proto文件列表，默認(rèn)的

<includes>
 <include>**/*.proto</include>
</includes>

使用自定義編譯插件編譯gRPC服務(wù)

如果只是編譯proto文件，可以不使用該插件，使用上面的配置即可。當(dāng)要使用自定義插件的時候，必須將goal設(shè)置為compile-custom。設(shè)置好goal后，可以配置插件的信息，如下：

pluginId: 唯一標(biāo)識protoc的插件，不能為內(nèi)置的protoc插件，比如grpc-java插件
pluginArtifact: 識別插件版本
pluginParameter: 傳遞給插件的參數(shù)

下面使用示例為使用grpc-java編譯proto文件的bom的build配置

// pom.xml

<build>
        <extensions>
            <extension>
                <groupId>kr.motd.maven</groupId>
                <artifactId>os-maven-plugin</artifactId>
                <version>${os.plugin.version}</version>
            </extension>
        </extensions>
        <plugins>
            <plugin>
                <groupId>org.xolstice.maven.plugins</groupId>
                <artifactId>protobuf-maven-plugin</artifactId>
                <version>${protobuf.plugin.version}</version>
                <extensions>true</extensions>
                <configuration>
                    <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
                    <pluginId>grpc-java</pluginId>
                    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.java.version}:exe:${os.detected.classifier}</pluginArtifact>
                    <!--默認(rèn)值-->
                    <protoSourceRoot>${project.basedir}/src/main/proto</protoSourceRoot>
                    <!--默認(rèn)值-->
                    <outputDirectory>${project.basedir}/src/main/java</outputDirectory>
                    <!--設(shè)置是否在生成java文件之前清空outputDirectory的文件，默認(rèn)值為true，設(shè)置為false時也會覆蓋同名文件-->
                    <clearOutputDirectory>false</clearOutputDirectory>
                    <!--更多配置信息可以查看https://www.xolstice.org/protobuf-maven-plugin/compile-mojo.html-->
                </configuration>
                <executions>
                    <execution>
                        <!--在執(zhí)行mvn compile的時候會執(zhí)行以下操作-->
                        <phase>compile</phase>
                        <goals>
                            <!--生成OuterClass類-->
                            <goal>compile</goal>
                            <!--生成Grpc類-->
                            <goal>compile-custom</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

這里我們主要配置了gprc-java插件，用來生成grpc服務(wù)的包

使用protobuf-maven-plugin生成gRPC的包

首先我們先proto的test目錄下，創(chuàng)建一個hello.proto的文件，內(nèi)容如下

syntax = "proto3";

option java_multiple_files = true;
option java_package = "cn.ckeen.lib.grpc.test";
option java_outer_classname = "HelloWorldProto";

// The greeting service definition.
service Simple {
    // Sends a greeting
    rpc SayHello (HelloRequest) returns (HelloReply) {
    }
}

// The request message containing the user's name.
message HelloRequest {
    string name = 1;
}

// The response message containing the greetings
message HelloReply {
    string message = 1;
}

使用上述自定義插件的插件的pom配置，使用maven compile編譯一下，我們可以看到編譯的生成的包