作者:程序员CKeen
博客:http://ckeen.cn
长期坚持做有价值的事!积累沉淀,持续成长,升维思考!希望把编码作为长期兴趣爱好😄
protobuf文件作为数据传输和存储的协议,已经使用的越来越广泛了。使用protobuf有如下的优势:
- protocol buffers 是一种语言无关、平台无关、可扩展的序列化结构数据。
- 相比XML,有编码后体积更小,编解码速度更快的优势;相比于 Json,Protobuf 有更高的转化效率,时间效率和空间效率都是 JSON 的 3-5 倍。
- protobuf还提供了不同语言的protoc的编译工具,使用简单的编译指令就更生成支持不同语言的调用包。
下面我们主要介绍在java使用maven编译proto文件的插件:protobuf-maven-plugin。
- 我们在工程目录下创建一个lib的module,用来统一管理proto的包和编译后生成的java包。然后我们在跟java同级的目录创建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> <!--默认值,proto源文件路径--> <protoSourceRoot>${project.basedir}/src/main/proto</protoSourceRoot> <!--默认值,proto目标java文件路径--> <outputDirectory>${project.basedir}/src/main/java</outputDirectory> <!--设置是否在生成java文件之前清空outputDirectory的文件,默认值为true,设置为false时也会覆盖同名文件--> <clearOutputDirectory>false</clearOutputDirectory> </configuration> <executions> <execution> <!--在执行mvn compile的时候会执行以下操作--> <phase>compile</phase> <goals> <!--生成OuterClass类--> <goal>compile</goal> <!--生成Grpc类--> <!--goal>compile-custom</goal--> </goals> </execution> </executions> </plugin> </plugins> </build>
- 该配置先使用os-maven-plugin插件,该插件主要是为了识别不同的操作系统,这样插件可以根据不同的平台加载不同protoc编译器文件。google的protobuf团队也是用该插件来识别protoc的运行操作系统信息
-
- 后面配置了protobuf-maven-plugin编译参数,下面我说下主要的几个参数。详细的参数可以参考官方文档:Maven Protocol Buffers Plugin – protobuf:compile
- protobuf-maven-plugin插件主要参数介绍
从上文的配置中,我们可以看到主要的配置参数如下:
- protocArtifact: protoc编译器工具的格式规范,groupId:artifactId:version[:type[:classifier]]。如果指定了该参数,protoc将尝试按照指定的参数对文件proto文件进行编译'
- protocExecutable:配置protoc的编译执行程序的路径
- protocPluginDirectory: protoc的执行文件目录
- protoSourceRoot: 原始proto文件的路径,比如${project.basedir}/src/main/proto
- outputDirectory: 编译后生成.java文件的路径,比如:${project.basedir}/src/main/java
- temporaryProtoFileDirectory: 临时使用目录
- clearOutputDirectory: 设置是否在生成java文件之前清空outputDirectory的文件,默认值为true,设置为false时也会覆盖同名文件
- additionalProtoPathElement:附加的源proto文件定义路径,如果设备源路径没找到,会到该目录找
- excludes:排除不需要编译的文件列表
- includes:包含需要编译的proto文件列表,默认的<includes> <include>**/*.proto</include> </includes>
- 使用自定义编译插件编译gRPC服务
如果只是编译proto文件,可以不使用该插件,使用上面的配置即可。当要使用自定义插件的时候,必须将goal设置为compile-custom。设置好goal后,可以配置插件的信息,如下:
- pluginId: 唯一标识protoc的插件,不能为内置的protoc插件,比如grpc-java插件
- pluginArtifact: 识别插件版本
- pluginParameter: 传递给插件的参数
下面使用示例为使用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> <!--默认值--> <protoSourceRoot>${project.basedir}/src/main/proto</protoSourceRoot> <!--默认值--> <outputDirectory>${project.basedir}/src/main/java</outputDirectory> <!--设置是否在生成java文件之前清空outputDirectory的文件,默认值为true,设置为false时也会覆盖同名文件--> <clearOutputDirectory>false</clearOutputDirectory> <!--更多配置信息可以查看https://www.xolstice.org/protobuf-maven-plugin/compile-mojo.html--> </configuration> <executions> <execution> <!--在执行mvn compile的时候会执行以下操作--> <phase>compile</phase> <goals> <!--生成OuterClass类--> <goal>compile</goal> <!--生成Grpc类--> <goal>compile-custom</goal> </goals> </execution> </executions> </plugin> </plugins> </build>
这里我们主要配置了gprc-java插件,用来生成grpc服务的包
- 使用 protobuf-maven-plugin生成gRPC的包
首先我们先proto的test目录下,创建一个hello.proto的文件,内容如下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编译一下,我们可以看到编译的生成的包
然后我们在gPRC的的服务端和客户端引用该包。
- 可能遇到的问题
- 配置了goal为compile-custom必须配置maven-protoc插件,否则会报错。
The parameters 'pluginId' for goal org.xolstice.maven.plugins:protobuf-maven-plugin:0.6.1:compile-custom are missing or invalid
- 注意所有文件路径中不要使用中文