一、起源:类路径的三个固有问题

1.1 类路径的工作方式

类路径是一组目录与 JAR 的线性列表。类加载器按照列表顺序逐项查找,遇到第一个匹配的类名即返回,后续条目中同名的类不再被考虑。整个过程没有依赖声明,没有版本信息参与判定,也没有跨 JAR 的可见性约束。

三种问题由此产生。

1.2 问题一:无版本约束

类路径中同一个库只能出现一份实现类。当两个依赖各自传递引入了同一库的不同版本时,构建工具按"最近优先"或"最先声明"等规则选出一个版本进入类路径,另一个版本被丢弃。这一选择发生在构建期,且可以静默完成:

现象 成因
运行时抛 NoSuchMethodError、NoClassDefFoundError 编译期使用的版本与运行期进入类路径的版本不一致
运行时报抽象方法未实现 接口版本被降级,实现类缺少新版本新增的方法
同一库在树中出现多个版本但只有一个生效 依赖调解丢弃了其余版本,被丢弃版本的功能缺失在运行时才暴露

类路径本身不区分"编译期依赖"与"运行期依赖",也不区分同一个类名来自哪个构件。构建工具能够列出依赖树,但打包进类路径后,构件边界即消失。

1.3 问题二:无可见性边界

Java 的访问控制以类与包为粒度,而类路径不参与其中:

  1. public 类对所有 JAR 可见。 一个库内部的 public 工具类,在类路径下与业务代码处于同一平面,任何代码都可以直接引用。库作者无法通过语言机制阻止这类调用。
  2. 包级私有不是真正的边界。 只要两个 JAR 声明了同一个包名,它们在该包内的类即可互相访问对方的包级私有成员。包级私有保护的是"同一包中不相关的类",无法保护"同一包中不同构件之间"的访问。
  3. 实现类与接口无隔离。 内部实现包(如 xxx.internal)只是命名约定,编译期无法强制,重构时删除内部类属于破坏性变更,因为外部代码可能已经依赖。
  4. 同一 JAR 内的部分导出不可表达。 一个 JAR 要么全部可见,要么整体不可见,没有"仅导出部分包、其余包保留给内部"的声明方式。

1.4 问题三:运行时才暴露冲突

类路径的解析结果是运行时状态,多数冲突在编译期不可见:

编译期:
  javac 按当前类路径编译通过
  → 类路径上的类集合、包归属、版本均未被记录

运行期:
  类加载器按类路径顺序查找
  → 首次命中即生效
  → 冲突以求救式错误出现:
     NoSuchMethodError / NoClassDefFoundError / ClassCastException / AbstractMethodError

这类错误的排查成本高于编译期错误,因为触发点与成因可能相距很远:错误出现在某个业务方法中,根因是依赖树中某个传递依赖的版本被替换。此外,类路径下"缺失"与"错误"的表现不同——缺失是 ClassNotFoundException,存在但不兼容往往是 NoSuchMethodError 或 LinkageError,后者只在具体代码路径被执行时才出现。

1.5 JDK 自身的模块化动机

类路径的上述问题同样存在于 JDK 内部,JPMS(Java Platform Module System,JSR 376,随 JDK 9 发布)首先被用于 JDK 自身:

  1. 体积与可分发性。 JDK 8 及之前,核心类库集中在 rt.jar 等少数几个 JAR 中,一个应用可能只用到其中很少一部分,却必须携带完整类库。内部结构未被描述,无法据此裁剪。JDK 9 把类库拆分为约七十个平台模块,java.base 为其余所有模块隐式依赖的基础模块,模块边界使裁剪成为可计算的操作。
  2. 内部 API 无法阻止被依赖。 sun.misc.*、com.sun.* 等包在类路径下与公开 API 同等可见,第三方库大量依赖这些内部实现,导致 JDK 升级时兼容性无法保证。模块化后这些包不导出,调用在编译期与运行期均被拒绝,JDK 得以在不破坏约定的前提下演进内部实现。
  3. 类库自身的循环依赖。 拆分模块的过程暴露了类库内部原本靠单一代码库掩盖的依赖方向问题,模块声明强制依赖关系显式化与无环化。

模块系统对 JDK 的意义与其对应用的意义并不相同:JDK 侧的主要收益是可裁剪与内部 API 可控,应用侧的主要收益是依赖显式化与封装边界。二者共用同一套机制,但收益结构决定了迁移动机的差异。

1.6 本篇定位

本篇讨论模块系统的机制与落地:模块声明与依赖语义、模块路径与类路径的差异、封装与反射的边界、服务加载方式的变化、模块层与自定义运行时,以及迁移的路径与代价。

类的加载过程、类加载器层级与双亲委派模型已在 类加载机制与执行引擎 中给出,本篇只补充模块路径在查找阶段的介入方式,不重复加载、验证、准备、解析、初始化五个阶段本身。JDK 与 JRE 的组成关系见 java 完整手册,本篇不重复环境配置内容。


二、原理

2.1 模块的基本概念

2.1.1 模块、包与构件的关系

模块是一个具名的、自描述的构件单元,由三部分构成:

模块(module)
├── 模块名            全局唯一,如 com.example.core
├── 模块描述符        module-info.class,编译自 module-info.java
└── 包与类            模块所包含的全部资源,按包组织

三组标识需要区分:

标识 作用域 示例 是否要求唯一
模块名 模块图内 com.example.core 同一模块图中唯一
包名 模块内与模块之间 com.example.core.internal 全模块图内不得重复(拆分包约束)
构件坐标 构建与仓库层 com.example:core:1.2.0 仓库内以坐标加版本区分

模块名与构件坐标是两套命名空间,可以不同。模块名是模块图解析的依据,构件坐标是构建工具解析依赖的依据,二者通过构建配置建立对应关系。包名则是模块之间真正互斥的部分:同一个包不能同时属于两个模块。

2.1.2 模块声明文件的构成

模块描述符是一个名为 module-info.java 的源文件,编译后生成 module-info.class,位于模块根目录。它只包含声明,不包含可执行代码:

module com.example.app {

    requires java.logging;
    requires transitive com.example.core;
    requires static java.compiler;

    exports com.example.app.api;
    exports com.example.app.spi to com.example.plugin;

    opens com.example.app.model to com.fasterxml.jackson.databind;

    uses com.example.app.spi.Plugin;

    provides com.example.app.spi.Plugin
        with com.example.app.internal.DefaultPlugin;
}

各类声明的作用与粒度:

指令 作用对象 语义
requires 模块 声明编译期与运行期的依赖;被依赖模块的导出包对本模块可读
requires transitive 模块 本模块的依赖同时传递给依赖本模块的模块,读本模块即可读到该依赖的导出包
requires static 模块 编译期必需、运行期可选的依赖,缺失时不阻止加载,但引用其类型会在运行期失败
exports 包 包的 public 类型对所有模块可访问
exports ... to 包 + 模块列表 限定导出,仅对列出的模块可访问
opens 包 包在运行期对反射开放,编译期仍不可通过普通引用访问
opens ... to 包 + 模块列表 限定开放,仅允许列出的模块反射访问
uses 服务接口 声明本模块通过 ServiceLoader 使用某服务,是调用加载的前提
provides ... with 服务接口 + 实现类 声明本模块对某服务接口提供的一个或多个实现类

java.base 由所有模块隐式依赖,无需声明。requires transitive 与 exports 的组合决定了模块图的可读性传递路径:若模块 A 的公开 API 中出现了模块 B 的类型,则 A 应以 requires transitive 声明 B,否则依赖 A 的模块无法在编译期引用这些类型。

open module 这一修饰符表示模块内所有包对反射开放,等价于对所有包写 opens,但导出关系仍由 exports 控制:开放针对反射,导出针对编译期与普通引用,两者语义独立,可以同时存在。

2.1.3 传递依赖与静态依赖

这两类扩展声明解决的是两类常见摩擦:

  1. requires transitive 解决"API 泄漏类型不可见"。 典型场景是聚合模块(重新导出若干子模块的 API)与 API 中直接暴露第三方类型。缺少传递声明时,依赖方会收到"某类型不在可读模块中"的编译错误,被迫在自己的描述符中重复声明依赖,形成依赖关系的重复与失配。
  2. requires static 解决"编译期需要、运行期不需要"的依赖。 注解处理器依赖、编译期常量与工具类依赖属于此类。若不加 static,这类依赖会被强制带入运行期,进入模块图并占用空间;若完全不声明,编译期会失败。

需要明确的边界是:requires transitive 只影响可读性的传递,不改变类加载与实例化的时机;requires static 只影响解析与加载的可选性,代码中对静态依赖类型的实际引用在运行期仍需要该模块存在,否则以 NoClassDefFoundError 失败。它不等价于"运行期安全忽略"。

2.2 模块路径与类路径

2.2.1 查找与解析的差异

模块路径与类路径是两套不同的查找与解析模型:

维度 类路径 模块路径
解析时机 运行期按需查找,逐项扫描直到命中 启动时一次性解析出模块图,未解析的模块不被加载
依赖来源 无声明,全部条目在同一平面 由模块描述符的 requires 声明
可见性 所有 public 类型互相可见 仅被 requires 且由对方 exports 的包可见
版本处理 不参与,同名类先命中者生效 不参与,同一模块名只允许一个版本
命名 全部内容归入未命名模块 每个模块有唯一名称
包归属 允许多个 JAR 合并同一包 同一个包不得出现在两个模块中

模块路径的解析是自上而下的:从根模块集合(由启动主模块或 --add-modules 指定)出发,沿 requires 关系递归展开,得到完整的模块图(module graph)。图中的边是"可读性"关系。未出现在图中的模块不会被加载,也不构成冲突来源——这是与类路径最本质的差异:类路径是全部内容都参与查找,模块路径是只有被解析的模块才参与加载。

模块路径上的条目本身也有限制:一个模块路径条目是一个 JAR 或一个已展开的模块目录,其中应含 module-info.class(显式模块);不含描述符的 JAR 则被视为自动模块。

2.2.2 自动模块

自动模块是模块路径上没有模块描述符的 JAR。系统为其推导一个模块名,并赋予一组宽松的默认行为:

属性 规则
模块名 优先取 MANIFEST.MF 中的 Automatic-Module-Name;缺失时由文件名推导(去掉版本号与 .jar,非法字符替换为 .)
导出 导出其中所有包
依赖 可读所有其他模块,包括其他自动模块与未命名模块
传递性 被显式模块 requires 时,其全部导出包对该模块可见

自动模块的作用是过渡:让尚未模块化的第三方库能够被显式模块依赖,避免要求所有依赖同时完成模块化。它的成本集中在两点:

  1. 模块名由文件名推导时不稳定。 同一库在不同版本号命名或不同构建工具下可能得到不同的模块名,依赖它的模块描述符中的 requires 名会随之失配。工程上的应对是要求依赖方显式提供 Automatic-Module-Name,或在本地通过清单属性补齐。
  2. 导出全部包,退回到类路径的可见性水平。 自动模块不提供封装收益,其内部包同样对外可见;它也不允许其他模块对其做限定导出,因为其自身没有声明能力。

自动模块的设计取向是"先可运行,后收紧"。把未模块化的库放在类路径上,它会归入未命名模块;放在模块路径上,它成为自动模块而可被 requires。两者都不产生封装收益,区别在于后者使依赖关系可被显式声明。

2.2.3 未命名模块

类路径上的全部内容在模块化运行时会归入一个未命名模块:

  1. 可读所有模块。 未命名模块的代码可以引用模块路径上所有被解析的模块所导出的包,因此从类路径调用模块化库是可行的。
  2. 不被任何具名模块依赖。 具名模块无法 requires 未命名模块,无法引用其中的类型。依赖方向因此是单向的:类路径内容可以读取模块路径内容,反之不可行。
  3. 导出全部包但不产生可读关系。 未命名模块导出其全部包,但由于没有具名模块能读它,这一导出在模块图内没有效果。
  4. 在模块图之外。 未命名模块不参与 requires 解析,其内容在启动时不被枚举,仅在类加载时按需查找,行为与沿用类路径时一致。

混合运行(模块路径与类路径同时存在)因此呈现一种不对称状态:模块化的部分获得封装与显式依赖,未模块化的部分退回到原有模型,两者之间只有"未命名模块读到具名模块"这一个可用方向。这类混合是可运行且常见的形态,代价是封装收益只覆盖模块路径部分,且依赖关系图中存在一段不可见区域。

2.2.4 拆分包问题

拆分包指同一个包出现在两个模块中。模块路径下这是解析错误,而非可静默容忍的情况:

场景 结果
两个显式模块导出同一包 解析失败,指出两个模块都导出该包
显式模块与自动模块含同一包 解析失败,两者都是具名模块
显式模块与类路径内容含同一包 不报错,但同名类只从显式模块加载,类路径中的同名包对模块化代码不可见,可能造成"类存在却行为不一致"
两个未命名模块条目含同一包 归入同一未命名模块,行为与类路径一致,先命中者生效

拆分包的常见来源是历史遗留的"核心包 + 扩展包"结构、api 与 impl 被拆分到不同构件中、以及依赖被着色(shade)后与原始 JAR 同时存在。规避方式有三类:

  1. 合并构件。 把同包的类合并到同一模块,适用于同一项目的自有构件。
  2. 重命名包。 对第三方库使用重定位(relocation)后不再与原 JAR 同包,代价是引入额外的构建步骤。
  3. 保留在类路径。 将涉及拆分包的依赖留在类路径,使其归入未命名模块,避免解析冲突,代价是这些依赖不参与封装。

2.2.5 混合使用的实际形态

现实工程中三类模块常常同时存在,其组合方式决定了可用能力:

模块路径
├── 显式模块        自有模块、已模块化的第三方库
│                     ├─ 可 requires 其他显式模块
│                     └─ 可 requires 自动模块
├── 自动模块        未模块化的第三方库(在模块路径上)
│                     └─ 导出全部包,可读全部模块
│
类路径
└── 未命名模块      未迁移的代码与依赖
                      ├─ 可读以上所有模块
                      └─ 不被以上任何模块可读

由此可得一条判据:迁移的推进方向是从未命名模块向显式模块逐个移动,每移动一个单元,该单元获得封装与显式依赖,同时失去对仍留在类路径上的内容的可见性。 迁移顺序需要与依赖方向一致,否则会产生"具名模块需要引用类路径类"的不可实现状态。

2.3 封装与反射

2.3.1 强封装下的反射限制

模块系统在 Java 反射之上增加了一层访问检查。这项检查独立于类的访问修饰符:即使目标是 public 成员,若其所在包未被导出或未被开放,跨模块的反射访问仍会被拒绝。

反射访问的判定顺序(模块化运行时)

1. 目标类型所在包是否被导出?
        ├─ 是 → 普通引用与反射均可(受访问修饰符约束)
        └─ 否 → 继续

2. 目标类型所在包是否被开放(opens)给调用方模块?
        ├─ 是 → 反射可访问(setAccessible 生效)
        └─ 否 → 判定不通过 → InaccessibleObjectException

关键点在于 exports 与 opens 解决的是不同问题:exports 使包在编译期可被引用、在运行期可被普通访问,但不承诺允许反射深入;opens 专门针对反射,使包内的类型与成员可被 setAccessible 打开,但不使包在编译期可被引用。一个包可以同时导出与开放,也可以只做其中之一。

从 JDK 9 到 JDK 17,默认行为收紧的过程:

版本 默认行为
JDK 9~15 非法反射访问默认被允许但打印警告,可用 --illegal-access 调整
JDK 16 默认改为拒绝,--illegal-access=permit 仍可临时开启
JDK 17 起 --illegal-access 被移除,非法反射访问一律拒绝,只能显式开放

拒绝时的异常类型是 InaccessibleObjectException,消息中会指出目标成员、所在模块与调用方模块。这与反射自身的访问控制在层次上是叠加关系:模块检查先于成员可访问性检查。反射的 setAccessible、getDeclaredXxx 等能力与其常规代价见 反射,本篇只说明模块层新增的边界。

2.3.2 opens、opens to 与命令行参数

开放内部包有三种写法,作用范围与生命周期不同:

方式 生效范围 生效时机 适用
opens pkg; 所有模块 该模块被加载时 框架访问面广、无法枚举调用方
opens pkg to M; 仅列出的模块 M 同上 已知调用方,收窄暴露面
--add-opens m/pkg=target 由参数决定 启动时,作用于运行期 无法修改被开放模块(第三方库或 JDK 自身)

三者的取舍:

  1. opens 与 opens to 是模块自身的声明,随构件一起发布,可被审计与版本管理;--add-opens 是启动参数,作用于运行期,不改变构件本身。
  2. 限定开放优于无限制开放。 opens pkg to com.fasterxml.jackson.databind 把反射权限收敛到具体模块,open module 或 opens pkg 则对所有模块开放。在自身可修改的前提下,限定形式是更小的暴露面。
  3. 命令行参数适用于无法修改的目标。 对 JDK 内部包(如 java.base/java.lang)与未模块化依赖,只能通过 --add-opens 开放。它是过渡手段,且会把参数固化进启动脚本或部署清单。

命令行参数还有几个常被混淆的成员:

参数 作用 与反射的关系
--add-opens m/pkg=target 运行期开放包,允许 setAccessible 直接决定反射是否被拒
--add-exports m/pkg=target 使包在编译期与运行期可被普通引用 不承诺允许反射;用于访问未导出 API
--add-reads m=target 增加可读性边,不改变对方导出 用于跨越 requires 声明缺失
--patch-module m=path 把额外内容并入指定模块 测试与补丁场景,影响包归属

--add-exports 与 --add-opens 的差别是最容易出错的一处:编译期通过 --add-exports 能引用某类型,不代表运行期能对它做 setAccessible,后者需要 --add-opens。

高危 对 JDK 内部包或第三方库开放内部包(opens、open module、--add-opens、--add-exports)

  • 影响范围:开放内部包使原本不可访问的类型与成员对指定范围可见,直接后果是封装失效与升级脆弱性——被开放包的内部结构在 JDK 或依赖升级时可能变更,依赖这些内部结构的代码会在升级后以 InaccessibleObjectException、NoSuchMethodError 或字段值异常等形式失败,且失败点在运行期。使用 --add-exports 访问 JDK 内部 API 的代码在目标 JDK 版本中若该 API 被移除,编译即失败;使用 --add-opens 的代码则把失败推迟到运行期。此外,开放范围过宽(ALL-UNNAMED 或无限制 opens)会使任何位于未命名模块或相应模块的代码都能反射改写内部状态,破坏不变量。
  • 回滚方式:移除对应的 opens、--add-opens、--add-exports 参数并恢复构建产物;若移除后框架无法工作,说明该框架确实依赖内部访问,此时应改为升级框架到支持模块化访问的版本,或改用限定开放(opens pkg to 具体模块)收窄范围,而不是保留无限制开放。回滚前应记录每一处开放的目标、调用方与原因,形成清单。
  • 替代做法:优先为反射框架提供显式配置(DTO 类型、绑定类、映射声明),使其不需要扫描与反射访问内部结构;对第三方库优先选择已提供模块描述符或 Automatic-Module-Name 的版本;对自身模块优先使用限定导出与限定开放。

2.3.3 对依赖注入与序列化框架的影响

以反射为主要机制的框架在模块化下会遇到两类问题,一是访问被拒,二是扫描范围缩小。

访问被拒出现在框架对一个未开放包中的类做 setAccessible 的场景:构造实例、注入字段、读取属性、调用方法。典型链路是框架从类名或类路径扫描得到目标类型,随后尝试打开其字段或构造器。

扫描范围缩小出现在框架通过遍历类路径枚举类型的场景。模块化运行时,类路径上的内容归入未命名模块,模块路径上的内容不在类路径中,沿用"扫描 classpath 上的所有 JAR"这一实现的框架将找不到模块路径上的类。因此模块化应用通常需要显式声明框架所需的类型(扫描包、实体列表、绑定类),而不是依赖扫描。

框架类别 典型访问目标 需要的声明或参数
依赖注入(构造与字段注入) 目标类的构造器、字段 目标包对框架模块 opens,或框架模块被列入限定开放
JSON 序列化/反序列化 数据类的字段与构造器 数据类所在包 opens 给序列化库;部分库支持显式注册类型以规避反射
对象关系映射 实体字段、代理生成 实体包 opens;字节码生成需要目标类可读且字段可访问
注解驱动的校验与绑定 字段、方法、注解 同上,注解需 RUNTIME 保留且类型可访问

序列化在模块化下的另一个约束与 Serializable 有关:反序列化需要对目标类做反射构造,未导出包中的可序列化类在反序列化时同样受模块检查约束。序列化机制本身与各类序列化技术选型的对照见 序列化与反序列化。

Spring 等容器对模块化的支持程度与其版本相关:较新的版本提供了对显式注册与 opens 场景的适配,但基于注解扫描的默认行为在模块化下需要额外的类型注册。容器启动流程与 Bean 装配的完整过程见 Spring Framework 核心体系,本篇不重复。

2.3.4 对字节码增强与诊断工具的影响

字节码增强与诊断工具需要读取或改写类定义,模块化对其施加三类约束:

  1. 类型定义的可读性。 增强工具需要在运行时解析目标类的字节码,涉及读取其常量池中引用的类型。若目标类所在模块未导出相关包,解析过程可能失败或得到不完整的类型信息。
  2. 反射改写内部状态。 部分增强与诊断工具通过反射读写目标对象的字段(例如修改代理状态、探针计数)。这类操作受 2.3.1 的模块检查约束,需要目标包对工具模块开放。
  3. 代理(agent)与类重定义的模块归属。 通过 -javaagent 挂载的代理在启动时被加载,其类归入未命名模块或代理自身的模块。代理通过 ClassFileTransformer 收到的类定义包含模块信息,改写后的类需要保持包与模块的一致;试图把类移入其他模块或改写 module-info.class 不属于标准能力范围,会被拒绝。代理自身的权限也由清单声明控制:Can-Redefine-Classes 与 Can-Retransform-Classes 决定其能否重新定义与重转换已有类。

动态代理与反射的层次关系、setAccessible 的能力与代价、以及代理机制本身,见 反射 的高级特性矩阵与动态代理相关章节;字节码增强的实现手段(加载时织入、运行期织入与字节码工具栈)见 Java 字节码与动态代理。诊断工具的使用方式因此发生变化:

工具类别 模块化下的变化
依赖扫描与分析(列出类路径内容) 需同时处理模块路径,工具须理解模块描述符
运行期字节码增强 需要目标模块开放相关包,或改用不依赖反射的可观测接口
远程 attach 与动态探测 受模块检查约束,对 JDK 内部结构的访问需要显式开放
类层次与反射调用分析 需要模块可读性信息才能给出去重后的调用关系

可观测能力的工程实现方式见 可观测性与探针注入,诊断工具对模块与内部 API 的依赖在升级 JDK 时需一并核对。JDK 内置工具(含模块相关工具的用法)见 JDK 内置工具详解。

2.4 服务加载

2.4.1 ServiceLoader 与 SPI 模式

服务加载解决的是"接口在调用方、实现由第三方提供、双方互不依赖"的解耦场景。类路径时代的机制是一个约定路径的文本文件:

类路径方式

服务接口:com.example.spi.Plugin(在调用方或独立 API 构件中)
实现构件:META-INF/services/com.example.spi.Plugin
          文件内容为实现类的全限定名,每行一个

调用方式:ServiceLoader.load(Plugin.class)
              → 扫描类路径上所有该路径下的文件
              → 逐行读取实现类名并反射实例化

该方式的特征是:实现声明放在被加载的构件里,调用方无须知道实现是谁;同时声明形式是资源文件,不参与编译期检查,实现类名写错只会在运行期以 ServiceConfigurationError 暴露。

2.4.2 provides 与 uses 声明的意义

模块化把服务声明提升为编译期可检查的模块描述符指令:

// 服务接口所在模块
module com.example.spi {
    exports com.example.spi;
}

// 调用方模块
module com.example.app {
    requires com.example.spi;
    uses com.example.spi.Plugin;                // 声明本模块要加载该服务
}

// 实现方模块
module com.example.plugin.impl {
    requires com.example.spi;
    provides com.example.spi.Plugin            // 声明本模块提供该服务的实现
        with com.example.plugin.impl.FastPlugin,
             com.example.plugin.impl.SafePlugin;
}

两条指令的作用分别对应服务加载的两端:

指令 所在模块 作用
uses 服务接口 调用方 声明本模块将加载该服务;缺失则 ServiceLoader.load 抛异常,加载被拒绝
provides 服务接口 with 实现类 实现方 声明实现关系;无需 META-INF/services 文件,模块系统直接提供实现列表

由此带来的变化:

  1. 实现声明从资源文件变为编译期声明。 实现类必须存在、必须位于本模块、必须可被实例化,编译期即可校验,减少了运行期才发现拼写错误的情况。
  2. uses 是调用加载的前提。 模块化运行时,ServiceLoader 会校验调用方模块是否声明了 uses,未声明时抛出异常而不是静默返回空。这是与类路径行为的一处显著差异,迁移时容易遗漏。
  3. 服务发现范围改变。 模块化运行时的服务提供者来自模块图中的 provides 声明;类路径上的 META-INF/services 文件仍然被识别,但来源是未命名模块。两者可以共存。
  4. provides 的实现类不必导出。 实现类所在包可以完全不导出,外部只能通过服务接口访问。这是模块化下 SPI 模式获得封装收益的地方:实现细节对外不可见,接口契约仍然生效。

SPI 与 API 的区别在模块化下变得可直接表达:API 用 exports 暴露,SPI 用 exports 暴露接口、用 provides 暴露实现、用不导出保留实现包。类路径下这三者只能靠命名约定区分。

2.5 模块层与自定义运行时

2.5.1 模块图与解析过程

模块图是解析的产物,其构造过程如下:

输入:
    根模块集合(启动主模块、--add-modules 指定的模块)
    模块路径(显式模块与自动模块)
    requires 声明(含 transitive 与 static)

解析:
    1. 从根模块出发,沿 requires 关系递归展开
    2. requires transitive 的模块同时成为依赖方的可读模块
    3. 校验每条边:被依赖模块存在、被引用的包确实被导出
    4. 校验全局约束:同一模块名不重复、同一包不归属两个模块

输出:
    模块图(节点为模块,边为可读性关系)
    → 只有图中的模块会被加载与链接

与类路径对比,解析把"运行期逐项查找"提前为"启动时一次性建图",因此模块缺失、包冲突、导出不足这类问题在启动阶段即被报告,而不是在首次执行到相关代码路径时。

模块层(ModuleLayer)是模块图在运行期的宿主。启动时构造的模块层称为引导层(boot layer),包含平台模块与应用模块。模块层可以被动态创建,用于在同一进程中隔离加载不同版本的同一模块:

引导层
├── 平台模块(java.base 等)
└── 应用模块

自定义层(由 ModuleLayer.defineModules 构造)
├── 可依赖引导层中的模块
└── 与引导层中同名模块相互隔离(不同层中的同名模块是不同的类)

模块层的隔离能力比类路径下的类加载器隔离更规整:层与层之间的可读性关系在构造时显式声明,而不是依赖类加载器的父子委派顺序。插件系统、脚本引擎、多版本共存场景可以利用这一机制。

2.5.2 jlink 裁剪运行时

jlink 依据模块图生成一个只包含所需模块的运行时镜像。它处理的对象是模块路径上的模块,类路径上的内容不进入镜像:

# 1. 分析应用依赖的平台模块
jdeps --print-module-deps --module-path mods --multi-release 17 app.jar
# 输出形如:java.base,java.logging,java.xml

# 2. 生成裁剪后的运行时镜像
jlink --module-path "$JAVA_HOME/jmods:mods" \
      --add-modules com.example.app \
      --output image \
      --strip-debug \
      --no-header-files \
      --no-man-pages \
      --compress=2

# 3. 校验镜像内容与运行
image/bin/java --list-modules
image/bin/java -m com.example.app/com.example.app.Main

裁剪的前提与边界:

  1. 应用与依赖须位于模块路径。 裁剪结果只包含模块图中的模块,类路径内容需要另外复制,且无法随模块图一起裁剪。这是裁剪收益与迁移成本直接相关的原因。
  2. 平台模块由 jdeps 推导或显式指定。 依赖推导是静态分析,反射、ServiceLoader、资源加载与服务提供者不会体现在 jdeps 结果中,需要额外把相关模块加入 --add-modules。
  3. JDK 模块的可裁剪性来自 JDK 自身的模块化。 这一点与 1.5 的动机一致:JDK 侧收益是"可分发性",jlink 正是该能力的出口。
  4. --bind-services 使 jlink 把服务提供者一并解析进模块图,用于服务加载密集的应用;不使用该选项时,provides 声明的实现模块可能因未被 requires 而不进入镜像。

2.5.3 jpackage 打包

jpackage 把应用与裁剪后的运行时打包为操作系统原生安装包,其输入通常是一个由 jlink 产出的运行时镜像:

jpackage --type app-image \
         --name demo-app \
         --module-path image/mods \
         --module com.example.app/com.example.app.Main \
         --runtime-image image/runtime \
         --dest dist

产物形态与目标平台绑定:Windows 生成 .msi 或 .exe,macOS 生成 .dmg 或 .pkg,Linux 生成 .deb 或 .rpm。该工具面向桌面与边缘分发场景;面向服务端的容器分发通常直接使用 jlink 产出的运行时镜像组织镜像层。各工具的参数细节见 JDK 内置工具详解。

2.5.4 与容器镜像体积和启动时间的关系

裁剪运行时对容器部署的影响集中在三条路径,判读方式与部署侧的取舍分析见 Java 应用云原生部署:

路径 作用方式 需要注意的点
镜像体积 运行时层由完整 JDK/JRE 变为裁剪镜像,基础层随之减小 体积影响首次拉取、扩容与故障转移时的拉取耗时,也影响节点磁盘占用;分层优化只改增量传输,不改解包耗时
启动时间 模块图在启动时一次性解析,被加载的平台类减少,类加载与校验的范围随之缩小 收益来自"更少的模块与类被解析",量级需要实测;启动耗时的分段构成与定位手段见部署篇
参数与工具可用性 裁剪后容器内不含完整 JDK 工具链 若线上诊断依赖容器内的 JDK 工具,裁剪镜像将不具备这些能力,需要改由平台侧或旁路方式采集,或另行准备诊断镜像

必须明确的边界是:jlink 与 CDS 是互补而非替代关系。 jlink 减少参与解析与加载的模块数量,CDS 归档一次运行中已完成加载与校验的类元数据以减少重复工作。二者可以叠加使用,且相互不冲突。

高危 使用 jlink 裁剪运行时并替换生产镜像的基础运行时

  • 影响范围:裁剪后的运行时只包含模块图中的模块,任何未进入模块图的平台模块在运行期都无法加载。反射、ServiceLoader、启动流程中的隐式依赖、加密算法提供者、字符集、时区数据、日志与偏好设置存储、字体与图像编解码、归档文件系统等资源型与隐式依赖不会被 jdeps 的静态分析覆盖,遗漏时表现为运行期 ClassNotFoundException、ServiceConfigurationError 或功能静默退化(例如时区偏移、字符集回退、加密套件不可用)。此外,裁剪镜像不含完整 JDK 工具链,容器内的诊断能力同时下降;若裁剪与镜像替换在同一次发布中完成,问题归因难度上升。
  • 回滚方式:保留替换前的完整运行时镜像与镜像标签,出现异常时回退到该标签并按原部署清单重建;裁剪结果的变更应作为独立发布步骤,与业务代码发布分离,便于单独回退。裁剪产物的校验清单见 3.4.2 节,未通过清单的裁剪结果不进入生产。
  • 配套要求:裁剪结果需在测试环境跑通全部功能路径与集成测试,而非仅验证启动成功;保留一份裁剪参数与模块列表的记录,使镜像可复现;对时区、字符集、加密、序列化这类隐式依赖单独构造验证用例。

2.6 迁移的现实约束

2.6.1 第三方库未模块化

绝大多数第三方库在 JDK 9 之后并未提供模块描述符,处理方式只有两类:

方式 做法 效果与代价
作为自动模块 放入模块路径,由系统推导模块名 可被 requires,但导出全部包、模块名不稳定;不获得封装收益
留在类路径 归入未命名模块 行为不变;但具名模块无法 requires 它,若具名模块需要引用其类型则不可行

判断依据是依赖方向:若迁移中的模块在编译期需要引用该库的类型,则必须把它放到模块路径上成为自动模块,并为其固定模块名;若只在实现内部使用且不暴露其类型,则可以留在类路径。中间状态(部分模块化、部分类路径)是常态而非过渡失败。

2.6.2 拆分包的规避方式

拆分包的处置方式已在 2.2.4 列出。工程上还需注意两点:

  1. 拆分包可能来自着色。 打包时把依赖重定位进本构件,会与本构件的包结构产生交叠,也可能与运行环境中同时存在的原始 JAR 冲突。着色策略与模块化的组合需要单独评估。
  2. 拆分包判定需要工具支持。 仅凭依赖坐标无法看出包归属,需要扫描各构件的包集合后求交集。jdeps 与构建工具的模块分析能力可用于此,见 JDK 内置工具详解。

2.6.3 构建工具与测试框架的支持程度

工具 支持方式 主要摩擦点
Maven 模块描述符置于 src/main/java,编译插件自动识别 测试阶段的类路径与模块路径差异、测试依赖不在模块图上、部分插件不识别模块结构
Gradle 通过模块路径推断开关处理 module-info.java 与增量编译、注解处理器、依赖约束的交互
测试框架 需在模块化下运行,或被改回类路径执行 反射访问被拒、测试依赖不可见、mock 框架的字节码生成受模块检查约束

测试阶段的模块化是常见难点:主代码在模块路径上运行,测试代码若同样置于模块路径,则测试框架与 mock 库需要成为模块或自动模块;若把测试改回类路径执行,则测试代码归入未命名模块,可以读主模块的导出包,但主模块未导出的内部包对测试不可见——这正是许多工程选择 --patch-module 或关闭测试阶段模块路径的原因。构建侧的配置要点见 3.2 节,插件能力与绑定阶段见 Maven 常用插件 与 Maven-build 配置实践。

高危 升级或变更构建工具中与模块相关的配置(编译插件目标版本、测试阶段模块路径开关、依赖解析范围)

  • 影响范围:构建配置的变更会同时改变编译期与运行期的类可见性,且对生产代码与测试代码的影响可能不一致。把测试阶段从类路径切到模块路径,会使测试依赖、mock 框架与测试资源在模块图上的可见性变化,表现为测试大面积失败或测试被跳过;把 module-info.java 纳入构建后,未导出的包对外不可见,原本可编译的代码会变为编译失败;依赖解析范围的变化会改变进入模块路径与类路径的构件集合,可能在本地通过而在流水线失败。若变更与业务代码变更在同一次提交中完成,失败归因成本显著上升。
  • 回滚方式:构建配置的变更单独提交,回滚即恢复上一版配置并重新构建;保留变更前的构建产物与镜像标签作为对照;在流水线中先以非阻塞方式运行模块检查(仅告警不失败),观察一轮后再切换为强制。
  • 配套要求:变更前记录编译期与运行期的类可见性基线(依赖树、包归属、测试通过率),变更后逐项对照;对测试阶段采用"先关闭模块路径、再逐步开启"的推进方式,避免一次性改变全部变量。

2.6.4 迁移收益与成本的判断

收益与成本不是对称的,可按下表逐项核对:

维度 收益 成本
依赖显式化 依赖方向可被编译期校验,缺失与循环在构建期暴露 需为每个依赖确定模块名,处理自动模块名不稳定
封装 内部包可真正不导出,public 不再等同对外承诺 需重新划定导出边界,历史代码中大量内部类型被外部引用时改造量大
运行时裁剪 可生成最小运行时,减小镜像与解析范围 要求应用与依赖位于模块路径,且需验证隐式依赖
服务加载 实现声明进入编译期检查,实现包可保留不导出 uses 声明必须补齐,否则加载被拒
升级适配 内部 API 访问被前置暴露,升级风险下降 依赖内部 API 的代码需要改写或显式开放
生态适配 框架对模块化的支持随时间改善 迁移期需为框架准备显式配置,部分框架版本不支持

判断依据集中在两点:是否具备裁剪运行时的需求,以及是否存在需要强制隔离的边界。 若部署形态对镜像体积与启动时间不敏感、封装边界可由代码评审与工具约束维持,则迁移的收益主要落在"依赖显式化"一项,成本与收益的比值需要单独评估。


三、实现

3.1 模块声明实践

3.1.1 一个可运行应用的模块声明

以三层结构(API、实现、应用入口)为例,各模块的职责与导出边界如下:

// 模块一:API 与 SPI 契约,导出接口,不包含实现
module com.example.core {
    exports com.example.core.api;       // 对外 API
    exports com.example.core.spi;       // 扩展点接口

    requires transitive java.logging;   // API 中使用了 java.util.logging 类型
}
// 模块二:默认实现,仅通过 provides 暴露,实现包不导出
module com.example.core.impl {
    requires com.example.core;
    requires java.sql;                  // 仅在实现内部使用

    provides com.example.core.spi.Store
        with com.example.core.impl.jdbc.JdbcStore;
}
// 模块三:应用入口,声明依赖与使用方,开放数据包给序列化库
module com.example.app {
    requires com.example.core;
    requires transitive com.example.core.impl;   // 装配时直接引用实现类型

    requires static java.compiler;               // 仅编译期需要的注解处理相关类型

    exports com.example.app.web;                 // 仅对启动与集成测试暴露的必要包

    opens com.example.app.model
        to com.fasterxml.jackson.databind;       // 序列化库的限定开放

    uses com.example.core.spi.Store;

    provides com.example.app.spi.Bootstrap
        with com.example.app.internal.DefaultBootstrap;
}

该示例体现的四条约定:

  1. 契约模块不包含实现。 实现模块不导出实现包,只通过 provides 提供实现。外部通过接口访问,实现细节不可见。
  2. requires transitive 只用于 API 中真正暴露了对方类型的情况。 示例中 com.example.app 在装配代码里直接引用实现类型,因此做传递声明;java.sql 仅在实现内部使用,保持普通 requires,不传递。
  3. requires static 限定编译期依赖。 注解处理相关类型在运行期不需要;若运行期确有引用,该声明不能替代普通 requires。
  4. 开放范围限定到具体模块。 opens 只针对序列化库,而不是 open module 或对所有模块开放。

3.1.2 依赖方向与导出边界的取舍

导出边界的划定原则:

原则 说明 违反后果
导出的是契约,不是实现 只导出接口、数据传输对象、异常与配置类型 实现变更成为破坏性变更
导出面越小越好 优先考虑不导出,确有需要再放开 导出面一旦扩大,后续收窄属于破坏性变更
拒绝反向依赖 实现模块依赖契约模块,不反向 形成循环,模块图无法解析
传递声明按实际暴露判定 仅当公开签名中出现对方类型时才用 transitive 声明过度会使依赖方获得非必要的可读性,削弱封装

内部包不导出的约定在模块化下变为强制:包不在 exports 列表中时,其他模块在编译期无法引用,运行期也无法反射访问(除非被 opens)。这使"内部包"从命名约定变为可被构建与运行强制执行的边界。

3.1.3 模块命名规范

规范 说明
采用反向域名 与包名一致,如 com.example.core,避免与第三方模块重名
各段为合法标识符 模块名各段不能以数字开头,不能包含连字符等非法字符
使用点分层级 通过前缀表达组织与产品,避免过长的扁平名称
记录与构件坐标的对应关系 模块名与 groupId:artifactId 是两套命名空间,需显式建立对应
避免与 JDK 模块同名 重名会导致解析失败或覆盖意图落空

3.2 与构建工具配合

3.2.1 构建配置中模块路径与模块描述符的处理

模块描述符按常规源码放置即可被编译器识别:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
        <release>17</release>          <!-- 编译目标版本,需不低于 9 才支持模块描述符 -->
        <encoding>UTF-8</encoding>
    </configuration>
</plugin>

要点:

  1. module-info.java 位于 src/main/java 根目录,与包目录并列。编译器识别到该文件后按模块化方式编译,并校验 exports、requires 是否与代码中的引用一致。
  2. 编译目标版本必须不低于 9。 使用 --release 而非 source/target 组合,以避免编译期访问到与目标版本不匹配的平台 API。
  3. 注解处理器路径的配置方式在模块化下受限。 处理器依赖通常位于类路径,配置方式需与编译插件的模块处理逻辑配合,具体配置模式见 Maven-build 配置实践 与 Maven 常用插件 的编译与测试插件说明。
  4. 打包插件通常无需特殊配置。 module-info.class 会随其他类一起进入 JAR;需要确认的是打包过程未把依赖着色进同一 JAR,因为着色会使包归属变化并影响模块解析。

3.2.2 测试阶段与主代码的模块差异

测试阶段的处理方式有两条路线,取舍如下:

路线 做法 优点 代价
测试运行在类路径 关闭测试阶段的模块路径推断 测试框架与 mock 库无需模块化;可用现有全部测试依赖 测试代码无法访问主模块未导出的包;模块边界在测试中不被验证
测试运行在模块路径 为测试声明模块依赖,或以 --patch-module 把测试类并入主模块 模块边界在测试中被验证;可访问内部包 测试框架与 mock 库需可模块化;字节码生成类库受模块检查约束

关闭测试阶段模块路径的常见配置方式:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.2.5</version>
    <configuration>
        <useModulePath>false</useModulePath>   <!-- 测试以类路径方式运行 -->
    </configuration>
</plugin>

这一配置的作用范围需要明确:它只影响测试执行阶段的类加载方式,不改变主代码的模块编译。其代价是测试不再验证模块边界,因此需要另行保留一项对模块描述符的独立校验(例如在集成测试中以模块化方式启动应用)。

3.2.3 多模块工程的组织

多模块工程与 JPMS 模块的对应关系有两种组织方式:

方式一:一个构建模块对应一个 JPMS 模块(推荐)

parent
├── core            → module com.example.core
│   └── src/main/java/module-info.java
├── core-impl       → module com.example.core.impl
│   └── src/main/java/module-info.java
└── app             → module com.example.app
    └── src/main/java/module-info.java

依赖方向与 requires 方向一致,构建顺序由依赖关系决定
方式二:多个构建模块合并为一个 JPMS 模块

若干构建模块共享同一个模块名与描述符
    → 需要在打包阶段合并,描述符只能出现一份
    → 构建复杂度上升,仅在有明确理由时采用

方式一使构建依赖关系与模块依赖关系一致,构建工具能够据此推导构建顺序,也有利于增量构建。构建模块之间的依赖声明与版本管理方式见 Maven 依赖管理,多模块的 reactor 顺序按依赖关系而非声明顺序确定。方式二会引入合并步骤与描述符冲突处理,通常在拆分粒度受历史约束时才采用。

3.3 兼容性处理实践

3.3.1 反射框架需要的 opens 配置

反射框架的开放配置按"开放方"与"调用方"两侧确定:

场景 开放方 配置
自有模块中的数据传输对象被序列化库访问 自有模块 opens com.example.app.model to com.fasterxml.jackson.databind;
自有模块中的所有数据类被容器访问 自有模块 收窄为具体包的 opens,避免 open module
第三方库内部包被自有代码反射访问 第三方模块 只能通过 --add-opens,或改用不依赖反射的调用方式
JDK 内部包被框架访问 JDK 模块 只能通过 --add-opens,且需在升级 JDK 时复核该包是否仍存在

命令行参数的写法与作用对象:

# 开放 JDK 内部包给所有未命名模块(过渡手段)
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.util=ALL-UNNAMED

# 使未导出包可被编译期与运行期引用(不承诺允许反射)
--add-exports java.base/sun.nio.ch=ALL-UNNAMED

# 增加可读性边,用于跨越缺失的 requires
--add-reads com.example.app=ALL-UNNAMED

参数的组织方式与 JVM 参数一致,与实例规格绑定或与运行环境相关的参数通过部署清单注入,避免固定进镜像。

3.3.2 命令行参数的过渡方案

过渡期的参数管理需要解决三个问题:

  1. 集中与集中后的可审计性。 把 --add-opens、--add-exports、--add-reads 集中在一处(如部署清单中的环境变量或镜像内的默认参数文件),避免散落在多个启动脚本中。集中后的清单即为后续逐项消除的依据。
  2. 逐项标注原因与消除条件。 每一项开放都应记录开放对象、调用方与消除条件(例如"待框架升级到某版本后移除")。缺少标注的参数会在升级后成为难以判断是否仍需要的遗留项。
  3. 验证参数是否真正生效。 参数拼写或模块名错误时,JVM 会在启动时报告无法识别的模块或包,或在运行时报反射被拒。参数变更后需要以覆盖该代码路径的用例验证,而不是仅验证启动成功。

3.3.3 自动模块名的稳定性风险与显式模块化建议

自动模块名的不稳定来自两个来源:文件名中的版本号与命名风格差异,以及不同打包方式对文件名的处理。消除方式按依赖能否修改分为两类:

依赖类型 处理方式
可修改清单(自有或可重新打包的构件) 在 MANIFEST.MF 中设置 Automatic-Module-Name,使模块名与文件名解耦
不可修改的第三方构件 在构建阶段以打包后处理方式补充清单属性;或在其模块化版本发布后替换

Automatic-Module-Name 的作用是把"由文件名推导"改为"由声明给出",从而使 requires 中的模块名在版本升级后保持稳定。这一属性是向后兼容的:在类路径运行时它被忽略,在模块路径运行且构件无描述符时被采用。

对长期维护的工程,推荐的做法是优先做显式模块化而非长期依赖自动模块:显式模块的导出面可控、可传递声明完备、包归属明确,且不会因文件名变化导致依赖方编译失败。

3.4 运行时裁剪实践

3.4.1 jlink 的用法与镜像组织

裁剪流程与镜像目录组织:

# 1. 收集应用模块(编译产物)到 mods/
#    mods/com.example.app.jar
#    mods/com.example.core.jar
#    mods/com.example.core.impl.jar

# 2. 推导所需平台模块,人工复核结果
jdeps --print-module-deps \
      --module-path mods \
      --multi-release 17 \
      --ignore-missing-deps \
      mods/com.example.app.jar

# 3. 生成运行时镜像,显式补充隐式依赖的模块
jlink --module-path "$JAVA_HOME/jmods:mods" \
      --add-modules com.example.app,jdk.crypto.ec,jdk.zipfs,java.naming \
      --output image/runtime \
      --strip-debug \
      --no-header-files \
      --no-man-pages \
      --compress=2

# 4. 以模块方式运行
image/runtime/bin/java -m com.example.app/com.example.app.Main
镜像目录组织

image/
├── runtime/                裁剪后的运行时(基础层,随 JDK 版本更新重建)
│   ├── bin/java
│   ├── lib/modules
│   └── release
├── app/                    应用模块(业务层,随业务发布更新)
│   ├── com.example.app.jar
│   ├── com.example.core.jar
│   └── com.example.core.impl.jar
└── conf/                   外部化配置(挂载或注入,不进入镜像)

按"运行时层与应用层分离"组织,使基础层在业务发布时命中缓存,业务层成为唯一变更层。这一组织方式与镜像分层的失效判定规则一致,层的失效条件与缓存命中逻辑见 Java 应用云原生部署 与 多阶段构建。

3.4.2 裁剪后的验证清单

裁剪结果需要按下列清单逐项验证,未通过项均不应进入生产:

类别 验证项 缺失时的表现
启动 以模块方式启动成功,--list-modules 输出的模块集合符合预期 启动即失败,找不到主类或依赖模块
反射 覆盖全部反射路径的用例通过(序列化、容器装配、动态代理) 运行期 InaccessibleObjectException
资源加载 配置文件、模板、字符集、时区数据、区域数据可被读取 资源找不到、时区偏移、字符集回退
服务加载 ServiceLoader 能发现全部提供者,provides 声明的实现可用 ServiceConfigurationError 或返回空集合
加密 实际使用的算法与协议可用(传输层套件、摘要、密钥库) 握手失败或算法不可用
压缩与归档 zip、jar 与 jar:file 协议的资源访问正常 归档内容读取失败
网络 域名解析、命名服务、管理探针可用 命名服务不可用、探针端点缺失
诊断 所需的诊断能力有替代采集路径 线上无法取证
日志 日志实现被解析,日志正常输出 日志静默失效

清单的组织原则是:按能力分类而非按依赖分类。 静态依赖分析能覆盖显式引用的类,反射、服务与资源属于隐式依赖,需要按能力逐个构造用例。相关工具的参数见 JDK 内置工具详解。

3.4.3 与容器镜像分层的配合

# 基础层:裁剪运行时,仅在 JDK 版本或裁剪参数变化时重建
FROM debian:12-slim AS base
ENV TZ=Asia/Shanghai \
    LANG=C.UTF-8
COPY image/runtime /opt/java
ENV JAVA_HOME=/opt/java \
    PATH=/opt/java/bin:$PATH

# 应用层:仅包含应用模块与配置,随业务发布更新
FROM base AS app
WORKDIR /app
COPY image/app /app/mods
COPY conf /app/conf
ENTRYPOINT ["java", "-m", "com.example.app/com.example.app.Main"]

配合要点:

  1. 运行时层与应用层分开构建。 业务发布只产生应用层新层,运行时层命中缓存,增量分发量下降。
  2. 裁剪产物由构建阶段生成,不进入运行时镜像。 裁剪所依赖的完整 JDK 与 jdeps、jlink 属于构建工具,留在构建阶段。
  3. 配置不进入镜像。 外部化配置与密钥通过挂载或注入提供,镜像保持不可变。
  4. 入口使用 exec 形式。 使主进程直接接收信号,避免信号被 shell 包装拦截。基础镜像与精简镜像的兼容性代价、体积与启动时间的对照见 镜像优化实践。

3.4.4 收益度量方式

裁剪的收益需要量化后再决定是否引入其复杂度,度量维度有三:

维度 度量方式 对应收益
镜像体积 对比裁剪前后运行时层的大小与镜像总大小 拉取时间、扩容与故障转移的恢复速度、节点磁盘占用
启动耗时 对比裁剪前后从进程启动到应用就绪的耗时分布,多次采样取分布而非单次值 模块与类解析范围缩小带来的启动收益
模块集合 --list-modules 的模块数与应用实际使用模块数的对照 判断裁剪是否过度(隐式依赖被移除)或不足(未使用的模块仍被带入)

度量方式需要控制变量:裁剪前后的 JDK 主版本、JVM 参数、镜像基础层、压测模型保持一致,否则差异无法归因于裁剪本身。性能基线的采集方法见 linux: 压测与性能基线。

3.5 常见问题与排查

3.5.1 模块未找到

错误特征:

java.lang.module.FindException: Module com.example.core not found, required by com.example.app

排查顺序:

  1. 确认模块是否在模块路径上。 检查启动参数中的 --module-path 是否包含该构件,以及构件的实际路径是否正确。
  2. 确认模块名。 对显式模块,读取其 module-info.class 中的名称;对自动模块,确认清单中是否有 Automatic-Module-Name,否则按文件名推导出的名字可能与 requires 中写的不一致。
  3. 确认构件是否被错误地放在类路径上。 位于类路径的构件归入未命名模块,具名模块无法 requires 它,表现即为"模块未找到"。
  4. 确认依赖是否被依赖调解移除。 模块化不改变构建工具的依赖调解,被丢弃的传递依赖不会出现在模块路径上。
  5. 确认版本冲突。 同一模块名的两个版本同时出现在模块路径上时,报错形式会指出重复的模块名。

3.5.2 包冲突与拆分包

错误特征:

java.lang.module.ResolutionException: Modules com.example.a and com.example.b
    export package com.example.shared to module com.example.app
java.lang.module.FindException: Two versions of module com.example.core found

排查顺序:

  1. 确定为拆分包后,先定位包的归属方。 扫描冲突构件的包集合,确认是哪个包被两个模块同时包含。
  2. 按 2.2.4 的三类方式之一处置:合并构件、重命名包(重定位)、或将其中一个构件移回类路径。
  3. 区分"显式模块与类路径同包"这一不报错的情形。 此时不会抛异常,但显式模块中的同名包会遮蔽类路径中的版本,排查方向是核对两侧的实现是否为同一版本。
  4. 核对是否为版本重复。 同名模块的两个版本是硬性错误,需要借助依赖树定位引入路径并统一版本,依赖调解规则见 Maven 依赖管理。

3.5.3 反射访问被拒

错误特征:

java.lang.reflect.InaccessibleObjectException: Unable to make field private
    java.lang.String com.example.app.model.User.name accessible:
    module com.example.app does not "opens com.example.app.model" to module com.fasterxml.jackson.databind
java.lang.reflect.InaccessibleObjectException: Unable to make ... accessible:
    module java.base does not "opens java.lang" to unnamed module

排查顺序:

  1. 读取异常消息中的三个要素:目标成员、所在模块、调用方模块。这三者直接决定开放配置的写法。
  2. 判断目标归属。 若目标在自有模块中,使用限定 opens;若目标在第三方库或 JDK 中,只能使用 --add-opens。
  3. 区分 exports 与 opens。 编译期引用通过但反射失败,通常是有 exports 而无 opens。
  4. 收窄开放范围。 优先 opens pkg to 具体模块,避免 ALL-UNNAMED 与无限制 opens;开放范围过宽会把封装收益完全抵消。
  5. 确认 JDK 版本相关的默认行为。 JDK 17 起非法反射访问一律拒绝,不存在靠默认放宽绕过的路径。

3.5.4 服务加载失败

错误特征:

java.util.ServiceConfigurationError: com.example.core.spi.Store:
    module com.example.app does not declare `uses` for this service type
java.util.ServiceConfigurationError: com.example.core.spi.Store:
    Provider com.example.core.impl.jdbc.JdbcStore not found
java.util.ServiceConfigurationError: com.example.core.spi.Store:
    Provider com.example.core.impl.jdbc.JdbcStore could not be instantiated

排查顺序:

  1. 核对 uses 声明。 模块化运行时调用 ServiceLoader.load 前,调用方模块必须有 uses 服务接口,未声明时加载被直接拒绝。这是从类路径迁移时最常见的遗漏项。
  2. 核对 provides 的实现类。 实现类必须在声明它的模块中,且需为 public 并提供可访问的无参构造器。
  3. 核对提供者模块是否进入模块图。 仅声明 provides 而未被任何模块 requires 的模块不会出现在模块图中,其提供者也不可用;需要显式 requires 或在 jlink 中使用 --bind-services。
  4. 核对实现类所在包的可读性。 实现类本身可以位于不导出的包,但接口所在包必须可被实现模块读取。
  5. 核对服务接口的可访问性。 服务接口须在其模块中被导出,否则实现方无法实现它。

3.5.5 测试运行异常

现象与处置:

现象 常见成因 处置方向
测试类无法访问主代码的内部包 测试运行在类路径,主模块的包未导出 使用 --patch-module 把测试类并入主模块,或接受测试不覆盖内部包的约束
测试依赖在模块图上不可见 测试依赖被放在类路径而测试运行在模块路径 关闭测试阶段模块路径,或为测试依赖准备模块声明
mock 框架报无法创建代理或无法访问字段 字节码生成与反射访问受模块检查约束 对测试范围开放目标包,或改用无反射的替身方式
测试全部失败且无堆栈信息 测试类未能被模块系统解析 检查测试阶段的类加载方式与模块路径配置
同一测试在本地通过、流水线失败 本地与流水线的模块路径内容不同(缓存、快照版本) 对齐依赖版本与模块路径构成

测试体系的整体组织与各层职责见 Java 测试体系。

3.5.6 与 agent 或安全策略的冲突

现象与处置:

  1. agent 无法访问目标类。 通过 -javaagent 挂载的代理位于未命名模块,其反射访问目标模块的未导出包会被拒绝。处置方向是为目标包限定开放给该代理所在模块,或改用代理自身声明模块的方式;代理能否重定义或重转换类由其清单属性决定。
  2. agent 需要重定义已被加载的类。 重转换要求类所属模块允许,且代理声明了 Can-Retransform-Classes。受限时的表现是转换器被调用但修改未生效,或以 UnsupportedOperationException 失败。
  3. 安全策略与模块检查的叠加。 模块访问检查与安全管理器的权限检查是两层独立机制,前者不因授予权限而放宽。安全管理器本身在较新版本中已被弃用并计划移除,依赖它的访问控制需要重新设计;两种机制的边界与迁移方向需要在升级评估中一并考虑。
  4. 动态附加工具的可见性。 运行期附加的诊断工具读取模块内部结构时受同样约束,处置方向是为其准备显式开放参数,或改用基于公开接口的采集方式。

诊断与调优流程、容器内外的取证手段见 Java 应用诊断与部署调优。

3.6 迁移策略

3.6.1 分阶段路径

迁移按三个阶段推进,每阶段有独立的验证项与回滚方式:

阶段一:依赖优化(不改变运行方式)

目标:消除类路径上的版本冲突与内部 API 依赖,使依赖结构清晰
动作:
    - 统一依赖版本,消除同一库的多版本共存
    - 用 jdeps --jdk-internals 找出对 JDK 内部 API 的依赖并改写
    - 为自有构件补充 Automatic-Module-Name
    - 生成依赖树与包归属报告,识别拆分包
验证:依赖树无冲突;无对 sun.* / com.sun.* 的编译期依赖
回滚:本阶段不改变运行时行为,回滚即恢复依赖声明
阶段二:显式模块化(改变运行方式,风险集中于此)

目标:把选定模块迁移到模块路径,建立导出边界
动作:
    - 在依赖方向的下游模块先写 module-info.java
    - 补齐 exports、requires、uses、provides
    - 对反射框架补 opens 或改用显式配置
    - 为无法模块化的依赖确定"模块路径(自动模块)或类路径"的归属
验证:编译期通过;全部集成测试通过;运行期无 InaccessibleObjectException;
      服务加载返回的提供者集合与迁移前一致
回滚:移除 module-info.java 并恢复类路径启动方式,构建配置的模块路径开关单独回滚
阶段三:裁剪运行时(改变交付物)

目标:以 jlink 生成最小运行时,与镜像分层配合
动作:
    - 以 jdeps 推导平台模块并人工复核隐式依赖
    - 生成运行时镜像,按 3.4.2 的清单逐项验证
    - 调整 Dockerfile 的层组织,运行时层与应用层分离
验证:裁剪后镜像通过全部功能测试;启动耗时与镜像体积的度量结果符合预期
回滚:回退到未裁剪的运行时镜像标签,裁剪作为独立发布步骤与业务发布分离

高危 把应用从类路径切换到模块路径(启用模块描述符并以 --module-path 启动)

  • 影响范围:切换改变的是类的可见性与加载方式,而非代码逻辑,因此原测试通过不代表切换后可用。具体后果包括:未在 exports 中列出的包对外立即不可见,原本可编译的跨构件引用变为编译错误;未在 uses 中声明的服务加载被直接拒绝,ServiceLoader 不再返回迁移前的结果集;框架的类路径扫描找不到模块路径上的类型,装配与映射在启动或首次调用时失败;反射访问未开放包抛出 InaccessibleObjectException;拆分包的依赖在解析阶段即导致启动失败;构建期与运行期使用的模块路径构成不一致时,问题在运行期才暴露。此外,切换与业务变更同时进行会使失败归因困难。
  • 回滚方式:移除 module-info.java 并恢复类路径启动方式(-cp 与主类),构建配置中的模块路径开关单独回滚;切换按模块粒度推进而非全工程一次性切换,出现异常时只需回退已切换的模块;保留切换前的构建产物与启动参数作为对照基线。
  • 配套要求:切换前完成阶段一的依赖优化并记录基线(依赖树、包归属、服务提供者集合、测试通过率);切换后逐项对照,尤其核对服务加载返回的提供者集合与反射相关用例;切换期间保持一份可对照的启动日志,用于判断失败发生在解析阶段、类加载阶段还是首次调用。

三个阶段的关键区分是风险集中度:阶段一不改变运行时行为,属可控调整;阶段二改变类可见性与加载方式,是风险最高的阶段;阶段三改变交付物形态,风险可通过保留原镜像标签隔离。

3.6.2 每阶段的验证项与回滚方式

阶段 必须验证的内容 回滚方式 回滚的前置条件
依赖优化 依赖树无重复版本;内部 API 引用已消除;包归属报告无交叠 恢复上一版依赖声明与构建产物 记录变更前后的依赖树与包归属报告
显式模块化 集成测试通过;反射与服务加载用例通过;启动日志无模块相关警告 移除模块描述符并恢复类路径启动参数 未在同期做破坏性数据或接口变更
运行时裁剪 3.4.2 的验证清单全部通过;体积与启动耗时度量完成 回退到未裁剪的运行时镜像标签 原镜像标签仍可拉取且未被覆盖

3.6.3 不适合迁移的工程特征

以下特征会使迁移的成本明显高于收益,或使迁移在当前条件下不可行:

特征 原因
依赖大量仅支持反射访问内部结构的旧版框架 需要大范围 opens,封装收益被抵消,同时引入升级脆弱性
依赖被着色进同一 JAR 且与原始构件共存 拆分包问题难以通过重命名之外的途径规避
依赖树中存在大量已停止维护的库 无法获得 Automatic-Module-Name 或模块化版本,长期停留在自动模块状态
深度使用 JDK 内部 API 且暂无替代方案 迁移后需要长期维护 --add-exports 参数清单
部署形态对镜像体积与启动时间不敏感 阶段三的收益不成立,迁移只剩依赖显式化一项收益
存在大量跨构件互相访问内部包的历史代码 导出边界无法在不做代码重构的前提下划定
构建与测试工具版本过旧,不支持模块路径 需要先完成工具链升级,风险叠加

判断的顺序是先确认阶段三的收益是否成立,再评估阶段二的成本。 若裁剪运行时的收益不成立,则迁移的收益仅为依赖显式化与封装,此时可只推进阶段一(依赖优化),阶段二按需在关键模块上局部实施,而不是全工程铺开。


四、总结

模块系统针对的是类路径的三个固有属性: 无版本约束(同名类先命中者生效,冲突在运行期以链接错误暴露)、无可见性边界(public 即对外承诺,包级私有不构成构件间边界)、运行时才暴露冲突(解析结果不参与编译期校验)。JDK 自身的模块化动机是体积可裁剪与内部 API 可控,应用侧的动机是依赖显式化与封装边界,二者收益结构不同。

原理层面的六条主线:

  1. 模块声明。 模块由模块名、模块描述符与包构成;requires 建立可读性,exports 控制编译期可见性,opens 控制反射可访问性,uses 与 provides 描述服务关系;requires transitive 传递可读性,requires static 只要求编译期存在。
  2. 模块路径与类路径。 模块路径在启动时自上而下解析出模块图,只有图中的模块参与加载;类路径内容归入未命名模块,可读所有模块但不被任何具名模块依赖;自动模块由文件名或清单属性推导模块名、导出全部包,是过渡形态;同一个包不得归属两个模块,拆分包需要合并、重命名或退回类路径。
  3. 封装与反射。 模块检查叠加在反射访问控制之上,先判包是否导出或开放,再判成员可访问性;exports 与 opens 解决不同问题;按 opens to 收窄范围优先于 --add-opens;JDK 17 起非法反射访问一律拒绝。依赖注入、序列化、映射与字节码增强框架都受此约束,扫描式的类型发现范围也会随模块化缩小。
  4. 服务加载。 uses 是调用加载的前提,provides ... with 取代 META-INF/services 并把实现声明提升到编译期;实现类可以位于不导出的包,这是 SPI 模式获得封装收益的位置;提供者模块须进入模块图,否则不被发现。
  5. 模块层与运行时。 解析输出模块图,模块层是其运行期宿主,可动态构造以隔离同名模块;jlink 只处理模块路径上的模块,据此生成最小运行时;jpackage 面向原生安装包分发;裁剪收益体现在镜像体积、启动耗时与工具可用性三条路径,且与 CDS 互补。
  6. 迁移约束。 未模块化的依赖只能作为自动模块(可被 requires,无封装收益)或留在类路径(不可被具名模块依赖);测试阶段的模块路径是常见难点;迁移收益需与依赖显式化、封装、裁剪三项逐项对照成本。

实现层面的六项实践: 模块声明以"契约模块导出接口、实现模块只提供不导出、开放范围限定到具体模块"为基线,requires transitive 只在公开签名暴露对方类型时使用;构建侧把描述符放在源码根目录、以 --release 指定目标版本,测试阶段是否启用模块路径单独决策,多模块工程优先采用"一个构建模块对应一个模块";兼容性处理把 --add-opens 一类参数集中管理并逐项标注消除条件,为可修改的构件补 Automatic-Module-Name;运行时裁剪按能力清单验证反射、资源、服务、加密与压缩,并与镜像分层配合;问题排查按"模块未找到、拆分包、反射被拒、服务加载、测试异常、agent 冲突"六类各自的首查项推进;迁移按"依赖优化、显式模块化、裁剪运行时"三阶段推进,风险集中在第二阶段,第三阶段以独立发布步骤隔离。

需要显式防范的四类操作: 把应用从类路径切换到模块路径(改变类可见性与加载方式,可能使原本可用的代码在编译期或运行期失败)、裁剪运行时(隐式依赖遗漏会使功能静默退化)、开放内部包(封装失效并引入升级脆弱性)、变更构建工具的模块相关配置(编译期与运行期的可见性同时变化,且对测试的影响与对主代码不一致)。这类动作的统一流程是"单独提交、保留原产物与参数备回滚、先在非关键模块或测试环境验证、记录变更前后的可见性与度量基线"。

一句话记忆:类路径无版本、无边界、冲突晚暴露;模块名加描述符加包构成模块,requires 定可读、exports 定编译可见、opens 定反射可访问、uses 与 provides 定服务;模块路径启动即建图、类路径归入未命名模块、自动模块是过渡;封装检查先于成员检查、JDK 17 起非法反射一律拒绝;裁剪只处理模块路径且隐式依赖需按能力验证;迁移按依赖优化、显式模块化、裁剪运行时三步走,风险集中在第二步。