JDK 9 引入的模块系统（JPMS，JSR 376）是 Java 二十多年来最大的一次架构变动。它想解决一个很朴素的问题："classpath 上的东西全都能互相看见，这太危险了。"这一章讲清 module-info.java 的四个关键字、jlink 怎么把 200MB 的 JDK 裁成 40MB 的运行时，以及——那些让你头疼的 --add-opens 到底是怎么回事。

classpath 的三个顽疾：为什么要发明模块系统

是什么：模块（module）是一个带名字、带"对外接口声明"的包集合。声明写在模块根目录的 module-info.java 里。有 module-info.class 的 jar 就是"显式模块"，没有的 jar 放到模块路径上就是"自动模块"，放在类路径上则属于"未命名模块"。

为什么需要它：因为 classpath 有三个从设计上就无法解决的问题：

怎么用：最小的模块化项目就三个文件。

src/
└── com.example.app/                    // 目录名 = 模块名
    ├── module-info.java
    └── com/example/app/
        └── Main.java

// module-info.java
module com.example.app {
    requires java.sql;                  // 我需要 java.sql 模块（JDK 自带的模块）
    exports com.example.app;            // 我对外公开这个包
}

module-info.java 的四个关键字

是什么：module-info.java 里能写的指令并不多，核心就四条：requires（依赖谁）、exports（公开什么）、opens（允许反射什么）、uses/provides（服务发现）。把这四个搞清，模块系统就掌握了八成。

一个"像真项目"的 module-info.java：注意每个关键字为什么这么选

/**
 * 模块名用反向域名，且必须和目录名一致
 */
module com.example.shop {
    // ── 依赖 ──
    requires java.base;                 // 其实不用写：java.base 是所有模块的隐式依赖
    requires java.sql;
    requires transitive com.example.common;   // 我的公开 API 里出现了它的类型 -> 传递出去
    requires static org.jetbrains.annotations; // 只在编译期用到的注解

    // ── 对外开放 ──
    exports com.example.shop.api;             // 公开的 API 包
    exports com.example.shop.internal to com.example.shop.test;  // 只给测试模块用

    // ── 允许反射 ──
    // 我的实体类要给 Jackson/Hibernate 用反射读写字段，所以必须 opens
    opens com.example.shop.model to com.fasterxml.jackson.databind;

    // ── 服务 ──
    uses com.example.common.PaymentProvider;
    provides com.example.common.PaymentProvider
        with com.example.shop.impl.AlipayProvider;
}

exports 和 opens 的区别：编译期可见 ≠ 反射可用

是什么：这是整个模块系统里最容易被搞混、也最容易引发线上问题的一对概念。一句话记法：exports 管的是"编译期和普通调用能不能用"，opens 管的是"运行时反射能不能深入"。

为什么会有 opens 这个东西：因为它面对的是一个现实：Spring、Hibernate、Jackson、JUnit 这些框架，全都靠反射读写你类里的私有字段（注入 @Autowired 的字段、读写 JPA 实体、序列化对象……）。在 classpath 时代这一切都理所当然；引入模块系统后，强封装默认把这条路堵上了，所以必须由你显式告诉 JVM："这个包允许反射。"

# 现象一：启动直接报错，堆栈里出现 InaccessibleObjectException
# java.lang.reflect.InaccessibleObjectException: Unable to make field private ... accessible:
#     module java.base does not "opens java.lang" to unnamed module @1234abcd
# 这是 JDK 17+ 最常见的"升级 JDK 就起不来"的报错。

# 解法一（临时、命令行）：用 --add-opens 打开对应的包
java --add-opens java.base/java.lang=ALL-UNNAMED -jar app.jar
java --add-opens java.base/java.util=ALL-UNNAMED -jar app.jar
#   语法：--add-opens 模块名/包名=目标模块
#   ALL-UNNAMED = 所有在 classpath 上的代码（也就是绝大多数传统应用）

# 解法二（模块化应用内）：在 module-info.java 里写 opens
#   opens com.example.model to com.fasterxml.jackson.databind;

# 排查工具：找出到底是谁在用 JDK 内部 API
jdeps --jdk-internals app.jar

# 注意：老教程里的 --illegal-access=permit 已经在 JDK 17 被彻底移除
#      JDK 16 起默认值就是 deny，所以"加个参数放开一切"的时代已经结束了

实战：编译、运行、再裁出一个 40MB 的运行时

怎么用：模块化项目的编译和运行只需要多两个参数（--module-path 和 -m）。真正让人眼前一亮的是 jlink——它能把你的模块和它实际用到的 JDK 模块打包成一个定制运行时，丢掉整个 JDK 里你用不到的部分。

# ── 假设项目结构 ──
# src/com.example.app/module-info.java
# src/com.example.app/com/example/app/Main.java

# ── ① 编译 ──
javac -d out/modules/com.example.app \
      src/com.example.app/module-info.java \
      src/com.example.app/com/example/app/Main.java

# ── ② 运行（注意模块名和主类名用 "/" 分隔） ──
java --module-path out/modules -m com.example.app/com.example.app.Main
# 等价写法：java --module-path out/modules --module com.example.app/com.example.app.Main

# ── ③ 看清 JDK 自带了哪些模块（JDK 本身就是一堆模块） ──
java --list-modules | head -20        # 列出所有可用的系统模块
java --list-modules | grep jdk.crypto # 找加密相关模块（裁镜像时经常要手动补）
java --describe-module java.sql       # 看某个模块依赖谁、导出什么
java --describe-module com.example.app --module-path out/modules

jlink：把 200MB 的 JDK 裁成一个只属于你的运行时

jlink --module-path out/modules:$JAVA_HOME/jmods \
      --add-modules com.example.app \
      --output myruntime \
      --strip-debug \
      --no-header-files \
      --no-man-pages \
      --compress=zip-6

# 各参数：
#   --module-path      你的模块 + JDK 的 jmods（系统模块的来源）
#   --add-modules      以哪个模块为根，自动带上它 requires 的全部模块
#   --output           输出目录（不是一个文件，是一整个目录树）
#   --strip-debug      去掉调试信息（省最多空间）
#   --no-header-files  去掉 C 头文件（只有 JNI 开发才需要）
#   --no-man-pages     去掉 man 手册
#   --compress=zip-6   压缩级别；JDK 21 起推荐 zip-0~zip-9，老的 0/1/2 已废弃

# ── 用它跑你的程序 ──
./myruntime/bin/java -m com.example.app/com.example.app.Main

# ── 对比体积（典型结果） ──
du -sh $JAVA_HOME       # 完整 JDK：约 300MB 左右
du -sh myruntime        # 裁出来的运行时：通常 40~60MB
# 注意：如果程序用到 HTTPS、时区、字符集，记得补上 jdk.crypto.ec、jdk.localedata 等模块，
#      否则会出现"在我机器上能跑，进容器就报找不到加密算法"这类问题

模块路径 vs 类路径：三种"模块身份"的规则

是什么：同一个 jar，放在哪条路径上，身份完全不同。这决定了"它能看见谁、谁又能看见它"。

为什么这些规则值得记：因为它们决定了两件很实际的事：① 你的传统应用（未命名模块）可以通过反射访问 JDK 内部 API，只是要被 --add-opens 管；② 一旦某个库上了模块路径变成自动模块，它就会"看见一切"，这可能让原本隐藏的 split package 问题突然暴露成启动错误。

# 自动模块的名字怎么来的？
#   guava-33.4.0-jre.jar       -> guava
#   commons-lang3-3.14.0.jar   -> commons.lang3        （连字符变成点，版本号被去掉）
#   库作者的正确做法：在 MANIFEST.MF 里写一行
#     Automatic-Module-Name: com.example.mylib
#   这样无论 jar 文件怎么改名，模块名都稳定不变。**自己发的库建议都加上这一行。**

# split package 会以启动错误的形式出现：
#   java.lang.module.ResolutionException: Modules A and B export package p to module C
# 这就是 classpath 时代"同一个包被两个 jar 瓜分"的问题，在模块化后变成了硬错误。
# 修法：把其中一个依赖从模块路径挪回 classpath，或者换掉冲突的库。

到底要不要上 JPMS：一份诚实的决策表

为什么需要这一节：因为网上关于模块系统的文章大多在讲"它多好"，却很少讲"它什么时候不值得"。