如何迁移到java Module模块

下面从概念 → 准备 → 实践步骤 → 常见问题四个层面，系统讲一下如何把现有 Java 项目迁移到 Java Module（JPMS，Java Platform Module System）。

一、先理解：什么是 Java Module

Java 9 引入的 Module System，核心是：

• 用 module-info.java 明确声明：
  • 依赖哪些模块（requires）
  • 暴露哪些包（exports）
  • 允许谁使用（opens）
• 强封装：未导出的包，外部无法访问
• 替代或部分替代 classpath 的“弱约束”

module com.example.service {
    requires java.sql;
    requires com.example.common;

    exports com.example.service.api;
}

二、迁移前的准备工作

1️⃣ JDK 版本

• 至少 JDK 9+
• 推荐 JDK 11 / 17（LTS）

2️⃣ 项目结构检查

确保：

• 包结构清晰
• 没有“随便扫包 / 反射乱用”
• 第三方库是否支持 Module（很多老库不支持）

3️⃣ 构建工具

• Maven ✅
• Gradle ✅（需较新版本）

三、迁移步骤（以 Maven 为例）

步骤 1：创建 module-info.java

放在 源码根目录（如 src/main/java）：

module com.example.app {
    requires java.logging;
    requires com.google.gson;

    exports com.example.app.api;
}

⚠️ 模块名必须全局唯一（通常用反向域名）

步骤 2：处理包和访问权限

• 只 exports 对外 API 包
• 内部实现包 不要 exports
• 如需反射（如 Spring、Jackson）：

opens com.example.app.entity to spring.core;

步骤 3：处理第三方依赖

情况 A：依赖是“自动模块”

• 没有 module-info
• 文件名变成模块名（如 gson-2.10.jar → gson）

requires gson;

情况 B：依赖完全不支持 Module

• 继续使用 classpath
• 或使用 --add-exports / --add-opens（不推荐长期使用）

步骤 4：编译 & 运行

编译

javac -d out $(find src -name "*.java")

运行

java --module-path out -m com.example.app/com.example.app.Main

步骤 5：构建工具配置（Maven）

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.11.0</version>
  <configuration>
    <release>17</release>
  </configuration>
</plugin>

四、多模块项目迁移建议

推荐方式

• 每个 module 一个 module-info.java
• 明确依赖方向（避免循环）

common
service
web

module com.example.web {
    requires com.example.service;
}

五、常见坑 & 解决方案

❌ 1. 反射失败（Spring / Hibernate）

✅ 使用：

opens package to framework.module;

❌ 2. 老库不支持 Module

✅ 方案：

• 放 classpath
• 或用 Automatic-Module-Name

❌ 3. 包分裂（split packages）

✅ 一个包只能属于一个模块

❌ 4. 测试模块

✅ 测试可单独模块：

requires com.example.app;

六、迁移策略建议

✅ 渐进式迁移

• 先 1~2 个模块
• 再逐步拆分
• 不要一次性全改

✅ 新项目直接用 Module ✅ 老项目：核心模块优先

七、适合 / 不适合

✅ 适合：

• 中大型项目
• 公共库 / 框架
• 长期维护项目

❌ 不适合：

• 小工具
• 强依赖老框架（未适配）

如果你愿意，我可以：

• 帮你 把具体项目结构改成 Module
• 或针对 Spring / MyBatis / 老系统 给迁移方案