基于Java&Maven适配依赖库双API版本的实现方案问询

架构老林

2026-5-15

嘿，这个场景我之前维护大数据项目的时候刚好碰到过！既要兼容Parquet新旧版本的API变更，又不想拆成独立项目，其实有几种可行的方案，咱们一步步说：

方案一：单模块+Maven Profiles+条件编译（不用新增模块）

这个方案完美匹配你“不新增模块”的需求，核心思路是把新旧版本的实现代码分开存放，通过Maven Profiles控制编译哪一部分，同时隔离依赖版本。

具体步骤：

抽离公共接口：先定义一个统一的适配接口，比如ParquetDataProcessor，放在src/main/java/com/yourproject/parquet/common下，所有业务代码只依赖这个接口，不直接触碰Parquet的具体API。
编写双版本实现：
- 在src/main/java/com/yourproject/parquet/old下写适配旧版本的实现类OldParquetProcessor，使用parquet.hadoop.api包下的API；
- 在src/main/java/com/yourproject/parquet/new下写适配新版本的实现类NewParquetProcessor，使用org.apache.parquet.hadoop.api包下的API；
  两个实现类都实现刚才的ParquetDataProcessor接口。

配置Maven Profiles：在项目根pom.xml里添加两个Profile，分别对应新旧版本，控制依赖版本和编译范围：

<profiles>
  <profile>
    <id>old-parquet</id>
    <properties>
      <parquet.version>1.10.1</parquet.version>
      <adapter.dir>old</adapter.dir>
    </properties>
    <dependencies>
      <dependency>
        <groupId>org.apache.parquet</groupId>
        <artifactId>parquet-hadoop</artifactId>
        <version>${parquet.version}</version>
      </dependency>
    </dependencies>
    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <configuration>
            <includes>
              <include>**/parquet/common/**</include>
              <include>**/parquet/${adapter.dir}/**</include>
              <!-- 其他业务代码目录 -->
              <include>**/service/**</include>
            </includes>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
  <profile>
    <id>new-parquet</id>
    <properties>
      <parquet.version>1.14.0</parquet.version>
      <adapter.dir>new</adapter.dir>
    </properties>
    <dependencies>
      <dependency>
        <groupId>org.apache.parquet</groupId>
        <artifactId>parquet-hadoop</artifactId>
        <version>${parquet.version}</version>
      </dependency>
    </dependencies>
    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <configuration>
            <includes>
              <include>**/parquet/common/**</include>
              <include>**/parquet/${adapter.dir}/**</include>
              <include>**/service/**</include>
            </includes>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

构建时切换版本：执行mvn clean package -P old-parquet就会编译旧版本实现并打包，用-P new-parquet则对应新版本。

这种方案的优势是保持单模块结构，不用拆分项目；缺点是IDE里需要切换Profile才能正确加载依赖和代码，而且要注意新旧实现代码不要互相引用。

方案二：多模块拆分（你的原始思路优化）

如果新旧版本的API差异很大，或者未来可能要扩展更多版本，多模块方案会更清晰：

拆分三个模块：
- yourproject-common：存放公共接口、工具类，不依赖任何Parquet版本；
- yourproject-parquet-old：依赖旧版本Parquet，实现yourproject-common里的接口；
- yourproject-parquet-new：依赖新版本Parquet，实现yourproject-common里的接口；
- 主业务模块yourproject-service：依赖yourproject-common，通过Profile控制引入old或new模块。

父pom配置Profile：在父pom里用Profile控制主业务模块的依赖：

<profiles>
  <profile>
    <id>old-parquet</id>
    <modules>
      <module>yourproject-common</module>
      <module>yourproject-parquet-old</module>
      <module>yourproject-service</module>
    </modules>
    <dependencies>
      <dependency>
        <groupId>com.yourproject</groupId>
        <artifactId>yourproject-parquet-old</artifactId>
        <version>${project.version}</version>
      </dependency>
    </dependencies>
  </profile>
  <profile>
    <id>new-parquet</id>
    <modules>
      <module>yourproject-common</module>
      <module>yourproject-parquet-new</module>
      <module>yourproject-service</module>
    </modules>
    <dependencies>
      <dependency>
        <groupId>com.yourproject</groupId>
        <artifactId>yourproject-parquet-new</artifactId>
        <version>${project.version}</version>
      </dependency>
    </dependencies>
  </profile>
</profiles>

这种方案的好处是代码完全隔离，每个模块的依赖独立，IDE里也不用频繁切换Profile；缺点是多模块结构稍微增加了一点配置复杂度，但长期维护更省心。

不推荐的方案：反射适配

有些同学会想到用反射来兼容不同包名的API，但这种写法会让代码变得非常晦涩，调试困难，而且性能也有损耗，除非差异极小，否则不建议用。

总结一下：如果新旧版本差异小，优先用单模块+Profiles；如果差异大或者未来要扩展，用多模块方案。

内容的提问来源于stack exchange，提问作者andre.hacker