Module-info.java解决包名冲突实战指南

Java 9+ 模块系统（JPMS）严格禁止 Split Package（包拆分）问题，即多个模块导出同一包名，而 `module-info.java` 是唯一且核心的解决方案：它要求开发者精准声明包归属——仅允许一个模块导出特定包，其余模块必须移除、重命名或重构同名包；对需反射访问的场景，优先使用受控的 `opens` 而非宽泛的 `exports`；通用代码应提取为独立模块并显式依赖，避免默认包或重复实现；同时善用 `requires transitive` 传递依赖，消除“桥接模块”误导出引发的隐性冲突——掌握这些实践，才能真正构建健壮、可维护的模块化 Java 应用。

模块系统中出现 Split Package（包拆分）问题，本质是多个模块导出了同一个包名，而 Java 9+ 的模块系统严格禁止这种行为。module-info.java 是声明模块边界、导出/开放包、声明依赖的唯一入口，因此必须通过它精准控制包归属和可见性来规避 Split Package。

明确每个包只属于一个模块

Split Package 的根源在于历史遗留或设计疏忽：比如 com.example.utils 同时出现在 core 和 common 两个模块中。解决的第一步不是改代码结构，而是强制约定——该包只能由其中一个模块定义并导出，其余模块必须移除对应包下的所有类，或重命名包（如改为 com.example.common.utils）。

在 module-info.java 中，仅在主模块中声明导出：

module com.example.core {
    exports com.example.utils;
}

其他模块不得包含同名包，也不得在自己的 module-info.java 中尝试导出相同包名——编译器会直接报错：error: package is declared in module 'xxx', which is not the current module。

用 opens 替代 exports 谨慎处理反射场景

若某模块需被其他模块通过反射访问内部类（如测试、序列化框架），但又不能公开整个包的 API，应避免误用 exports 导致包冲突。此时用 opens 更安全：

module com.example.service {
    opens com.example.service.internal to com.example.test;
}

注意：opens 不会触发 Split Package 检查（它不参与“导出包”的唯一性校验），且限定仅对指定模块开放，既满足反射需求，又不破坏模块边界。

合并或重构共享代码，避免跨模块共用未命名包

常见误区：把工具类放在默认包（unnamed package）或 java.*/javax.* 下试图绕过模块限制——这在模块化项目中不可行，且会导致运行时报 IllegalAccessError 或启动失败。

正确做法：

• 将真正通用的工具类统一提取到独立的 utils 模块，并在它的 module-info.java 中导出明确的包，如 exports com.example.shared.util;
• 其他模块通过 requires com.example.shared.util; 依赖它，不再自行复制或重写同类代码
• 若涉及 SPI（服务提供者机制），使用 uses / provides ... with 显式声明，而非靠包名隐式发现

利用 requires transitive 简化间接依赖，减少包暴露面

当模块 A 依赖模块 B，而模块 C 又依赖 A，且 C 需要用到 B 中导出的类型时，若 B 的包被 A 错误地再次导出，就可能引发间接的 Split Package 风险。

解决方案是在 A 的 module-info.java 中用 requires transitive 声明 B，让 C 自动获得对 B 导出包的访问权，而无需 A 再次导出 B 的任何包：

module com.example.api {
    requires transitive com.example.model; // C 可直接使用 model 包，A 不需 exports model
    exports com.example.api;
}

这样既保持了封装，又避免了因“桥接模块”不当导出导致的包重复。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~