JPMS 模块系统

JPMS 的三个目标：
  1. 可靠的配置 —— 依赖在启动时校验，缺模块立即报错
  2. 强封装     —— 未 export 的包外部不可访问（含反射）
  3. 可裁剪     —— jlink 只打包用到的模块，生成精简运行时

module com.example.order {
    requires java.sql;                      // 依赖标准模块
    requires transitive com.example.common; // 传递依赖：下游也能看到
    requires static lombok;                 // 编译期需要，运行期可选

    exports com.example.order.api;          // 对外公开的包
    exports com.example.order.spi to com.example.plugin;  // 限定导出

    opens com.example.order.entity to org.hibernate.orm.core;  // 反射开放
    opens com.example.order.dto;            // 对所有模块开放反射

    uses com.example.order.spi.PaymentProvider;       // 声明服务消费者
    provides com.example.order.spi.PaymentProvider    // 声明服务提供者
        with com.example.order.impl.AlipayProvider;
}

exports vs opens 的区别：
  exports：编译期可 import，反射默认可访问 public 成员
  opens： 编译期不可 import，但反射可访问全部成员（含 private）
  框架（Spring/Hibernate/Jackson）大量用反射 → 需要 opens

# 类路径（传统）
java --class-path lib/*:app.jar com.example.Main

# 模块路径（JPMS）
java --module-path mods:lib --module com.example.order/com.example.order.Main

# 简写
java -p mods:lib -m com.example.order/com.example.order.Main

# 运行未命名模块（有 main 的 JAR）
java -p mods -m com.example.order

两类路径的区别：
  类路径 classpath
    - 所有 JAR 平等可见，无边界
    - 无法使用 jlink
    - 仍然可用（向后兼容）

  模块路径 module-path
    - 模块目录（含 module-info.class 或自动模块名）
    - 启动时解析依赖图，缺失立即报错
    - 可用 jlink 生成定制运行时

自动模块名推导规则：
  foo-bar-1.2.3.jar  →  foo.bar
  去掉版本号，把非字母数字替换为点，去重连续点
  可用 --describe-module 查看推导结果：
    jar --describe-module --file=foo-bar-1.2.3.jar

错误示例：
  module com.example.a 导出 com.example.util
  module com.example.b 也导出 com.example.util
  → 启动报错：module com.example.a reads package com.example.util from both ...

根因：
  类路径允许同名包分散在多个 JAR（合并成一个「包空间」）
  模块路径禁止一个包被两个模块导出（模块是包的唯一起源）

常见拆分包场景：
  1. javax.annotation 分散在 JDK 与第三方 JAR
  2. 老框架把 api 与 impl 放在同一个包
  3. 工具类被复制到多个模块
  4. Spring 的 spring-core 与第三方共享 org.springframework.*

应对：
  1. 升级到已模块化的库版本
  2. 用 --patch-module 临时合并（迁移期）
  3. 把冲突包收敛到一个模块

# 迁移期临时补丁：把补丁 JAR 合并进目标模块
java --module-path mods \
     --patch-module com.example.a=patch/a-extra.jar \
     -m com.example.a/com.example.a.Main

# 分析 JAR 的模块依赖
jdeps --module-path mods --multi-release 21 --print-module-deps app.jar

# 生成 module-info.java 草稿
jdeps --generate-module-info out --module-path mods app.jar

# 检查是否使用了 JDK 内部 API
jdeps --jdk-internals app.jar

# 输出示例
app.jar -> java.base
app.jar -> java.sql
app.jar -> java.logging

# 只打包用到的模块，生成精简 JRE
jlink --module-path $JAVA_HOME/jmods:mods \
      --add-modules com.example.order \
      --output custom-runtime \
      --strip-debug \
      --no-header-files \
      --no-man-pages \
      --compress=2

# 体积对比
du -sh $JAVA_HOME        # 完整 JDK：约 300MB
du -sh custom-runtime    # 定制运行时：约 40MB

# 用定制运行时启动（甚至可以用 jpackage 打成安装包）
custom-runtime/bin/java -m com.example.order/com.example.order.Main

# 打成可分发的原生安装包（Windows/macOS/Linux）
jpackage --runtime-image custom-runtime \
         --module com.example.order/com.example.order.Main \
         --name order-app --type deb

# 查看模块内容
jmod list $JAVA_HOME/jmods/java.base.jmod | head

# 创建自定义 jmod
jmod create --class-path mods/com.example.order mymod.jmod

阶段一：分析
  jdeps 扫描现有依赖，识别拆分包与 JDK 内部 API 使用

阶段二：自底向上模块化
  先模块化「叶子」库（无第三方依赖的模块），再逐层向上
  每个模块写最小 module-info：只 requires 必需，只 exports 必需

阶段三：处理第三方
  未模块化的库 → 放 module-path 当自动模块，或用 --add-modules ALL-MODULE-PATH

阶段四：收敛 opens
  给反射框架显式 opens，而非 opens 整个模块

阶段五：jlink 收尾
  生成定制运行时，接入 CI 校验依赖图

# 迁移期常用「宽进」参数，先跑通再收紧
java --module-path mods \
     --add-modules ALL-MODULE-PATH \
     --add-opens com.example.order/com.example.order.dto=org.springframework.core \
     -m com.example.order/com.example.order.Main

<!-- Maven：编译期使用 module path，且要求依赖可解析 -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <release>21</release>
  </configuration>
</plugin>

// Gradle：显式开启模块路径推断（Java 模块化插件）
java {
    modularity.inferModulePath.set(true)
}

Spring Framework 6 / Boot 3 的态度：
  1. 官方未提供 module-info，仍以自动模块形式工作
  2. 依赖大量反射 → 需要 opens，而非 exports
  3. CGLIB 动态代理需要 opens 代理目标包
  4. 常见报错：InaccessibleObjectException / IllegalAccessError

// 应用侧自建模块时，给框架开放的典型写法
module com.example.app {
    requires spring.boot;
    requires spring.context;

    opens com.example.app.config to spring.core, spring.beans;
    opens com.example.app.entity to org.hibernate.orm.core;

    exports com.example.app.api;
}

务实结论：
  1. 应用层模块化收益有限、成本高 —— 除非要做 jlink 裁剪
  2. 库/框架作者模块化收益大 —— 强封装保护内部 API
  3. 内部平台/中间件（自研）适合模块化
  4. 大量 Spring 反射的场景，JPMS 更多是「可控的 add-opens」而非纯收益

# 排查利器：打印模块描述符与依赖图
java --describe-module com.example.order
java --show-module-resolution -p mods -m com.example.order/com.example.order.Main