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:
Итак, так же, как мы пишем 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 :
Опция Eclipse New Java Package позволяет нам сгенерировать package-info.java :
Вышеупомянутый метод работает и для существующих пакетов. Выберите существующий пакет, выберите опцию New-> Package и отметьте опцию Create package-info.java .
Хорошей практикой всегда является обязательное включение package-info.java в правила кодирования наших проектов. В этом могут помочь такие инструменты, как Sonar или Checkstyle .
6. Заключение
Основное различие между использованием файлов HTML и Java заключается в том, что с файлом Java у нас есть дополнительная возможность использования аннотаций Java. Таким образом , java- файл с информацией о пакете является не только домом для пакета Javadocs, но и аннотаций для всего пакета . Кроме того, этот список вариантов использования может быть расширен в будущем .
Как всегда, код доступен на GitHub .