package-info.java 介绍

pacakge-info.java 是一个 Java 文件，目标是提供一个包级的文档说明及包级的注释。在 Java 5 之前，包级的文档是 package.html，是通过 JavaDoc 生成的。而在 Java 5 之后版本，包的描述以及相关的文档都可以写入 pacakge-info.java 文件。

创建 package-info.java

pacakge-info.java 不能随便被创建，会报 This is not a valid Java qualified name 错误，类名无效，因为类名不能包括 -，那么怎么创建这个文件呢？

创建一个普通的文件，文件名设置为 package-info.java 即可，或者从其它项目中复制一个。

pacakge-info.java 只需要声明 package。

package com.test;

package-info.java 用途

提供包级别的注释

为 package-info.java 添加注释

/**
 * 测试 package-info 的包注释功能
 * 
 * @author mimi
 * @since 1.0.0-RELEASE
 * @version 2.0.0-RELEASE
 */
package com.test;

执行 javadoc 之后查看效果图

• 如何在 idea 中执行 javadoc

Tools -> Generate JavaDoc，选择 Output directory，在 Othre Command line arguments 中填入 -encoding utf-8 -charset UTF-8，用于解决中文乱码问题。

提供包级别的注解

自定义一个注解

@Target(ElementType.PACKAGE)
@Retention(RetentionPolicy.RUNTIME)
public @interface PackageAnnotation {
}

在 package-info.java 上添加注解，注解加在 package 之上，注解的地方与平常用的注解稍有不同

@PackageAnnotation
package com.test;

获取包注解

public class Test {
    public static void main(String[] args) {
        System.out.println("Package Annotation：");
        Arrays.stream(Test.class.getPackage().getAnnotations())
                .forEach(System.out::println);
        System.out.println();
        System.out.println("Class Annotation：");
        Arrays.stream(Test.class.getAnnotations())
                .forEach(System.out::println);
    }
}

输入结果如下，通过包可以获取到包的注解。

Package Annotation：
@com.test.PackageAnnotation()

Class Annotation：

@Deprecated 的使用

@Deprecated 可以作用在一个类，一个方法或者一个变量上，意味着被标记的元素是过时的，在之后的版本可能不再支持，不建议使用。但如果是一整个功能下线，@Deprecated 也可以作用在包上，将整个包标记为过时。

@Deprecated
package com.test;

提供包级别的变量

package-info.java 中只能声明 default 默认访问权限的类，只能包内访问，其它包包括子包都不可访问。

package com.test;
class Constant {
    static final String PACKAGE_NAME = "Test";
}

同一个包下使用

public class Application {
    public static void main(String[] args) {
        System.out.println(Constant.PACKAGE_NAME);
    }
}