Java package-info.java文件使用学习

Posted 2021-06-27 FserSuN

1. 概述

本教程中，我们将学习package-info.java文件的用途。简而言之，package-info.java是一个Java文件，这个文件可以被添加到任何的package中。

2. package-info文件的用途

package-info文件的两大用途如下：

• 用作包级的说明文档
• 定义包级注解

除了这两点，也可以按需扩展使用。如果需要添加任何包级的特性，则可以将这些信息添加到该文件中。

3.包级的文档

jdk1.5之后引入了这个文件，用于增加包级的定义，下面是一个例子。

/**
 * 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。

4. 包级注解

Java中注解极大让我们的程序变的很优雅。常见的注解有如下类型：

public enum ElementType {
    /** Class, interface (including annotation type), or enum declaration */
    TYPE,

    /** Field declaration (includes enum constants) */
    FIELD,

    /** Method declaration */
    METHOD,

    /** Formal parameter declaration */
    PARAMETER,

    /** Constructor declaration */
    CONSTRUCTOR,

    /** Local variable declaration */
    LOCAL_VARIABLE,

    /** Annotation type declaration */
    ANNOTATION_TYPE,

    /** Package declaration */
    PACKAGE,

    /**
     * Type parameter declaration
     *
     * @since 1.8
     */
    TYPE_PARAMETER,

    /**
     * Use of a type
     *
     * @since 1.8
     */
    TYPE_USE
}

PACKAGE 即是我们要用的包级注解。 顾名思义，包级注解就是将注解加到包声明上。如同类级注解将注解加到类定义上。

类级注解：

@Service
public class StackService {
}

但包注解不能直接加到类的包上。直接这样使用会提示错误，包级注解定义需要加在package-info.java文件中。

Main.java 定义
@Pkg
package selenium;
/**
 * Created by sunfei on 2020/1/11.
 */
public class Main {
}

我们在package-info.java使用包注解

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

    String name() default "pkg";
}



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
 */
@Pkg
package selenium;

随后就可以拿到包上定义的注解信息

public class Main {
    public static void main(String[] args) {
        Package pkg = Package.getPackage("selenium");
        boolean anno = pkg.isAnnotationPresent(Pkg.class);
        Pkg pkgV = pkg.getAnnotation(Pkg.class);
        System.out.println(pkgV.name());
        System.out.println(anno);
    }
}

5. 总结

我们需要使用包级文档或包级注解时可以使用package-info文件。

例如我们开发的项目约定某些包下只能写某些功能或方法必须满足某些约定，这时就可以借助包级的注解。此外通过包文档来增加文字说明，最终生成Java文档。