Java 模块系统如何封装库内部类

本文介绍了如何使用 Java 模块系统（JPMS）来封装库的内部类，防止库的使用者直接访问和实例化这些内部类。文章阐述了 JPMS 的强封装特性，以及如何在模块定义中明确指定需要暴露的包。同时，讨论了向后兼容性问题，以及在不强制用户使用模块的情况下，如何通过约定和注解来引导用户正确使用库的 API。

Java 模块系统（JPMS）提供了一种强大的机制来控制代码的可见性，允许开发者将库的内部实现细节隐藏起来，只暴露公共 API。这有助于提高代码的可维护性、可演进性和安全性。

利用模块系统进行封装

JPMS 的核心思想是模块化，每个模块声明其依赖关系以及对外暴露的包。通过这种方式，可以实现强封装，防止外部模块访问内部包。

以下是一个示例，展示如何使用模块系统来封装一个库的内部类：

1. 组织代码结构： 将公共 API 类放在 *.api 包中，内部类放在 *.internal 包中。

2. 创建模块描述文件 module-info.java： 在库的根目录下创建 module-info.java 文件，并声明模块的名称和导出的包。

module some.library {
    exports some.library.api;
    requires etc1; // 如果你的库依赖其他模块
}

在上面的示例中，exports some.library.api; 声明了 some.library.api 包中的所有公共类对其他模块可见。而 some.library.internal 包则没有被导出，因此对其他模块是不可见的。

模块路径与类路径

需要注意的是，JPMS 为了向后兼容，引入了模块路径（module path）和类路径（class path）的概念。模块路径强制执行模块间的封装规则，而类路径则允许访问所有类，包括内部类。

如果库的使用者没有使用模块系统，而是将库放在类路径上，那么他们仍然可以访问库的内部类。这是因为类路径上的类被视为“未命名模块”的一部分，可以访问所有其他类。

解决方案：约定与注解

即使不能完全阻止用户访问内部类，仍然可以通过一些约定和注解来引导用户正确使用库的 API。

• 包命名约定： 使用明确的包命名约定，如 *.internal，来表明这些包包含内部实现细节，不应该被直接使用。
• 注解： 使用注解（如 @InternalApi）来标记内部类，明确告知用户这些类是内部使用的，可能会在未来的版本中发生变化。

package some.library.internal;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface InternalApi {
}

@InternalApi
public class InternalClass {
    // ...
}

• 语义化版本控制： 遵循语义化版本控制（Semantic Versioning），对公共 API 的更改使用主版本号的更新，而对内部类的更改则不需要。这有助于用户区分公共 API 和内部实现细节，并减少对内部类的依赖。

总结

虽然 JPMS 提供了一种强大的机制来封装库的内部类，但由于向后兼容性的考虑，不能完全阻止用户访问内部类。然而，通过合理的代码组织、包命名约定、注解和语义化版本控制，可以有效地引导用户正确使用库的 API，并提高代码的可维护性和可演进性。最终的目标是让用户明确了解哪些类是公共 API，哪些是内部实现细节，并鼓励他们只依赖公共 API。