轉自http://strong-life-126-com.iteye.com/blog/806246
及http://blog.sina.com.cn/s/blog_93dc666c0101gzlr.html
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
文件惹的禍，在各個包下創建一個即可。