在設(shè)計Java API的時候總是有很多不同的規(guī)范和考量。與任何復(fù)雜的事物一樣，這項工作往往就是在考驗我們思考的縝密程度。就像飛行員起飛前的檢查清單，這張清單將幫助軟件設(shè)計者在設(shè)計Java API的過程中回憶起那些明確的或者不明確的規(guī)范。本文也可以看作為“API設(shè)計指南”這篇文章的附錄。

我們還準(zhǔn)備了一些前后比對的例子來展示這個列表如何幫助你理清設(shè)計需求，找出錯誤，識別糟糕的設(shè)計實(shí)踐以及如何尋找改進(jìn)的時機(jī)。

這個清單使用了如下的語言規(guī)范：

要 - 表示必要的設(shè)計

建議 - 表示在幾個最好的設(shè)計中選擇一個

考慮 - 表示一個可能的設(shè)計上的改進(jìn)

避免 - 表示一個設(shè)計上的缺陷

不要 - 表示一個設(shè)計上的錯誤

1. 包設(shè)計清單

1.1. 共通

• 1.1.1.    建議把API和實(shí)現(xiàn)放入不同的包

• 1.1.2.    建議把API放進(jìn)上層包，而把實(shí)現(xiàn)放進(jìn)下層包

• 1.1.3.    考慮把一組大型的API分拆進(jìn)不同的包

• 1.1.4.    考慮把API和實(shí)現(xiàn)打包進(jìn)不同的jar包

• 1.1.5.    避免API的實(shí)現(xiàn)類之間的內(nèi)部依賴

• 1.1.6.    避免把API分拆了太細(xì)

• 1.1.7.    避免把公共實(shí)現(xiàn)類放到API的包中

• 1.1.8.    不要在調(diào)用者和實(shí)現(xiàn)類之間建立依賴

• 1.1.9.    不要把沒有關(guān)系的API放進(jìn)同一個包

• 1.1.10.  不要把API和SPI（service provider interface）放進(jìn)一個包（注：兩者不同可以查看這個頁面http://stackoverflow.com/questions/2954372/difference-between-spi-and-api ）

• 1.1.11.  不要移動或者重命名一個已經(jīng)發(fā)布的公共API

1.2. 命名

• 1.2.1.    （一級）包名以公司（或者組織）的根命名空間來命名

• 1.2.2.    使用一個穩(wěn)定的產(chǎn)品名稱或者一個產(chǎn)品系列的名稱作為包的二級名稱

• 1.2.3.    使用API名稱作為包名的（三級名稱）結(jié)尾

• 1.2.4.    考慮把僅包含實(shí)現(xiàn)的包的名稱中包含"internal"這個詞（注：似乎“impl”更常見一些）

• 1.2.5.    避免使用組合起來的名稱

• 1.2.6.    避免包名和包內(nèi)的類名使用同樣的名稱

• 1.2.7.    避免在包名稱中使用“api”這個詞

• 1.2.8.    不要使用營銷，計劃，組織單元（部門）和地理名稱

• 1.2.9.    不要在包名中使用大寫字母

1.3. 文檔

• 1.3.1.    為每一個包提供一個package.html

• 1.3.2.    遵循標(biāo)準(zhǔn)的javadoc的規(guī)范

• 1.3.3.    在API的開始處用一句短小的話來概括（描述）

• 1.3.4.    提供足夠多的細(xì)節(jié)來幫助判斷是否需要使用和如何使用該API

• 1.3.5.    指出該API的入口（主要的類或者方法）

• 1.3.6.    包含覆蓋主要的，基本功能演示的樣例代碼

• 1.3.7.    包含一個指向開發(fā)者指南的超鏈接

• 1.3.8.    包含一個指向手冊的超鏈接

• 1.3.9.    指出相關(guān)的API集合

• 1.3.10.  包含API的版本號

• 1.3.11.  用 @deprecated 標(biāo)記出不再使用的API版本

• 1.3.12.  考慮添加一個版權(quán)聲明

• 1.3.13.  避免過長的包概述

• 1.3.14.  不要在發(fā)布的javadoc中包含實(shí)現(xiàn)相關(guān)的包

2. 類型設(shè)計清單（這里的“類型”個人理解為一組Api）

2.1. 共通

• 2.1.1.    確保每種（設(shè)計的）類型都有單一明確的目的

• 2.1.2.    確保每種類型代表了（業(yè)務(wù)）領(lǐng)域的概念，而不是為了（技術(shù)上）的抽象

• 2.1.3.    限制類型的總數(shù)量

• 2.1.4.    限制類型的大小

• 2.1.5.    設(shè)計相關(guān)的類型時保持和原有的類型的一致性

• 2.1.6.    建議為多種public的類型提供多種（private）的實(shí)現(xiàn)

• 2.1.7.    建議接口的實(shí)現(xiàn)類和繼承關(guān)系的類應(yīng)該在行為上保持一致性

• 2.1.8.    建議用抽象類而不是接口解耦A(yù)pi的實(shí)現(xiàn)

• 2.1.9.    建議使用枚舉而不是常量

• 2.1.10.  考慮使用泛型

• 2.1.11.  考慮在泛型參數(shù)上增加約束

• 2.1.12.  考慮使用接口來實(shí)現(xiàn)多繼承的效果

• 2.1.13.  避免為使用者的擴(kuò)展（需求）進(jìn)行設(shè)計

• 2.1.14.  避免深度的繼承層次

• 2.1.15.  不要使用public內(nèi)嵌的類型

• 2.1.16.  不要申明public和protected的變量

• 2.1.17.  不要把實(shí)現(xiàn)的繼承關(guān)系暴露給使用者

2.2. 命名

• 2.2.1.    使用名詞或者名詞詞組

• 2.2.2.    使用PascalCasing（駝峰命名法的別稱詳見http://en.wikipedia.org/wiki/CamelCase ）

• 2.2.3.    縮寫僅第一個首字母大寫

• 2.2.4.    為類型的實(shí)際作用使用精確的名稱命名

• 2.2.5.    為最常用的類型準(zhǔn)備最短最容易記憶的名稱

• 2.2.6.    所有異常都以“Exception”結(jié)尾

• 2.2.7.    使用名詞的單數(shù)（比如用Color而不用Colors）來命名枚舉類型

• 2.2.8.    考慮較長的名稱

• 2.2.9.    考慮派生類用基類的名稱結(jié)尾

• 2.2.10.  考慮為抽象類名稱使用“Abstract”開頭

• 2.2.11.  避免使用縮略語

• 2.2.12.  避免太通用的名詞

• 2.2.13.  避免同義詞

• 2.2.14.  避免在相關(guān)的Api中使用類型的名稱

• 2.2.15.  不要使用僅大小寫不同的名稱

• 2.2.16.  不要使用前綴

• 2.2.17.  不要以“I”作為接口的名稱開頭

• 2.2.18.  不要（重復(fù)）使用Java核心包中的名稱

2.3. 類

• 2.3.1.    最小化實(shí)現(xiàn)使用的依賴

• 2.3.2.    先列出public方法

• 2.3.3.    申明實(shí)現(xiàn)方法為private（這里是筆誤嗎？）

• 2.3.4.    為一個public抽象類定義至少一個public的shi

• 2.3.5.    為基本的使用情況提供足夠的缺省實(shí)現(xiàn)

• 2.3.6.    設(shè)計基本上不變的類

• 2.3.7.    把無狀態(tài)，訪問器，擴(kuò)展（mutator個人理解為多種參數(shù)形式的方法）方法集合到一起

• 2.3.8.    把擴(kuò)展方法的數(shù)量控制到最少

• 2.3.9.    考慮設(shè)計一個默認(rèn)的無參的構(gòu)造方法

• 2.3.10.  考慮重寫equal,hashCode方法

• 2.3.11.  考慮實(shí)現(xiàn)Comparable接口

• 2.3.12.  考慮實(shí)現(xiàn)Serializable接口

• 2.3.13.  考慮使類可以容易的擴(kuò)展

• 2.3.14.  考慮申明類為final

• 2.3.15.  考慮為類的實(shí)例化提供一個public的構(gòu)造方法

• 2.3.16.  考慮使用自定義的類型來增強(qiáng)類的不可變性

• 2.3.17.  考慮設(shè)計不可變的類

• 2.3.18.  避免靜態(tài)類

• 2.3.19.  避免使用Cloneable

• 2.3.20.  不要向靜態(tài)類中添加實(shí)例duixi

• 2.3.21.  不要為使用者不應(yīng)擴(kuò)展的public抽象類提供public的構(gòu)造方法

• 2.3.22.  不要濫用初始化

2.4. 接口

• 2.4.1.    為每一個public接口提供至少一個實(shí)現(xiàn)類

• 2.4.2.    為每一個public接口設(shè)計至少一個消費(fèi)方法

• 2.4.3.    不要對一個已經(jīng)發(fā)布的public接口添加新的方法

• 2.4.4.    不要使用標(biāo)記接口（標(biāo)記接口詳見http://en.wikipedia.org/wiki/Marker_interface_pattern ）

• 2.4.5.    不要把public接口設(shè)計成常量的容器（這個實(shí)在很常見啊……）

2.5. 枚舉

• 2.5.1.    考慮為枚舉類型指定一個0值（“NONE”或者“Unspecialized”等等）

• 2.5.2.    避免只有一個值的枚舉

• 2.5.3.    不要使用枚舉實(shí)現(xiàn)開放式的值集合

• 2.5.4.    不要為將來可能增加的值設(shè)計枚舉

• 2.5.5.    不要為已經(jīng)發(fā)布的版本增加新的枚舉值

2.6. 異常

• 2.6.1.    確保自定義的異?？梢员恍蛄谢?/p>

• 2.6.2.    考慮為每種類型定義一個不同的異常

• 2.6.3.    考慮為代碼訪問提供更多的異常信息

• 2.6.4.    避免深層的異常繼承

• 2.6.5.    不要從Exception和RuntimeException以外的類派生自定義異常

• 2.6.6.    不要直接從Throwable派生異常

• 2.6.7.    不要在異常信息內(nèi)包含敏感信息

2.7. 文檔

• 2.7.1.    為每種類型（的Api）配上概述

• 2.7.2.    遵循標(biāo)準(zhǔn)Javadoc的約定

• 2.7.3.    每種類型開頭以一句短小的話概述

• 2.7.4.    為是否使用以及如何使用該類型提供足夠的細(xì)節(jié)來幫助做決定

• 2.7.5.    解釋如何實(shí)例化一個類型

• 2.7.6.    為一個類型的主要的使用情景提供樣例代碼

• 2.7.7.    包含指向到開發(fā)指南的鏈接

• 2.7.8.    包含指向手冊的鏈接

• 2.7.9.    顯示相關(guān)的類型

• 2.7.10.  用@deprecated標(biāo)簽申明過時的類型

• 2.7.11.  文檔類具有不可變性

• 2.7.12.  避免冗長的類概述

• 2.7.13.  不要為私有方法生成Javadoc

3. 方法設(shè)計清單

3.1. 共通

• 3.1.1.    確保每個方法實(shí)現(xiàn)一個目的

• 3.1.2.    確保相關(guān)的方法都是一個粒度級別的

• 3.1.3.    確保沒有混合調(diào)用方法的公共代碼

• 3.1.4.    使所有方法的調(diào)用具有原子性（原子性：http://jiangyongyuan.iteye.com/blog/364010）

• 3.1.5.    設(shè)計protected方法時要像public方法一樣慎重

• 3.1.6.    限制擴(kuò)展方法的數(shù)量

• 3.1.7.    設(shè)計擴(kuò)展方法需要具有較強(qiáng)的穩(wěn)定性

• 3.1.8.    建議為一系列重載的方法設(shè)計一個泛型的方法

• 3.1.9.    考慮使用泛型方法

• 3.1.10.  考慮設(shè)計方法對，即兩個方法的作用是相反的

• 3.1.11.  避免“helper”方法

• 3.1.12.  避免長時間執(zhí)行的方法

• 3.1.13.  避免調(diào)用者在普通使用中需要手動寫循環(huán)

• 3.1.14.  避免可選的參數(shù)影響方法的行為

• 3.1.15.  避免不可重復(fù)調(diào)用的方法

• 3.1.16.  不要刪除一個已經(jīng)發(fā)布的方法

• 3.1.17.  不要在沒有提供替換方法前把一個已經(jīng)發(fā)布的方法標(biāo)記為過時

• 3.1.18.  不要修改一個已經(jīng)發(fā)布的方法的簽名

• 3.1.19.  不要修改一個已經(jīng)發(fā)布的方法的可觀測行為（也許指的是輸出之類）

• 3.1.20.  不要增加一個已經(jīng)發(fā)布方法的調(diào)用條件

• 3.1.21.  不要減少一個已經(jīng)發(fā)布方法的調(diào)用結(jié)果

• 3.1.22.  不要為已經(jīng)發(fā)布的public接口新增方法

• 3.1.23.  不要為已經(jīng)發(fā)布的Api新增重載

3.2. 命名

• 3.2.1.    用給力的，有表達(dá)力的動詞作為名稱起始

• 3.2.2.    使用駝峰命名法（好奇怪，前面寫的是PascalNaming）

• 3.2.3.    為JavaBean的私有屬性預(yù)留“get”“set”“is”等訪問方法

• 3.2.4.    使用對調(diào)用者熟悉的詞語

• 3.2.5.    盡量使用英語口語

• 3.2.6.    避免使用縮略語

• 3.2.7.    避免使用一般的動詞

• 3.2.8.    避免同義詞

• 3.2.9.    不要使用“黑話”

• 3.2.10.  不要依靠參數(shù)的名稱和類型判斷方法的意義

3.3. 參數(shù)

• 3.3.1.    為參數(shù)選擇最合適的類型

• 3.3.2.    在相關(guān)方法的調(diào)用中對參數(shù)為null值的處理保持一致性

• 3.3.3.    在相關(guān)方法中參數(shù)的名稱，類型和順序需要保持一致

• 3.3.4.    在參數(shù)列表中把輸出的參數(shù)放到輸入?yún)?shù)之后

• 3.3.5.    為重載的方法省略常用的默認(rèn)參數(shù)以提供一個較短的參數(shù)列表

• 3.3.6.    在無關(guān)的類型中為相同語義的操作提供重載方法

• 3.3.7.    建議使用接口而不是具體類作為參數(shù)

• 3.3.8.    建議使用集合而不是數(shù)組作為參數(shù)和返回值

• 3.3.9.    建議使用一般集合而不是原始（無類型）集合

• 3.3.10.  建議使用枚舉而不是Boolean或者Integer作為參數(shù)

• 3.3.11.  建議把單個的參數(shù)放到集合或者數(shù)組參數(shù)之前

• 3.3.12.  建議把自定義類型的參數(shù)放大Java標(biāo)準(zhǔn)類型參數(shù)之前

• 3.3.13.  建議把對象類型的參數(shù)方法值類型的參數(shù)之前

• 3.3.14.  建議使用接口而不是具體類作為返回值

• 3.3.15.  建議把空的集合而不是null作為返回值

• 3.3.16.  建議把返回值設(shè)計成可以作為其他方法的合法輸入?yún)?shù)

• 3.3.17.  考慮為不可變參數(shù)設(shè)計一個副本

• 3.3.18.  考慮在內(nèi)部存儲弱引用的對象

• 3.3.19.  避免參數(shù)數(shù)量變更

• 3.3.20.  避免參數(shù)長度太長（超過3個）

• 3.3.21.  避免連續(xù)的同類型的參數(shù)

• 3.3.22.  避免用作輸出或者輸入輸出的參數(shù)

• 3.3.23.  避免方法重載

• 3.3.24.  避免參數(shù)類型暴露實(shí)現(xiàn)細(xì)節(jié)

• 3.3.25.  避免boolean參數(shù)

• 3.3.26.  避免返回null

• 3.3.27.  除了Java核心Api，避免把類型作為不相關(guān)的Api的返回值

• 3.3.28.  避免把可變的內(nèi)部對象作為返回值來引用

• 3.3.29.  不要把預(yù)先設(shè)置的常量作為整型值參數(shù)使用

• 3.3.30.  不要為將來的（擴(kuò)展設(shè)計）考慮預(yù)留參數(shù)

• 3.3.31.  不要在重載方法中改變參數(shù)的名稱的順序

3.4. 異常處理

• 3.4.1.    只有在異常情況下才拋出異常

• 3.4.2.    只需要為可恢復(fù)的錯誤拋出已確認(rèn)的異常

• 3.4.3.    為了通知Api使用錯誤而拋出運(yùn)行時異常

• 3.4.4.    在適當(dāng)?shù)某橄髮哟螔伋霎惓?/p>

• 3.4.5.    進(jìn)行運(yùn)行時預(yù)置條件的檢查

• 3.4.6.    為一個被不能為null的參數(shù)拋出空指針異常

• 3.4.7.    為一個除為null以外異常值的參數(shù)排除非法參數(shù)異常

• 3.4.8.    為一個錯誤上下文環(huán)境中的方法調(diào)用拋出非法狀態(tài)異常

• 3.4.9.    在錯誤信息中顯示出參數(shù)的預(yù)置條件

• 3.4.10.  確保失敗的方法調(diào)用不會產(chǎn)生單向的后果

• 3.4.11.  為回調(diào)方法中的禁止使用的Api提供運(yùn)行時檢查

• 3.4.12.  建議優(yōu)先使用Java標(biāo)準(zhǔn)異常

• 3.4.13.  建議提供拋出異常的條件的查詢方法

3.5. 重寫

• 3.5.1.    使用@Override注解

• 3.5.2.    維持或弱化預(yù)置條件

• 3.5.3.    維持或者加強(qiáng)后置條件（不好翻譯，大概output+effect的意思）

• 3.5.4.    維持或者加強(qiáng)不可變性

• 3.5.5.    不要拋出新增的運(yùn)行時異常

• 3.5.6.    不要更改方法的類型（無狀態(tài)，訪問器或者擴(kuò)展方法等）

3.6. 構(gòu)造方法

• 3.6.1.    最小化構(gòu)造方法中的工作

• 3.6.2.    為所有的屬性設(shè)置合理的默認(rèn)值

• 3.6.3.    僅把構(gòu)造方法的參數(shù)作為一種設(shè)置參數(shù)的快捷方法

• 3.6.4.    校驗構(gòu)造方法的參數(shù)

• 3.6.5.    以參數(shù)相應(yīng)的屬性為其命名

• 3.6.6.    當(dāng)提供了多個構(gòu)造方法時，遵循指南對其進(jìn)行重載

• 3.6.7.    建議使用構(gòu)造方法而不是靜態(tài)的工廠方法

• 3.6.8.    考慮使用無參的構(gòu)造方法

• 3.6.9.    如果不是總需要新的實(shí)例，考慮使用靜態(tài)的工廠方法

• 3.6.10.  如果你需要在運(yùn)行時決定一個合適的類型，考慮使用靜態(tài)的工廠方法

• 3.6.11.  如果你需要訪問外部的資源，考慮使用靜態(tài)的工廠方法

• 3.6.12.  當(dāng)面臨非常多的參數(shù)的時候，考慮使用生成器（builder）

• 3.6.13.  當(dāng)需要回避直接實(shí)例化類的時候使用考慮private的構(gòu)造函數(shù)

• 3.6.14.  避免創(chuàng)建非必需的對象

• 3.6.15.  避免finalizer

• 3.6.16.  不要從無參的構(gòu)造方法中拋出異常

• 3.6.17.  不要向一個已經(jīng)發(fā)布的類中添加顯示的構(gòu)造方法

3.7. Setters和getters

• 3.7.1.    以get開頭命名一個返回值不為boolean的訪問屬性的方法

• 3.7.2.    以is，can開頭命名一個返回值為boolean的訪問屬性的方法

• 3.7.3.    以set開頭命名一個更新本地變量的方法

• 3.7.4.    校驗setter方法的參數(shù)

• 3.7.5.    最小化getter和setter方法的工作

• 3.7.6.    考慮從一個getter方法中返回不可變的集合

• 3.7.7.    考慮實(shí)現(xiàn)一個private接口的集合替代public的集合屬性

• 3.7.8.    考慮只讀的屬性

• 3.7.9.    設(shè)置可變類型的屬性時考慮Defensive Copy（Defensive Copy詳見：http://www.javapractices.com/topic/TopicAction.do?Id=15 ）

• 3.7.10.  當(dāng)返回可變類型的屬性時考慮Defensive Copy

• 3.7.11.  getter方法避免返回數(shù)組

• 3.7.12.  避免根據(jù)方法內(nèi)信息無法完成的校驗

• 3.7.13.  不要從getter方法中拋出異常

• 3.7.14.  不要設(shè)計只能set的屬性方法 (僅有public的setter而沒有public的getter)

• 3.7.15.  不要依賴屬性設(shè)置的順序

3.8. 回調(diào)

• 3.8.1.    設(shè)計時使用最嚴(yán)密的預(yù)置條件

• 3.8.2.    設(shè)計時使用最弱的后置條件

• 3.8.3.    考慮傳遞引用對象的方法中把回調(diào)接口作為第一個參數(shù)

• 3.8.4.    避免有返回值的回調(diào)方法

3.9. 文檔

• 3.9.1.    為每個方法提供Javadoc注釋

• 3.9.2.    遵循標(biāo)準(zhǔn)的Javadoc約定

• 3.9.3.    每個方法以一句短小的話作為概述

• 3.9.4.    申明相關(guān)的方法

• 3.9.5.    用@deprecated標(biāo)簽申明過時的類型

• 3.9.6.    顯示所有過時方法的替換方法

• 3.9.7.    避免冗長的zhus

• 3.9.8.    包含常用的使用模式

• 3.9.9.    （如果允許的話）包含null值的確切含義

• 3.9.10.  包含方法的類型 (無狀態(tài)，訪問器或者擴(kuò)展)

• 3.9.11.  包含方法的預(yù)置條件

• 3.9.12.  包含算法實(shí)現(xiàn)的性能特征

• 3.9.13.  包含遠(yuǎn)程方法調(diào)用

• 3.9.14.  包含訪問外部資源的方法

• 3.9.15.  包含哪些API可以在回調(diào)中使用

• 3.9.16.  考慮為了描述方法的行為而包含單元測試