Java模块化改造需分四阶段渐进实施：第一阶段用jdeps诊断依赖并可视化强耦合点；第二阶段按业务域拆Maven子模块并清理跨包调用；第三阶段从独立工具模块试点module-info.java并验证合法性；第四阶段将模块检查嵌入CI，建立契约与健康度治理机制。
在大型遗留系统中推进Java模块化改造，不能一蹴而就，必须以“可观察、可验证、不中断业务”为前提，分阶段稳扎稳打。核心不是立刻写满module-info.java，而是通过渐进式边界识别、依赖梳理和可控切分，把隐式耦合显性化、把模糊依赖结构化。
第一阶段：诊断与建模——摸清系统真实依赖
跳过这一步直接写模块声明，大概率会失败。重点不是代码行数，而是运行时和编译时的真实依赖关系。
- 用
jdeps --multi-release 17 --class-path "lib/*" -summary -recursive app.jar生成依赖摘要，识别哪些JDK内部API（如sun.misc）被滥用，这些是迁移拦路虎 - 运行
jdeps -jdkinternals app.jar，工具会直接标出替代方案（例如sun.misc.BASE64Encoder → java.util.Base64） - 导出DOT图：
jdeps --dot-output deps/ app.jar，用Graphviz可视化，找出强耦合中心模块（比如一个被90%其他类引用的Utils类），它们就是首批重构靶点 - 人工标注“逻辑边界”：结合业务域（如订单、库存、用户），在代码中圈出高内聚、低交互的包集合，哪怕它们当前物理上混在一个jar里
第二阶段：隔离与封装——从“能跑”到“可管”
目标不是立刻模块化，而是让系统具备模块化的基础条件：类加载可控、包可见性可约束、构建可分片。
- 将原单体项目按业务域拆为多个Maven子模块（如
order-core、user-api），每个子模块有独立pom.xml，但暂不加module-info.java - 在各子模块中逐步清理跨包调用：禁止
com.xxx.order.service直接newcom.xxx.user.dao，改用接口+SPI或轻量级服务发现 - 统一日志、配置、异常处理等横切关注点，抽离为
common-starter模块，避免各处重复实现 - 引入
java.base显式声明：即使不模块化，也在编译参数中加入--add-modules java.base，提前暴露潜在兼容问题
第三阶段：模块声明落地——小步验证，逐个击破
从最独立、改动最小的子模块开始，真正启用JPMS。每个模块上线前必须满足两个硬条件：能独立编译、能通过集成测试。
- 选一个无外部依赖的纯工具模块（如
date-utils）作为试点，在其根目录添加module-info.java：module com.example.dateutils { exports com.example.dateutils; } - 修改构建脚本：用
--module-path替代-cp，用--add-modules显式启用所需JDK模块（如java.sql） - 验证方式很简单：启动应用时加
--illegal-access=deny，如果没报错，说明该模块没有非法反射访问；再加--validate-modules，确认模块图合法 - 对含第三方库的模块，先用
jlink或jmod打包成自定义模块，或用Automatic-Module-NameMANIFEST属性为其赋予稳定名称，避免版本漂移
第四阶段：治理与演进——建立可持续的模块健康度机制
模块化不是一次发布就结束，而是持续治理的过程。关键指标要嵌入CI流水线。
- 在CI中加入
jdeps --check检查：禁止模块A依赖未声明的模块B，失败则阻断构建 - 定义模块契约：每个导出包需配套接口文档+最小测试集，新功能必须通过该测试集才允许合并
- 定期运行
jdeprscan扫描废弃API使用情况，尤其关注JDK升级后即将移除的类 - 建立模块依赖矩阵看板：可视化显示哪些模块依赖了
spring-corev5.x，哪些已升到v6.x，驱动统一升级节奏
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
