The package-info.java File – 包-信息.java文件

最后修改: 2021年 4月 17日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

In this tutorial, we’re going to understand the purpose of package-info.java and how it is useful. Simply put, package-info is a Java file that can be added to any Java package.

在本教程中，我们将了解package-info.java的目的以及它的作用。简单地说，package-info是一个Java文件，可以添加到任何Java包中。

2. Purposes of package-info

2.包-信息的目的

The package-info.java file currently serves two purposes:

package-info.java文件目前有两个用途。

  • A place for package-level documentation
  • Home for package-level annotations

Other than the aforementioned, the use-cases can be extended as required. In the future, if it’s required to add any package-level feature, this file will be a perfect place.

除了上述内容外，还可以根据需要对这些使用情况进行扩展。在未来，如果需要添加任何包级功能，这个文件将是一个完美的地方。

Let’s examine the current use cases in detail.

让我们详细研究一下目前的用例。

3. Package Documentation

3.包装文件

Prior to Java version 5, the documentation related to a package was placed in an HTML file, package.html. This is just a normal HTML file with Javadoc comments placed inside the body tag.

在Java版本5之前，与包有关的文档被放在一个HTML文件中，package.html。这只是一个普通的HTML文件，Javadoc注释放在body标签内。

As JDK 5 arrived on the scene, package.html gave way to a new option, package-info.java, which is now preferred over package.html.

随着JDK 5的出现，package.html让位于一个新的选项，package-info.java，现在它比package.html更受欢迎。

Let’s see an example of the package documentation in a package-info.java file:

让我们看看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;

The above package-info.java will generate the Javadoc:

上面的package-info.java将生成Javadoc。

So, just as we write a Javadoc in other places, we can place the package Javadoc in a Java source file.

所以，就像我们在其他地方写Javadoc一样，我们可以把包的Javadoc放在一个Java源文件中。

4. Package Annotations

4.包注释

Suppose we have to apply an annotation to the entire package. In this case, package-info.java can come to our aid.

假设我们必须对整个包应用注释。在这种情况下，package-info.java可以为我们提供帮助。

Consider a situation where we need to declare fields, parameters, and return values as non-null by default. We can achieve this goal by simply including the @NonNullApi annotation for non-null parameters and return values, and the @NonNullFields annotation for non-null fields, in our package-info.java file.

考虑一种情况，我们需要将字段、参数和返回值默认为非空。我们可以通过在package-info.java文件中为非空参数和返回值加入注解和为非空字段加入@NonNullFields注解来实现这个目标。

@NonNullFields and @NonNullApi will mark fields, parameters, and return values as non-null unless they are explicitly marked as @Nullable:

@NonNullFields和@NonNullApi将把字段、参数和返回值标记为非空，除非它们被明确标记为 @Nullable。

@NonNullApi
@NonNullFields
package com.baeldung.nullibility;

import org.springframework.lang.NonNullApi;
import org.springframework.lang.NonNullFields;

There are various annotations available to be used at the package level. For example, in the Hibernate project, we have a category of annotations, and the JAXB project also has package-level annotations.

有各种注释可以在包级使用。例如，在Hibernate项目中，我们有一个注释的类别，而JAXB项目也有包级注释。

5. How to Create a package-info File

5.如何创建一个包-信息文件

Creating a package-info file is fairly simple: we can create it manually or seek IDE help for generating the same.

创建package-info文件相当简单：我们可以手动创建它，或者寻求IDE的帮助来生成同样的文件。

In IntelliJ IDEA, we can right-click on the package and select New-> package-info.java:

在IntelliJ IDEA中，我们可以右键单击软件包，并选择New-> package-info.java。

Eclipse’s New Java Package option allows us to generate a package-info.java:

Eclipse的New Java Package选项允许我们生成一个package-info.java。

The above method works for existing packages also. Select the existing package, New-> Package option, and tick the Create package-info.java option.

上述方法也适用于现有包。选择现有的包，New-> Package选项，并勾选Create package-info.java选项。

It’s always a good practice to make the mandatory inclusion of package-info.java in our project coding guidelines. Tools like Sonar or Checkstyle can be of help in achieving this.

在我们的项目编码指南中强制加入package-info.java总是一个好的做法。像Sonar或Checkstyle这样的工具可以帮助我们实现这一目标。

6. Conclusion

6.结论

The main difference between the HTML and Java file usage is that, with a Java file, we have an additional possibility of using Java annotations. So the package-info java file isn’t just a home for package Javadocs but also package-wide annotations. Also, this list of use-cases can be extended in the future.

HTML和Java文件使用的主要区别在于，对于Java文件，我们还有一种使用Java注释的可能性。因此，package-info java文件不仅仅是包的Javadocs的家园，也是整个包的注释。另外，这个用例列表可以在未来扩展。

As always, the code is available over on GitHub.

像往常一样，代码可在GitHub上获得。