maven中的grpc编译插件protobuf-maven-plugin详解

protobuf-maven-plugin 是 Maven 中用于编译 Protocol Buffers（protobuf）文件并生成对应语言代码（如 Java、C++、Python 等）的插件。在 gRPC 项目中，它常被用来生成服务端和客户端所需的代码。以下是该插件的详细解析：

前些天发现了一个巨牛的人工智能学习网站，通俗易懂，风趣幽默，忍不住分享一下给大家。点击跳转到网站

---

1. 插件作用

• 编译 .proto 文件：将 .proto 文件编译为指定语言的代码（如 Java 的 POJO 类、gRPC 的服务接口等）。
• 支持 gRPC 代码生成：通过配置插件，可以生成 gRPC 服务端和客户端的代码。
• 自动化集成：与 Maven 的构建流程集成，无需手动调用 protoc 编译器。

---

2. 插件配置示例

在 Maven 的 pom.xml 文件中，配置 protobuf-maven-plugin 的示例如下：

<build><plugins><plugin><groupId>org.xolstice.maven.plugins</groupId><artifactId>protobuf-maven-plugin</artifactId><version>0.6.1</version> <!-- 使用最新版本 --><configuration><!-- 指定 protoc 编译器的版本和路径 --><protocArtifact>com.google.protobuf:protoc:3.21.12:exe:${os.detected.classifier}</protocArtifact><!-- 指定 gRPC 插件的版本和路径 --><pluginId>grpc-java</pluginId><pluginArtifact>io.grpc:protoc-gen-grpc-java:1.57.2:exe:${os.detected.classifier}</pluginArtifact><!-- 指定 proto 文件目录 --><protoSourceRoot>${project.basedir}/src/main/proto</protoSourceRoot><!-- 指定生成的代码输出目录 --><outputDirectory>${project.basedir}/target/generated-sources/protobuf</outputDirectory><!-- 是否清空输出目录 --><clearOutputDirectory>false</clearOutputDirectory></configuration><executions><execution><goals><!-- 编译 proto 文件生成基础消息类 --><goal>compile</goal><!-- 编译 proto 文件生成 gRPC 代码 --><goal>compile-custom</goal></goals></execution></executions></plugin></plugins>
</build>

---

3. 关键配置项解析

• protocArtifact
  指定 protoc 编译器的版本和路径。${os.detected.classifier} 会根据操作系统自动选择对应的版本（如 osx-x86_64、linux-x86_64 等）。

• pluginId 和 pluginArtifact
pluginId 指定插件类型（如 grpc-java），pluginArtifact 指定 gRPC 插件的版本和路径。

• protoSourceRoot
  指定 .proto 文件的目录，默认为 ${project.basedir}/src/main/proto。

• outputDirectory
  指定生成的代码输出目录，默认为 ${project.build.directory}/generated-sources/protobuf。

• clearOutputDirectory
  是否在生成代码前清空输出目录。设为 false 可以避免重复生成时丢失已有代码。

• goals

  • compile：生成基础的消息类（如 Java 的 POJO）。
  • compile-custom：生成 gRPC 相关的代码（如服务接口和客户端代码）。

---

4. 依赖项

为了使生成的 gRPC 代码能够正常工作，需要在 pom.xml 中添加 gRPC 的依赖：

<dependencies><!-- gRPC 核心依赖 --><dependency><groupId>io.grpc</groupId><artifactId>grpc-netty-shaded</artifactId><version>1.57.2</version></dependency><dependency><groupId>io.grpc</groupId><artifactId>grpc-protobuf</artifactId><version>1.57.2</version></dependency><dependency><groupId>io.grpc</groupId><artifactId>grpc-stub</artifactId><version>1.57.2</version></dependency><!-- Protocol Buffers 运行时依赖 --><dependency><groupId>com.google.protobuf</groupId><artifactId>protobuf-java</artifactId><version>3.21.12</version></dependency>
</dependencies>

---

5. 使用流程

1. 编写 .proto 文件
   在 src/main/proto 目录下编写 .proto 文件，定义消息和服务。例如：

   syntax = "proto3";
   option java_package = "com.example.grpc";
   option java_outer_classname = "HelloWorldProto";service Greeter {rpc SayHello (HelloRequest) returns (HelloReply) {}
   }message HelloRequest {string name = 1;
   }message HelloReply {string message = 1;
   }
   

2. 运行 Maven 编译
   执行以下命令生成代码：

   mvn compile
   

   生成的代码会出现在 target/generated-sources/protobuf 目录下。

3. 在代码中使用生成的类
   生成的代码包括：

   • 消息类（如 HelloRequest 和 HelloReply）。
   • gRPC 服务接口（如 GreeterGrpc）。

---

6. 常见问题

• 版本不匹配
  确保 protobuf-maven-plugin、protoc 和 gRPC 插件的版本兼容。建议使用最新稳定版本。

• 代码未生成
  检查 .proto 文件是否放在正确的目录下，并确认插件配置中的 protoSourceRoot 和 outputDirectory 是否正确。

• 操作系统兼容性
  ${os.detected.classifier} 会自动处理操作系统的差异，但如果出现问题，可以手动指定 protoc 的路径。

• ${os.detected.classifier}报红

  Could not find artifact com.google.protobuf:protoc:exe:${os.detected.classifier}:3.3.0 in

  • 解决方案：
    在build标签中增加extensions标签，如下所示：

  <extensions><extension><groupId>kr.motd.maven</groupId><artifactId>os-maven-plugin</artifactId><version>1.4.1.Final</version></extension></extensions>
  

  整体配置如下所示：

  <build><plugins><plugin><groupId>org.xolstice.maven.plugins</groupId><artifactId>protobuf-maven-plugin</artifactId><version>0.6.1</version><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.version}:exe:${os.detected.classifier}</pluginArtifact><protoSourceRoot>${project.basedir}/src/main/proto</protoSourceRoot><outputDirectory>${project.basedir}/src/main/java/com/xxx/cloud/demo/grpc/service</outputDirectory><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><extensions><extension><groupId>kr.motd.maven</groupId><artifactId>os-maven-plugin</artifactId><version>1.4.1.Final</version></extension></extensions></build>

---

7、protocPlugin解析

protoc_plugin 是 Protocol Buffers（protobuf）编译器 protoc 的插件，用于根据 .proto 文件生成特定语言的代码。不同语言和场景下有多种常用的 protoc_plugin，以下是一些常见插件的解析：

1. protoc-gen-go（Go语言插件）

• 用途：用于生成 Go 语言的 protobuf 代码。
• 特点：
  • 由 Google 官方维护，与 Go 生态深度集成。
  • 支持 protobuf 的消息定义和服务定义。
  • 生成的代码可直接用于 gRPC 或序列化场景。
• 使用示例：

  protoc --go_out=. --go_opt=paths=source_relative your_file.proto
  

2. protoc-gen-grpc-java（Java gRPC 插件）

• 用途：用于生成 Java 语言的 gRPC 客户端和服务端代码。
• 特点：
  • 生成的代码包括 gRPC 的服务接口和消息类。
  • 支持 Java 的多种构建工具（如 Maven、Gradle）。
• 使用示例（Maven 配置）：

  <plugin><groupId>org.xolstice.maven.plugins</groupId><artifactId>protobuf-maven-plugin</artifactId><configuration><pluginId>grpc-java</pluginId><pluginArtifact>io.grpc:protoc-gen-grpc-java:1.57.2</pluginArtifact></configuration>
  </plugin>
  

3. protoc-gen-dart（Dart 语言插件）

• 用途：用于生成 Dart 语言的 protobuf 代码。
• 特点：
  • 支持 Flutter 和 Dart 开发。
  • 生成的代码可用于 Dart 虚拟机或浏览器（通过 dart2js）。
• 使用示例：

  protoc --dart_out=. your_file.proto
  

4. protoc-gen-grpc-python（Python gRPC 插件）

• 用途：用于生成 Python 语言的 gRPC 客户端和服务端代码。
• 特点：
  • 生成的代码包括 gRPC 的服务接口和消息类。
  • 支持 Python 的异步编程模型。
• 使用示例：

  pip install grpcio-tools
  python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. your_file.proto
  

5. protoc-gen-ts（TypeScript 插件）

• 用途：用于生成 TypeScript 语言的 protobuf 代码。
• 特点：
  • 生成的代码可用于浏览器或 Node.js。
  • 支持 gRPC-Web（用于浏览器端 gRPC 通信）。
• 使用示例：

  protoc --plugin=protoc-gen-ts=./node_modules/.bin/protoc-gen-ts --ts_out=. your_file.proto
  

6. 自定义 protoc 插件

• 用途：根据业务需求生成特定格式的代码或文档。
• 特点：
  • 插件是一个独立的二进制程序，通过标准输入/输出与 protoc 通信。
  • 使用 protoc 的 CodeGeneratorRequest 和 CodeGeneratorResponse 协议缓冲区消息进行交互。
• 实现步骤：
  1. 从标准输入读取 CodeGeneratorRequest。
  2. 解析 .proto 文件信息。
  3. 生成目标代码。
  4. 将生成的代码封装为 CodeGeneratorResponse 并写入标准输出。
• 示例（Go 实现）：

  package mainimport ("flag""fmt""google.golang.org/protobuf/compiler/protogen"
  )func main() {var flags flag.FlagSetprotogen.Options{ParamFunc: flags.Set,}.Run(func(gen *protogen.Plugin) error {for _, f := range gen.Files {if !f.Generate {continue}// 生成目标代码g := gen.NewGeneratedFile(f.GeneratedFilenamePrefix+".custom.txt", f.GoImportPath)g.P("// 自定义生成的代码")for _, msg := range f.Messages {g.P(fmt.Sprintf("message %s {", msg.GoIdent.GoName))for _, field := range msg.Fields {g.P(fmt.Sprintf("  %s %s = %d;", field.Desc.Kind(), field.GoName, field.Desc.Number()))}g.P("}")}}return nil})
  }
  

7. protoc-gen-doc（文档生成插件）

• 用途：根据 .proto 文件生成文档（如 Markdown、HTML）。
• 特点：
  • 支持多种输出格式。
  • 可用于生成 API 文档。
• 使用示例：

  protoc --doc_out=. --doc_opt=markdown,your_file.md your_file.proto
  

8.vertx-grpc-protoc-plugin

vertx-grpc-protoc-plugin 是专为 Vert.x 框架设计的 gRPC 插件，用于将 .proto 文件编译生成 Vert.x 生态所需的 gRPC 客户端和服务端代码。以下是对其核心特性和作用的解析：

1. 核心功能

• 代码生成：基于 .proto 文件，自动生成符合 Vert.x 异步编程模型的 gRPC 客户端和服务端代码。
• 与 Vert.x 集成：生成的代码可直接与 Vert.x 的事件循环和非阻塞特性配合使用，无需额外适配。
• 简化开发：避免手动编写 gRPC 通信逻辑，开发者可专注于业务实现。

2. 技术特点

• 异步支持：生成的代码支持 Vert.x 的异步调用方式，适合高并发场景。
• 多语言支持：通常与 Vert.x 支持的语言（如 Java、Kotlin、Groovy 等）兼容。
• 依赖管理：可能包含对 Vert.x 依赖的自动管理，简化项目配置。

3. 使用场景

• Vert.x 微服务：在基于 Vert.x 的微服务架构中，快速实现 gRPC 通信。
• 实时通信：适用于需要低延迟、高吞吐量的场景（如实时数据推送）。
• 跨语言服务：通过 gRPC 的多语言支持，与其他语言的服务交互。

4. 与其他插件对比

• 通用 gRPC 插件：如 protoc-gen-grpc-java 生成的代码是通用的，可能需要额外适配 Vert.x。
• vertx-grpc-protoc-plugin：专为 Vert.x 优化，生成的代码更贴合 Vert.x 的编程模型。

5. 优缺点

• 优点：
  • 减少样板代码，提升开发效率。
  • 与 Vert.x 深度集成，适合 Vert.x 生态。
• 缺点：
  • 依赖 Vert.x 框架，灵活性可能受限。
  • 社区规模较小，文档和示例可能不如通用插件丰富。

6. 使用示例

假设有一个 .proto 文件 service.proto：

syntax = "proto3";
service Greeter {rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest { string name = 1; }
message HelloReply { string message = 1; }

使用 vertx-grpc-protoc-plugin 编译后，会生成 Vert.x 风格的 gRPC 客户端和服务端代码，可直接在 Vert.x 项目中使用。

7. 配置建议

• 在 Vert.x 项目的构建工具（如 Maven 或 Gradle）中配置插件。
• 确保插件版本与 Vert.x 和 gRPC 版本兼容。

vertx-grpc-protoc-plugin 是 Vert.x 生态中 gRPC 开发的利器，尤其适合需要与 Vert.x 深度集成的项目。它通过自动化代码生成，简化了 gRPC 的开发流程，但可能牺牲一定的灵活性。对于 Vert.x 用户，这是一个值得尝试的工具。

总结

• 官方插件：如 protoc-gen-go、protoc-gen-grpc-java 等，适用于主流语言，功能稳定。
• 自定义插件：适用于特定需求，灵活性高，但需要额外开发。
• 文档生成插件：如 protoc-gen-doc，适用于 API 文档生成。

选择插件时，需根据项目使用的语言、框架和需求进行匹配。对于 gRPC 开发，通常需要结合语言特定的 gRPC 插件（如 protoc-gen-grpc-java 或 protoc-gen-grpc-python）和 protobuf 消息插件（如 protoc-gen-go 或 protoc-gen-dart）。

8. 总结

protobuf-maven-plugin 是 gRPC 项目中不可或缺的工具，通过合理的配置可以自动化生成消息类和 gRPC 代码，大大简化开发流程。关键点包括：

• 正确配置 protoc 和 gRPC 插件的版本。
• 指定 .proto 文件和生成代码的目录。
• 确保依赖项版本兼容。

通过以上配置和使用方法，可以高效地在 Maven 项目中集成 gRPC 和 Protocol Buffers。