1. 概述
在本教程中,我们将了解 package-info.java 的用途以及它的用途。简单来说, package-info 是一个 Java文件,可以添加到任何Java包中 。
2. package-info 的用途
package-info.java 文件当前有两个用途:
- 包级文档的地方
- 包级注释主页
除上述之外,还可以根据需要扩展用例。将来,如果需要添加任何包级功能,这个文件将是一个完美的地方。
让我们详细研究一下当前的用例。
3. 包文档
在 Java 版本 5 之前,与包相关的文档放置在 HTML 文件 package.html 中。这只是一个普通的 HTML 文件,Javadoc 注释放置在 body 标记内。
随着 JDK 5 的出现, package.html 让位于一个新选项 package-info.java , 它现在比 package.html 更受青睐。
让我们看一下 package-info.java 文件中的包文档示例:
/**
* This module is about impact of the final keyword on performance
* <p>
* This module explores if there are any performance benefits from
* using the final keyword in our code. This module examines the performance
* implications of using final on a variable, method, and class level.
* </p>
*
* @since 1.0
* @author baeldung
* @version 1.1
*/
package com.baeldung.finalkeyword;
上面的 package-info.java 将生成 Javadoc:
所以,就像我们在其他地方编写Javadoc一样,我们可以将包Javadoc放在Java源文件中。
4. 包注解
假设我们必须 对整个包应用注释 。在这种情况下, package-info.java 可以为我们提供帮助。
考虑这样一种情况,我们需要将字段、参数和返回值默认声明为非空。我们只需在 package-info.java 文件*.* 中包含用于非空参数和返回值的 @NonNullApi 注释以及用于非空字段的 @NonNullFields 注释即可实现此目标。
@NonNullFields 和 @NonNullApi 会将字段、参数和返回值标记为非空,除非它们显式标记为 @Nullable :
@NonNullApi
@NonNullFields
package com.baeldung.nullibility;
import org.springframework.lang.NonNullApi;
import org.springframework.lang.NonNullFields;
有多种注释可在包级别使用。例如,在Hibernate项目中,我们有一个类别的注释,而JAXB项目也有 包级别的注释。
5. 如何创建 包信息 文件
创建 package-info 文件相当简单:我们可以手动创建它或寻求 IDE 帮助来生成它。
在 IntelliJ IDEA 中,我们可以右键单击包并选择 New-> package-info.java :
Eclipse 的 New Java Package 选项允许我们生成 package-info.java :
上述方法也适用于现有的包。选择现有包, New->Package 选项,然后勾选 Create package-info.java 选项。
在我们的项目编码指南中强制包含 package-info.java 始终是一个好习惯。 Sonar或Checkstyle等工具可以帮助实现这一目标。
六,结论
HTML 和 Java 文件使用之间的主要区别在于,对于 Java 文件,我们还可以使用 Java 注释。因此, package-info java 文件不仅是 包 Javadocs 的家 ,而且还是 包范围的注释 。此外,这个 用例列表将来还可以扩展 。
与往常一样,代码可以在 GitHub 上获取。