2.5 模块化迁移策略：从传统项目到模块化系统

---

模块化迁移策略：从传统项目到模块化系统

将传统 Java 项目迁移至 JDK 9 模块化系统是一项系统性工程，需分阶段实施以降低风险。以下是详细的迁移策略、工具使用和实战示例。

---

1. 迁移阶段划分

阶段	目标	关键操作
阶段1：兼容性验证	确保项目能在 JDK 9 上无模块化运行	使用类路径运行，处理废弃 API 和依赖冲突
阶段2：模块化试点	部分代码转为模块，依赖自动模块（非模块化 JAR）	创建 module-info.java，逐步迁移核心模块
阶段3：完整模块化	全项目模块化，显式管理所有依赖	重构模块结构，移除自动模块依赖

---

2. 阶段1：兼容性验证

目标

在不修改代码的情况下，验证项目在 JDK 9 上的运行能力。

关键步骤

1. 编译与运行测试

   javac -d out -classpath lib/*.jar src/**/*.java  
   java -classpath out:lib/*.jar com.example.Main  
   

2. 处理兼容性问题

   • 废弃 API 检测：

     jdeprscan --release 9 myapp.jar  
     

   • 内部 API 访问：
     • 错误示例：sun.misc.BASE64Encoder 不可访问。
     • 修复方案：替换为标准 API（java.util.Base64）。

3. 依赖冲突排查

   • 工具：使用 jdeps 分析依赖树：

     jdeps --class-path lib/*.jar -recursive myapp.jar  
     

---

3. 阶段2：模块化试点

目标

将部分代码转换为模块，依赖未模块化的第三方库作为自动模块。

关键步骤

1. 创建初始模块

   • 选择核心模块（如 com.utils），添加 module-info.java：

     module com.utils {  
         exports com.utils;  
         requires transitive org.apache.commons.lang3; // 自动模块名：commons.lang3  
     }  
     

2. 模块化编译与运行

   javac -d out --module-source-path src --module com.utils  
   java --module-path out:lib -m com.utils/com.example.Main  
   

3. 处理自动模块依赖

   • 自动模块命名规则：
     • JAR 文件名 log4j-api-2.17.1.jar → 模块名 log4j.api。
   • 依赖传递：自动模块默认依赖所有模块，但需显式声明核心 JDK 模块。

---

4. 阶段3：完整模块化

目标

全项目模块化，显式管理所有依赖（包括第三方库）。

关键步骤

1. 重构模块结构

   • 模块拆分：按功能拆分模块（如 com.user、com.order）。
   • 模块描述符：为每个模块编写 module-info.java。

2. 处理第三方库

   • 方案1：等待库官方提供模块化版本（如 Log4j 2.17+）。
   • 方案2：手动为库添加模块描述符（生成 module-info.java）。

3. 显式依赖管理

   module com.myapp {  
       requires java.sql;  
       requires com.utils;  
       requires org.apache.logging.log4j; // 显式声明 Log4j 模块  
   }  
   

4. 生成定制化 JRE

   jlink --module-path $JAVA_HOME/jmods:mods \  
         --add-modules com.myapp,java.sql \  
         --output myapp-runtime  
   

---

5. 迁移工具链

工具	用途	示例命令
jdeps	分析依赖关系和模块兼容性	jdeps --generate-module-info ./out myapp.jar
jdeprscan	检测废弃 API 使用	jdeprscan --release 9 myapp.jar
jlink	生成最小化 JRE	jlink --add-modules java.base...
jmod	创建 JMOD 文件（可选）	jmod create --class-path ...

---

6. 常见问题与解决方案

问题	解决方案
模块依赖未找到	检查 requires 声明，确保依赖模块在模块路径中，或添加 --add-modules <模块名>。
反射访问失败（如 Hibernate）	使用 opens 开放包权限：opens com.myapp.model to org.hibernate。
自动模块名冲突	重命名 JAR 文件（如 my-lib-1.0.jar → mylib.jar）以生成唯一模块名。
性能下降	检查垃圾回收配置（如 -XX:+UseG1GC），优化模块依赖减少加载时间。

---

7. 迁移最佳实践

1. 分阶段实施：
   • 先迁移底层工具模块，再逐步向上层业务模块推进。
2. 自动化测试：
   • 在每个阶段运行单元测试和集成测试（如 JUnit + CI/CD）。
3. 依赖管理：
   • 优先选择已适配 JDK 9 的第三方库（如 Spring 5、Hibernate 5.3+）。
4. 文档与协作：
   • 维护模块依赖图和迁移日志，与团队共享知识。

---

8. 实战示例：迁移 Spring Boot 应用

步骤1：兼容性验证

• 处理问题：
  • 替换 javax.xml.bind（JDK 9 中已移除）为第三方实现（如 org.glassfish.jaxb）。
  • 添加 --add-opens 参数开放反射权限：

    java --add-opens java.base/java.lang=ALL-UNNAMED -jar myapp.jar  
    

步骤2：模块化核心组件

• 模块描述符：

  module com.myapp.core {  
      requires spring.boot;  
      requires spring.context;  
      opens com.myapp.model to spring.core; // 允许 Spring 反射扫描  
  }  
  

步骤3：生成定制化 JRE

jlink --module-path $JAVA_HOME/jmods:mods \  
      --add-modules com.myapp.core,java.sql \  
      --output springboot-runtime  

---

9. 总结

模块化迁移需结合工具链、分阶段策略和严格测试，核心在于渐进式重构和显式依赖管理。通过模块化，项目将获得更强的封装性、更清晰的架构和更高效的运行时，为后续技术演进（如云原生、微服务）奠定基础。