开源项目经常看到 package-info.java 文件，到底有啥用？

Bertha 。 2022-09-11 15:18 217阅读 0赞

一、pacakge-info.java介绍

pacakge-info.java是一个Java文件，可以添加到任何的Java源码包中。pacakge-info.java的目标是提供一个包级的文档说明或者是包级的注释。

![d8c883b06a70f547fdb4c7ef24249559.png][]

pacakge-info.java文件中，唯一要求包含的内容是包的声明语句，比如：

/**
    * This is domain module, the core business logic is implemented here.
    *
    */
    package com.rickie.tracking.domain;

在Java 5之前，包级的文档是package.html，是通过JavaDoc生成的。而在Java 5以上版本，包的描述以及相关的文档[java教程][java]都可以写入pacakge-info.java文件，它也用于JavaDoc的生成。

## 二、使用IDEA生成JavaDoc文档 ##

在IDEA中，选择Tools/Generate JavaDoc…菜单项，如图所示：

![91d6156f2acb29e6df6dab305a21bb88.png][]

在Generate JavaDoc窗口，输入相关设置。

第一步：选择生成JavaDoc文档的范围，下图中，我们可以选择Module模块。

第二步：输出目录最好新建一个文件夹，比较有条理和整洁。

第三步：区域（Locale）设置，决定文档的语言，简体中文就是zh\_CN、繁体(台湾)zh\_tw、繁体(香港)zh-hk、英语(香港)en-hk、英语(美国)en-us、英语(英国)en-gb、英语(全球)en-ww。

![3c1264423ca2bc8d7b168573fd1f2daf.png][]

设置完成后点击【OK】按钮即可生成Doc文档。找到输出目录，然后打开 index.html 便能看生成的文档。

![3cdbe96e52389c8e86a0368b9509b6a3.png][]

查看类的文档，如图所示：

![83aac724e55dc4824153ce106575bc02.png][]

## 三、创建package-info文件 ##

package-info文件不能随便被创建，会报“This is not a valid Java qualified name”错误，类名无效，Java变量定义规范是：字母、数字、下划线，还有那个不怎么常用的$符号，这个中划线可不在之列，那怎么创建这个文件呢？

![4d0348a6d76f20f26e2b27f731d84e9a.png][]

可以创建一个普通的文件，如图所示，文件名为package-info.java。或者更直接的办法就是从别的项目中拷贝过来一个。

![5e73930a6f5ff0be1a5728dab241977f.png][]

## 四、提供包级别的变量 ##

如果想在包里面使用对应的变量，而不想让其他包使用，就可以将变量放到package-info.java下面，实现分包自用的理念。

/**
    * This is domain module, the core business logic is implemented here.
    *
    */
    package com.rickie.tracking.domain;
    
    /**
    * 包常量
    */
    class PACKAGE_CONST{
     public static final String COLA="《COLA 4.x架构入门和项目实践》技术专栏首先介绍了COLA框架的使用入门，以及与IDEA开发工具的集成等等；然后基于COLA架构，创建DDD经典示例项目-货物运输系统，详细介绍了DDD领域建模、适配层、应用层、领域层和基础设施层的代码开发、防腐层（ACL）设计与实现、领域事件（Domain Event）入门实践、以及基于Kafka消息中间件的消息发布和订阅等等。内容由浅入深，从开发实战出发，逐步掌握基于COLA架构和DDD领域建模思想构建复杂业务应用系统。";
    }

在包内的任意类调用包常量，示例代码如下所示：

public class Test {
     public static void main(String[] args) {
     System.out.println(PACKAGE_CONST.COLA);
     }
    }

![0398f75837f9e9069fdfd3ec3dd2aabd.png][]

在包外的任意类调用包常量，则会提示报错。

## 五、提供包级别的注释 ##

使用JavaDoc的时候，通过在package-info.java添加注释，生成JavaDoc实现对应包的注释说明。

/**
    * 描述: COLA 领域模块<br>
    * This is domain module, the core business logic is implemented here. <br>
    * 创建时间: 2021/8/1 12:00 <br>
    * @version v1.0
    */
    package com.rickie.tracking.domain;
    
    /**
    * 包常量
    */
    class PACKAGE_CONST{
     public static final String COLA="《COLA 4.x架构入门和项目实践》技术专栏首先介绍了COLA框架的使用入门，以及与IDEA开发工具的集成等等；然后基于COLA架构，创建DDD经典示例项目-货物运输系统，详细介绍了DDD领域建模、适配层、应用层、领域层和基础设施层的代码开发、防腐层（ACL）设计与实现、领域事件（Domain Event）入门实践、以及基于Kafka消息中间件的消息发布和订阅等等。内容由浅入深，从开发实战出发，逐步掌握基于COLA架构和DDD领域建模思想构建复杂业务应用系统。";
    }

生成对应的JavaDoc文档，如图所示：

![479cea842a93e14be03bb530ebaa6e73.png][]

[d8c883b06a70f547fdb4c7ef24249559.png]: /images/20220828/cab61e7906c94f91b7781840241bd5c4.png
[java]: https://www.xin3721.com/eschool/Javaxin3721/
[91d6156f2acb29e6df6dab305a21bb88.png]: /images/20220828/550c0df70c0d48cba39dbf64d8822eee.png
[3c1264423ca2bc8d7b168573fd1f2daf.png]: /images/20220828/24aaca886f8340119bf073050878670a.png
[3cdbe96e52389c8e86a0368b9509b6a3.png]: /images/20220828/73c4702a8e7e4183994c8f1de13657dc.png
[83aac724e55dc4824153ce106575bc02.png]: /images/20220828/5f349dacd40e4e8eaa50c4c81745950e.png
[4d0348a6d76f20f26e2b27f731d84e9a.png]: /images/20220828/c2ded1fa317b4e79a9f79cb702b22bed.png
[5e73930a6f5ff0be1a5728dab241977f.png]: /images/20220828/beff3852b7ae42b9982ccd38237c3980.png
[0398f75837f9e9069fdfd3ec3dd2aabd.png]: /images/20220828/983386875fd6473fac823db1ec64f599.png
[479cea842a93e14be03bb530ebaa6e73.png]: /images/20220828/bdac2c0b522c4f71a8c2b46707dfc70e.png