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. 使用流程

编写 .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;
}

运行 Maven 编译
执行以下命令生成代码：
```
mvn compile
```
生成的代码会出现在 target/generated-sources/protobuf 目录下。
在代码中使用生成的类
生成的代码包括：
- 消息类（如 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 main

import (
    "flag"
    "fmt"
    "google.golang.org/protobuf/compiler/protogen"
)

func main() {
    var flags flag.FlagSet
    protogen.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）。