module-info.java 不适用于标准 Maven 多模块项目的依赖可见性管理，它与 Maven 依赖机制正交：Maven 控制构建期依赖引入，JPMS 控制运行期包可见性；二者需协同配置才有效，否则易引发编译失败、NoClassDefFoundError 或 IDE 报红。
别把 module-info.java 当成 Maven 依赖管理替代品
Java 模块系统（JPMS）和 Maven 是两套独立机制：
- Maven 控制 编译期和构建期哪些 JAR 被拉进来、版本是否统一、scope 如何生效；
- JPMS 控制 运行期哪些包对哪个模块可见、能否反射访问、是否允许服务发现；
- module-info.java 不影响 Maven 的 dependency resolution，它不会让一个没声明依赖的模块突然“看到”另一个模块的类；
- 若你在子模块里写了
requires other.module;，但 Maven pom.xml 中没配<dependency>，编译直接失败 —— 因为 javac 根本找不到那个模块对应的自动模块名或模块 JAR。
什么时候才需要写 module-info.java？
仅当项目明确要求以下任一能力时才启用 JPMS：
- 需要强封装：用
exports private.package to specific.module;限制包暴露范围； - 要使用服务加载机制（
uses/provides），比如 SPI 插件体系； - 目标 JDK ≥ 11 且部署环境强制模块化（如某些容器或 GraalVM 原生镜像）；
- 你已接受放弃部分 Spring Boot 2.x/3.x 的自动配置兼容性（Spring 对 JPMS 支持仍有限，尤其在类路径扫描阶段）。
绝大多数企业级 Maven 多模块项目（含 Spring、MyBatis、Dubbo 等）目前无需也不建议主动开启模块化。强行添加 module-info.java 反而制造“变量可见性黑洞”——因为模块未导出、未声明依赖、或自动模块名解析失败，导致 IDE 和构建工具行为不一致。
真正解决“变量不可见”的正确路径
所谓“变量可见性黑洞”，95% 情况下是 Maven 层面的问题，不是 Java 模块问题。按优先级排查：
立即学习“Java免费学习笔记（深入）”；
-
检查子模块是否正确定义了对其他模块的 dependency：例如
service模块要用common里的工具类，就必须在service/pom.xml中声明：<dependency><groupId>com.example</groupId><artifactId>common</artifactId></dependency> - 确认父 POM 正确使用 <dependencyManagement>：避免子模块各自声明不同版本，造成编译时用 v1、运行时加载 v2 导致符号不匹配；
-
验证模块间 scope 是否合理：比如
test依赖泄漏进compile，或provided依赖未被显式排除，导致 IDE 认为类存在但实际打包缺失； - IntelliJ IDEA 中刷新 Maven 项目：右键父模块 → Reload project，或点击 Maven 工具栏的刷新按钮；避免缓存残留导致“明明配了依赖却报 red underlines”；
-
禁用或延迟引入 module-info.java：除非有强需求，否则先删掉所有
module-info.java，确保 Maven 依赖链完全通畅后再评估是否模块化。
如果坚持要用 module-info.java，必须同步满足三个条件
否则必掉坑：
-
所有参与模块都必须有 module-info.java：不能只给部分模块加，否则非模块化模块会变成“自动模块”，名字由 JAR 名推导（如
common-1.0.jar→ 自动模块名common），极易冲突或不可预测； -
Maven 构建需启用模块路径（--module-path）而非类路径（-cp）：需配置
maven-compiler-plugin的<source>11</source>和<release>11</release>，并设置<useModulePath>true</useModulePath>； -
IDEA 需开启 “Use --module-path instead of -classpath” 选项：Settings → Build → Compiler → Java Compiler → 勾选此项，否则即使代码写了
requires，IDE 仍按传统类路径解析，提示永远不准。
