多模块Maven项目PDFBox依赖冲突问题求助

核心问题分析 #

你的问题本质是类加载冲突：ModuleD依赖的修改版PDFBox（com.edited.crucial:crucialpdfbox）和其他模块的官方PDFBox（org.apache.pdfbox:pdfbox:2.0.24）包名完全一致（都是org.apache.pdfbox），运行时JVM类加载器会优先加载类路径中先找到的版本，导致ModuleD的代码调用到了官方版中不存在的方法。

下面是三种可行的解决办法，按推荐优先级排序：

1. 使用Maven Shade插件重命名修改版PDFBox的包名（推荐） #

通过Shade插件将修改版PDFBox的包名重命名为自定义命名空间，彻底隔离两个版本的类，不会影响其他模块的正常运行。

在ModuleD的pom.xml中添加以下插件配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.4.1</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <relocations>
                            <!-- 重命名PDFBox核心包 -->
                            <relocation>
                                <pattern>org.apache.pdfbox</pattern>
                                <shadedPattern>com.edited.crucial.pdfbox</shadedPattern>
                            </relocation>
                            <!-- 同步重命名fontbox包，避免关联冲突 -->
                            <relocation>
                                <pattern>org.apache.fontbox</pattern>
                                <shadedPattern>com.edited.crucial.fontbox</shadedPattern>
                            </relocation>
                        </relocations>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

配置完成后，重新打包ModuleD：

mvn clean package -pl ModuleD -am

此时ModuleD的JAR中，所有org.apache.pdfbox相关的类都会被重命名为com.edited.crucial.pdfbox，和其他模块的官方PDFBox完全隔离，运行时不会再出现类加载冲突。

2. 调整ModuleServer的依赖顺序与排除规则（仅适用于修改版兼容官方版的场景） #

如果修改版PDFBox完全兼容官方2.0.24版本，可以通过调整依赖顺序，让修改版优先被加载，同时排除其他模块的官方PDFBox传递依赖。

在ModuleServer的pom.xml中按以下顺序声明依赖：

<dependencies>
    <!-- 优先声明ModuleD，确保其依赖的修改版PDFBox被优先解析 -->
    <dependency>
        <groupId>你的项目groupId</groupId>
        <artifactId>ModuleD</artifactId>
        <version>你的项目版本</version>
    </dependency>
    
    <!-- 显式声明修改版PDFBox，避免传递依赖被覆盖 -->
    <dependency>
        <groupId>com.edited.crucial</groupId>
        <artifactId>crucialpdfbox</artifactId>
        <version>0.0.1</version>
    </dependency>
    
    <!-- 声明其他模块，并排除它们的官方PDFBox依赖 -->
    <dependency>
        <groupId>你的项目groupId</groupId>
        <artifactId>ModuleA</artifactId>
        <version>你的项目版本</version>
        <exclusions>
            <exclusion>
                <groupId>org.apache.pdfbox</groupId>
                <artifactId>pdfbox</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    
    <!-- 同理处理ModuleB、ModuleC -->
    <dependency>
        <groupId>你的项目groupId</groupId>
        <artifactId>ModuleB</artifactId>
        <version>你的项目版本</version>
        <exclusions>
            <exclusion>
                <groupId>org.apache.pdfbox</groupId>
                <artifactId>pdfbox</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    
    <dependency>
        <groupId>你的项目groupId</groupId>
        <artifactId>ModuleC</artifactId>
        <version>你的项目版本</version>
        <exclusions>
            <exclusion>
                <groupId>org.apache.pdfbox</groupId>
                <artifactId>pdfbox</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    
    <!-- 其他依赖（ModuleCommons等） -->
</dependencies>

注意：如果修改版PDFBox和官方2.0.24存在不兼容的API，这种方法会导致ModuleA/B/C出现运行错误，仅适合完全兼容的场景。

3. 类加载器隔离（复杂度高，适合大型项目） #

如果上述两种方法都无法解决，可以考虑通过类加载器隔离实现模块间的依赖隔离：

• OSGi方案：将每个模块打包成OSGi bundle，每个bundle拥有独立的类加载空间，可通过OSGi的依赖管理机制控制版本。
• 自定义类加载器：为ModuleD编写自定义类加载器，加载其依赖的修改版PDFBox类，避免和全局类加载器中的官方版冲突。

这种方案需要修改项目的架构和运行方式，复杂度较高，小型项目不推荐使用。

内容的提问来源于stack exchange，提问作者WhereWolf