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中只能聲明默認訪問權限的類，也就是友好類。

其實還有幾個特殊的地方，比如不可以繼承，沒有接口，沒有類間關系（關聯、組合、聚合等等）等。

這個文件的特殊性說完了，那再說說它有什么作用，它有三個作用：

1. 為標注在包上Annotation提供便利；
2. 聲明友好類和包常量；
3. 提供包的整體注釋說明。

 我們來建立一個項目演示這三個作用，建立一個package-info的Java Project，在com.company包三個類:package-info.java是我們重點關注的，PkgAnnotation.java是一個標注在包上的注解定義，Client.java模擬業務操作類。其結構如下圖：

 

1,為標注在包上Annotation提供便利

     首先定義一個包類型的注解，它只能放置的一個包上：

Java代碼  

　　/** 
 * 定義只能標注在package上的注解 3     */  
 @Target(ElementType.PACKAGE) 5  @Retention(RetentionPolicy.RUNTIME) 6     public @interface PkgAnnotation { 7     } 

再定義一個package-info類，這個是一個特殊的類，先看代碼：

@PkgAnnotation 2 package com.company; 

很簡單，就這么個文件，里面啥都沒有，就這兩句話，沒有class類，沒有常變量聲明。接着寫一個模擬交易類，代碼如下

Java代碼：

 public class Client {  2         public static void main(String[] args) {  3             //可以通過I/O操作或配置項獲得包名 
            String pkgName = "com.company";  5             Package pkg = Package.getPackage(pkgName);  6             //獲得包上的注解 
            Annotation[] annotations = pkg.getAnnotations();  8             //遍歷注解數組 
            for(Annotation an:annotations){ 10                 if(an instanceof PkgAnnotation){ 11                     System.out.println("Hi,I'm the PkgAnnotation"); 12                     /* 
 * 注解操作 14  * MyAnnotation myAnn = (PkgAnnotation)an; 15  * 還可以操作該注解包下的所有類，比如初始化，檢查等等 16  * 類似Struts的@Namespace，可以放到包名上，標明一個包的namespace路徑 17                      */           
 } 19  } 20  } 21     }  

運行結果如下所示：

Hi,I'm the PkgAnnotation!

2,聲明友好類和包常量

     這個比較簡單，而且很實用，比如一個包中有很多的內部訪問的類或常量，就可以統一的放到package-info類中，這樣就方便，而且集中管理，減少friendly類到處游走的情況，看例子：

Java代碼：

@PkgAnnotation  2 package com.company;  3  //這里是包類，聲明一個包使用的公共類，強調的是包訪問權限 
class PkgClass{  5     public void test(){  6  }  7 }  8 //包常量，只運行包內訪問，適用於分“包”開發 
class PkgConst{ 10     static final String PACAKGE_CONST="ABC"; 11 }

 

3,提供包的整體注釋說明

     如果是分“包”開發，也就是說一個包實現一個業務邏輯或功能點、或模塊、或組件，則需要對一個包有很好的說明，說明這個包是干啥的，有啥作用，版本變遷，特別說明等等，如下：

Java代碼：

  /** 
 * <b>package-info不是平常類，其作用有三個:</b><br> 3  * 1、為標注在包上Annotation提供便利；<br> 4  * 2、聲明包的私有類和常量；<br> 5  * 3、提供包的整體注釋說明。<br> 6     */  
    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文件惹的禍，在各個包下創建一個即可。