package-info.java 作用及用法详解

package-info.java 对于经常使用外部包的程序员来说应该是熟悉陌生人。因为不是专门开发包的程序员很少需要关注它，而又常在其他包中看到他，眼很熟。它到底有哪些特性和作用及如何使用呢？程序员讲究动口不如动手，何不创建一个试试。打开 Eclipse,new class, 哦！创建失败，‘-’ 作为特殊字符不允许在类名称里出现，什么情况。原来它本来就是个特例当然得用特别方法创建，记事本上，好了成功了。我喜欢追根问底，还什么特殊的， google  吧，果然有先辈，转过来收藏了。

原文地址： http://strong-life-126-com.iteye.com/blog/806246

特点：

首先，它不能随便被创建。在 Eclipse 中， package-info 文件不能随便被创建，会报 “Type name is notvalid” 错误，类名无效，Java变量定义规范是：字母、数字、下划线，还有那个不怎么常用的$符号（顺带说下， Java 是支持中文名称的变量，习惯挑战的同学可以尝试下，分享一下这方面的经验）。

其次，服务的对象很特殊。一个类是一类或一组事物的描述，比如 Dog 这个类，就是描述旺财的，那 package-info 这个类是描述啥的呢？它总要有一个被描述或被陈述的对象，它是描述和记录本包信息。

最后，类不能带有 public、private 访问权限。 package-info.java 再怎么特殊，也是一个类文件，也会被编译成 package-info.class ，但是在 package-info.java 中只能声明默认访问权限的类，也就是友好类。

其实还有几个特殊的地方，比如不可以继承，没有接口，没有类间关系（关联、组合、聚合等等）等。

这个文件的特殊性说完了，那再说说它有什么作用，它有三个作用：

为标注在包上 Annotation 提供便利；

声明友好类和包常量；

提供包的整体注释说明。

    我们来建立一个项目演示这三个作用，建立一个 package-info 的 Java Project ，在com.company包三个类:package-info.java是我们重点关注的，PkgAnnotation.java是一个标注在包上的注解定义，Client.java模拟业务操作类。其结构如下图：

为标注在包上 Annotation 提供便利

     首先定义一个包类型的注解，它只能放置的一个包上：

Java 代码   

     

     @Target(ElementType.PACKAGE)  

      @Retention(RetentionPolicy.RUNTIME)  

    public @interface PkgAnnotation {  

    } 

 再定义一个 package-info 类，这个是一个特殊的类，先看代码：

@PkgAnnotation  

package com.company; 

 很简单，就这么个文件，里面啥都没有，就这两句话，没有 class 类，没有常变量声明。接着写一个模拟交易类，代码如下

Java 代码：

     public class Client  {     

         public static void main(String[] args)  {  

            //可以通过 I/O 操作或配置项获得包名  

             String pkgName = "com.company";       

            Package pkg = Package.getPackage(pkgName);   

            //获得包上的注解  

             Annotation[] annotations = pkg.getAnnotations();   

            //遍历注解数组  

             for(Annotation an:annotations){  

                if(an instanceof PkgAnnotation){  

                    System.out.println("Hi,I'm the PkgAnnotation");   

                        

                }  

            }  

        }  

    }  

      运行结果如下所示：

Hi,I'm the PkgAnnotation!

 声明友好类和包常量

     这个比较简单，而且很实用，比如一个包中有很多的内部访问的类或常量，就可以统一的放到 package-info 类中，这样就方便，而且集中管理，减少 friendly 类到处游走的情况，看例子：

Java 代码：

@PkgAnnotation  

package com.company;   

 //这里是包类，声明一个包使用的公共类，强调的是包访问权限  

class PkgClass{  

    public void test(){  

    }  

}  

//包常量，只运行包内访问，适用于分“包”开发  

class PkgConst{  

    static final String PACAKGE_CONST="ABC";  

}

提供包的整体注释说明

     如果是分“包”开发，也就是说一个包实现一个业务逻辑或功能点、或模块、或组件，则需要对一个包有很好的说明，说明这个包是干啥的，有啥作用，版本变迁，特别说明等等，如下：

Java 代码：

     

     package com.company;    

      通过 javadoc 生成的 API 文档如下：

     这与包下放置 package.htm 没啥区别，只是 package-info 可以更好的在代码中维护文档的完整性，并且可以实现代码与文档同步更新， package.htm 也可以做到，不争论，建议是 Java 1.5 以上版本都使用 package-info.java 来注释。

     与 package-info 相关的问题

                      在项目开发中，可以放置在包上的常用注解有： Struts的@namespace、Hibernate 的 @FilterDef 和 @TypeDef 等等。在包下，随便一个类中的包名前加这些注解， Eclipse 会提示 “Package annotations must be in file package-info.java” ,在该包下建立 package-info.java 文件，把注解移到这里即可。

    使用 Checkstyle 插件做代码检查时，会报一个警告 “Missing package-info.java file.” 也是这个 package-info 文件惹的祸，在各个包下创建一个即可。