java使用protobuf-maven-plugin的插件编译proto文件

protobuf文件作为数据传输和存储的协议，已经使用的越来越广泛了。使用protobuf有如下的优势：

1. protocol buffers 是一种语言无关、平台无关、可扩展的序列化结构数据。
2. 相比XML，有编码后体积更小，编解码速度更快的优势；相比于 Json，Protobuf 有更高的转化效率，时间效率和空间效率都是 JSON 的 3-5 倍。
3. protobuf还提供了不同语言的protoc的编译工具，使用简单的编译指令就更生成支持不同语言的调用包。

下面我们主要介绍在java使用maven编译proto文件的插件：protobuf-maven-plugin。

1. 我们在工程目录下创建一个lib的module，用来统一管理proto的包和编译后生成的java包。然后我们在跟java同级的目录创建proto的文件夹，用来存放.proto文件（如下图）
   
2. 在pom的build中配置proto的编译插件

   // pom.xml
   
   
           
               
                   kr.motd.maven
                   os-maven-plugin
                   ${os.plugin.version}
               
           
           
               
                   org.xolstice.maven.plugins
                   protobuf-maven-plugin
                   ${protobuf.plugin.version}
                   true
                   
                       
                      com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}
                       
                       ${project.basedir}/src/main/proto
                       
                       ${project.basedir}/src/main/java
                       
                       false
   
                   
                   
                       
                           
                           compile
                           
                               
                               compile
                               
                               
                           
                       
                   
               
           
       

   -  该配置先使用os-maven-plugin插件，该插件主要是为了识别不同的操作系统，这样插件可以根据不同的平台加载不同protoc编译器文件。google的protobuf团队也是用该插件来识别protoc的运行操作系统信息

3. - 后面配置了protobuf-maven-plugin编译参数，下面我说下主要的几个参数。详细的参数可以参考官方文档：Maven Protocol Buffers Plugin – protobuf:compile

4.  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文件列表，默认的

   
    **/*.proto
   

5. 使用自定义编译插件编译gRPC服务
   
   如果只是编译proto文件，可以不使用该插件，使用上面的配置即可。当要使用自定义插件的时候，必须将goal设置为compile-custom。设置好goal后，可以配置插件的信息，如下：
   
   - pluginId: 唯一标识protoc的插件，不能为内置的protoc插件，比如grpc-java插件
   - pluginArtifact: 识别插件版本
   - pluginParameter:  传递给插件的参数
   
   下面使用示例为使用grpc-java编译proto文件的bom的build配置

   // pom.xml
   
   
           
               
                   kr.motd.maven
                   os-maven-plugin
                   ${os.plugin.version}
               
           
           
               
                   org.xolstice.maven.plugins
                   protobuf-maven-plugin
                   ${protobuf.plugin.version}
                   true
                   
                       com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}
                       grpc-java
                       io.grpc:protoc-gen-grpc-java:${grpc.java.version}:exe:${os.detected.classifier}
                       
                       ${project.basedir}/src/main/proto
                       
                       ${project.basedir}/src/main/java
                       
                       false
                       
                   
                   
                       
                           
                           compile
                           
                               
                               compile
                               
                               compile-custom
                           
                       
                   
               
           
       

   这里我们主要配置了gprc-java插件，用来生成grpc服务的包

6. 使用 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的的服务端和客户端引用该包。 

7. 可能遇到的问题
   
   -  配置了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
   
   - 注意所有文件路径中不要使用中文