将传统类路径项目迁移到模块路径，核心是分阶段重构代码结构与依赖关系；变量不可见主因是模块封装强制要求显式导出包，未导出的public类也无法跨模块访问，需通过exports或opens声明可见性，并正确使用--module-path替代-cp。

将传统类路径项目迁移到模块路径，核心在于分阶段重构代码结构与依赖关系，变量可见性问题本质是模块封装边界带来的访问控制变化，不是语法错误而是设计约束。

明确模块边界与导出策略

模块系统强制要求显式声明哪些包对外可见。不能简单沿用过去“所有public类都可被任意调用”的假设。

• 每个模块必须有module-info.java，放在src/main/java根目录下
• 只导出真正需要被其他模块使用的API包，例如：exports com.example.service;
• 若某包仅需被特定模块访问，用exports com.example.internal to com.example.cli;
• 未导出的包即使含public类，也无法从模块外访问——这是变量/类不可见的主因

处理跨模块变量引用与反射场景

原类路径下通过反射访问私有字段或内部类的情况，在模块路径下会失败，需主动适配。

• 对需反射的包，添加opens com.example.config;（允许运行时深层反射）
• 若仅需模块内反射，用opens com.example.config to com.example.core;
• 避免在模块外直接引用非导出包中的public静态变量——应通过导出接口提供getter方法
• 框架类（如Spring、JUnit）可能自动添加--add-opens参数，但生产环境须显式配置

兼容未模块化第三方库

多数老版本JAR尚未提供module-info.class，它们在模块路径上成为“自动模块”，名称由JAR文件名推导（如guava-31.1-jre.jar → 模块名guava）。

• 在module-info.java中按自动模块名声明依赖：requires guava;
• 自动模块可读取所有其他模块，但自身不导出任何包——你无法import其内部类，只能用已有的public API
• 若遇“package not visible”报错，确认该类是否在自动模块的默认导出范围内（通常只有顶层包）
• 长期方案是替换为已模块化的替代库，或使用jdeps --multi-release 17分析其内部结构

构建与运行时路径切换验证

迁移过程中常混淆--class-path与--module-path，导致类加载失败或变量找不到。

• Maven编译时启用模块支持：<maven.compiler.release>17</maven.compiler.release>
• 运行命令必须用--module-path而非-cp，并指定主类模块：java --module-path out:lib -m myapp/com.example.Main
• 混合场景下（如测试仍走类路径），Gradle会自动隔离：测试代码运行在未命名模块中，不受目标模块exports限制
• 用jdeps --list-deps --module-path lib/ myapp.jar检查模块依赖图，确认无遗漏requires