Перейти к основному содержимому

Файл package-info.java

· 3 мин. чтения

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 foreach
* @version 1.1
*/
package com.foreach.finalkeyword;

Приведенный выше package-info.java сгенерирует Javadoc:

./2861acc18324a156dd26284834d9bfc6.png

Итак, так же, как мы пишем Javadoc в других местах, мы можем поместить пакет Javadoc в исходный файл Java.

4. Аннотации пакетов

Предположим, нам нужно применить аннотацию ко всему пакету . В этом случае нам может прийти на помощь package-info.java .

Рассмотрим ситуацию, когда нам нужно объявить поля, параметры и возвращаемые значения ненулевыми по умолчанию. Мы можем достичь этой цели, просто включив аннотацию @NonNullApi для ненулевых параметров и возвращаемых значений, `а также аннотацию @NonNullFields для ненулевых полей в наш файл package-info.java .`

@NonNullFields и @NonNullApi будут помечать поля, параметры и возвращаемые значения как ненулевые, если они явно не помечены как @Nullable :

@NonNullApi
@NonNullFields
package com.foreach.nullibility;

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

Существуют различные аннотации, которые можно использовать на уровне пакета. Например, в проекте Hibernate у нас есть категория аннотаций , а в проекте JAXB также есть аннотации уровня пакета .

5. Как создать файл с информацией о пакете

Создать файл с информацией о пакете довольно просто: мы можем создать его вручную или обратиться за помощью в IDE для его создания.

В IntelliJ IDEA мы можем щелкнуть правой кнопкой мыши пакет и выбрать New->package-info.java :

./4225cc001242e2a48d6bd583d5a7b51e.png

Опция Eclipse New Java Package позволяет нам сгенерировать package-info.java :

./17557701bf3b5a266a5fd2a4e7100586.png

Вышеупомянутый метод работает и для существующих пакетов. Выберите существующий пакет, выберите опцию New-> Package и отметьте опцию Create package-info.java .

Хорошей практикой всегда является обязательное включение package-info.java в правила кодирования наших проектов. В этом могут помочь такие инструменты, как Sonar или Checkstyle .

6. Заключение

Основное различие между использованием файлов HTML и Java заключается в том, что с файлом Java у нас есть дополнительная возможность использования аннотаций Java. Таким образом , java- файл с информацией о пакете является не только домом для пакета Javadocs, но и аннотаций для всего пакета . Кроме того, этот список вариантов использования может быть расширен в будущем .

Как всегда, код доступен на GitHub .