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 始终是一个好习惯。 SonarCheckstyle等工具可以帮助实现这一目标。

六,结论

HTML 和 Java 文件使用之间的主要区别在于,对于 Java 文件,我们还可以使用 Java 注释。因此, package-info java 文件不仅是 包 Javadocs 的家 ,而且还是 包范围的注释 。此外,这个 用例列表将来还可以扩展

与往常一样,代码可以在 GitHub 上获取。