为何Protobuf Maven插件未在target目录生成类文件？

问题描述 #

我刚开始学习gRPC，在proto包中创建了一个简单的proto文件：

syntax = "proto3";

service HelloWorldService {
  rpc hello(HelloRequest) returns (HelloResponse) {}
}

message HelloRequest {
  string text = 1;
}

message HelloResponse {
  string text = 1;
}

使用Maven构建，pom.xml配置如下：

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<groupId>org.example</groupId>
<artifactId>grpc-hello-server</artifactId>
<version>1.0-SNAPSHOT</version>

<name>GRPC</name>
<!-- FIXME change it to the project's website -->
<url>http://www.example.com</url>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.7</maven.compiler.source>
    <maven.compiler.target>1.7</maven.compiler.target>
</properties>

<dependencies>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.13.2</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-netty-shaded</artifactId>
        <version>1.48.0</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-protobuf</artifactId>
        <version>1.48.0</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-stub</artifactId>
        <version>1.48.0</version>
    </dependency>
    <dependency>
        <groupId>javax.annotation</groupId>
        <artifactId>javax.annotation-api</artifactId>
        <version>1.3.2</version>
    </dependency>
</dependencies>

<build>
    <extensions>
        <extension>
            <groupId>kr.motd.maven</groupId>
            <artifactId>os-maven-plugin</artifactId>
            <version>1.6.2</version>
        </extension>
    </extensions>
    <plugins>
        <plugin>
            <groupId>org.xolstice.maven.plugins</groupId>
            <artifactId>protobuf-maven-plugin</artifactId>
            <version>0.6.1</version>
            <configuration>
                <protocArtifact>com.google.protobuf:protoc:3.9.0:exe:${os.detected.classifier}</protocArtifact>
                <pluginId>grpc-java</pluginId>
                <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.24.0:exe:${os.detected.classifier}</pluginArtifact>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>compile</goal>
                        <goal>compile-custom</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

执行package（及clean、install）后，target/generated-sources目录为空，未生成预期的Java类文件。

原因分析及解决方案 #

1. proto文件路径不符合插件默认约定 #

protobuf-maven-plugin默认从src/main/protobuf目录读取proto文件，若你将文件放在src/main/java下的proto包中，插件会找不到文件，无法生成代码。

解决方法：

• 推荐：将proto文件移动到src/main/protobuf目录，符合Maven插件约定；
• 备选：在插件配置中指定proto文件路径，添加<protoSourceRoot>：

<configuration>
    <!-- 保留原有配置 -->
    <protoSourceRoot>${project.basedir}/src/main/java/org/example/proto</protoSourceRoot>
</configuration>

（替换为你实际的proto文件所在路径）

2. gRPC组件版本不兼容 #

你的grpc依赖版本是1.48.0，但protoc-gen-grpc-java版本为1.24.0，版本差距过大，会导致插件执行失败。

解决方法：
将protoc-gen-grpc-java版本升级至与grpc依赖一致的1.48.0，同时匹配兼容的protoc版本（grpc 1.48.0最低支持protoc 3.12.0，推荐使用3.21.0）：

<configuration>
    <protocArtifact>com.google.protobuf:protoc:3.21.0:exe:${os.detected.classifier}</protocArtifact>
    <pluginId>grpc-java</pluginId>
    <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.48.0:exe:${os.detected.classifier}</pluginArtifact>
</configuration>

3. Java版本过低 #

pom中配置的Java编译版本为1.7，但grpc 1.48.0最低要求Java 8，版本不兼容会导致插件执行异常。

解决方法：
修改pom中的Java版本配置为1.8及以上：

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

4. 插件版本过旧 #

protobuf-maven-plugin 0.6.1版本较老，存在兼容性问题。

解决方法：
升级插件至最新稳定版（如0.1.17），配置格式保持不变：

<plugin>
    <groupId>org.xolstice.maven.plugins</groupId>
    <artifactId>protobuf-maven-plugin</artifactId>
    <version>0.1.17</version>
    <configuration>
        <protocArtifact>com.google.protobuf:protoc:3.21.0:exe:${os.detected.classifier}</protocArtifact>
        <pluginId>grpc-java</pluginId>
        <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.48.0:exe:${os.detected.classifier}</pluginArtifact>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>compile</goal>
                <goal>compile-custom</goal>
            </goals>
        </execution>
    </executions>
</plugin>

验证步骤 #

修改配置后，执行以下命令：

mvn clean compile

查看target/generated-sources/protobuf目录下是否生成了消息类和grpc服务Stub类。

内容的提问来源于stack exchange，提问作者Денис Задорожний