前谷歌首席 Java 架構師談如何設優秀的 API
【編者按】隨著近來軟體規模的日益龐大,API程式設計介面的設計變的越來越重要。良好的介面設計可以降低系統各部分之間的相互依賴,提高組成單元的內聚性,降低組成單元間的耦合度,從而提高系統的維護性和穩定性。
Joshua Bloch是美國著名程式式設計師。他為Java平臺設計並實現了許多的功能,是Google的首席Java架構師(Chief Java Architect)。他也是《Effective Java Programming Language Guide》一書的作者,就是人們常說的 Effective Java。本文翻譯自Joshua Bloch所發表的一個PPT:How to Design a Good API and Why it Matters
隨著大資料、公共平臺等網際網路技術的日益成熟,API介面的重要性日益凸顯,從公司的角度來看,API可以算作是公司一筆巨大的資產,公共API可以捕獲使用者、為公司做出許多貢獻。對於個人來說,只要你程式設計,你就是一個API設計者,因為好的程式碼即是模組——每個模組便是一個API,而好的模組會被多次使用。此外,編寫API還有利於開發者提高程式碼質量,提高自身的編碼水平。
優秀API所具備的特徵:
- 簡單易學;
- 易於使用,即使沒有文件;
- 很難誤用;
- 易於閱讀,程式碼易於維護;
- 足夠強大,可以滿足需求;
- 易於擴充套件;
- 適合使用者。
瞭解了一款優秀API所具備的特徵後,一起再來看看如何設計優秀的API,有哪些流程和規則可循,開發者在設計時需要注意哪些事項。
API設計流程中的注意事項
徵集需求
在開始之前,你可能會收到一些解決方案,它們不一定會比現有的方案好,而你的任務是以用例的形式提取真實需求,並制定真正合適的解決方案,這樣構建出來的東西就會更加有價值。
從簡短的說明開始
這時,編寫簡短的說明最為合適,編寫時需要考慮的因素有:
- 靈活性要遠勝於完整性;
- 跳出規則:聽取意見並嚴陣以待;
- 精煉短小才易修改;
- 獲得信任之後將其具體化,在此之中,程式設計很重要。
儘早編寫API
- 對每一個實現進行儲存,以防丟失;
- 在開始之前,列出一些合理的規定,儲存所寫說明,以防丟失;
- 繼續編寫和充實API。
編寫SPI尤為重要
- Service Provider Interface即服務提供商介面,外掛服務支援多種實現,例如Java Cryptography Extension
(JCE); - 釋出之前編寫多個外掛;
- “三次原則”(“The Rule of Threes”):指的是當某個功能第三次出現時,才進行”抽象化”。
維護切實可行的期望
- 大多數API設計都過於約束;
- 對可能會犯的錯誤進行預計,要用發展的思維來編寫API。
API設計原則
每個API介面應該只專注一件事,並做好:如果它很難命名,那麼這或許是個不好的徵兆,好的名稱可以驅動開發、並且只需拆分與合併模組即可
- API應儘可能地輕小:滿足需求、對有疑問的地方可以暫時不使用(函式、類、方法、引數等,你可以不新增,但千萬不要刪除)、概念性的東西比體積重要、尋找一個良好的動力體積比;
- 實現不要影響API:關注實現細節(不要迷惑使用者、不要隨便改變實現方式)、意識到具體的實現細節(不要有越權的方法行為,例如不要制訂雜湊函式、所有的調優引數都是可疑的);
- 不要讓實現細節“洩露”到API(例如on-disk和on-the-wire格式等異常情況);
- 最小化可訪問:設計人員應儘量把類及成員設為私有,公共類不應該有公共欄位(包括異常例項),最大限度地提高資訊隱藏,允許模組可以被使用、理解、構建、測試和獨立除錯;
- 命名問題:應該見名知意,避免含糊的縮寫、對同一樣東西的命名應該有個一致性的字首(遍及整個平臺API)、講究對稱、程式碼應該易讀。如下所示:
12 | if(car.speed()>2*SPEED_LIMIT)generateAlert("Watch out for cops!"); |
重視文件
開發API時要意識到文件的重要性。元件重用不是紙上談兵的東西,既需要好的設計,也需要優秀的文件,這二者缺一不可,即使我們看到了良好的設計而未見文件,那麼元件重用也是不妥的。
——摘自 D. L. Parnas 在1994年第16屆國際軟體開發大會上的演講內容
文件應包含每個類、介面、方法、建構函式、引數和異常,此外,還要小心對待文件的狀態空間。
API設計決策對效能的影響
- API設計決策對效能的影響是真實永久的;
- 不好的決策會限制性能(型別易變、建構函式替代靜態工廠、實現型別替代介面);
- 不得打包API來提升效能(潛在的效能問題可能會得到修復,但救的了一時,救不了一世);
- 良好的設計通常與好的效能是一致的。
API與平臺和平共處
- 養成良好的習慣:遵守標準的命名約定、避免陳舊的引數和返回型別、核心API和語言的模仿模式;
- 利用API的友好功能:泛型、可變引數、列舉、預設引數;
- 瞭解和避免API陷阱和缺陷:Finalizers、公共靜態Final陣列。
API中類的設計
最小化可變性
- 最好不要隨便改變類,除非有一個非常合理的理由;
- 如果是可變類,最好保持很小的狀態空間、定義良好的結構,因時制宜地去呼叫方法。
子類只存在有意義的地方
- 子類具備可替代性(Liskov);
- 公共類不應該繼承其它公共類。
用於繼承的設計和文件或者直接禁止繼承(Design and Document for Inheritance or Else Prohibit it)
- 繼承破壞封裝
- 如果你允許子類和文件自用,那麼要考慮彼此該如何互相呼叫方法
- 保守策略:把所有類都設定成Final
API中的方法設計
模組能做到的,客戶端就不要做減少模板程式碼的使用:
123456789101112131415 | import org.w3c.dom.*;import java.io.*;import javax.xml.transform.*;import javax.xml.transform.dom.*;import javax.xml.transform.stream.*;// DOM code to write an XML document to a specified output stream.privatestaticfinalvoidwriteDoc(Document doc,OutputStream out)throwsIOException{try{Transformert=TransformerFactory.newInstance().newTransformer();t.setOutputProperty(OutputKeys.DOCTYPE_SYSTEM,doc.getDoctype().getSystemId());t.transform(newDOMSource(doc),newStreamResult(out));}catch(TransformerExceptione){thrownewAssertionError(e);// Can’t happen!}} |
遵守最小驚訝原則
使用者API只需根據需求來設計即可,不必讓客戶感到驚訝,小心弄巧成拙:
12345 | publicclassThreadimplementsRunnable{// Tests whether current thread has been interrupted.// Clears the interrupted status of current thread.publicstaticbooleaninterrupted();} |
故障快速報告應儘快生成
- 編譯時最好是靜態型別、泛型;
- 方法裡應該包含錯誤自動提交機制。
1234567 | // A Properties instance maps strings to stringspublicclassPropertiesextendsHashtable{publicObjectput(Objectkey,Objectvalue);// Throws ClassCastException if this properties// contains any keys or values that are not stringspublicvoidsave(OutputStream out,Stringcomments);} |
以String形式對所有可用資料提供程式設計式訪問
1234567891011 | publicclassThrowable{publicvoidprintStackTrace(PrintStreams);publicStackTraceElement[]getStackTrace();// Since 1.4}publicfinalclassStackTraceElement{publicStringgetFileName();publicintgetLineNumber();publicStringgetClassName();publicStringgetMethodName();publicbooleanisNativeMethod();} |
方法過載要細心
- 避免模稜兩可的過載,例如多個過載適用於同一個實物
- 即使你能分清,也最好不要這樣做,最好起個不同的名字
- 如果非要定義這種過載,相同的引數確保相同的行為
12 | publicTreeSet(Collectionc);// Ignores orderpublicTreeSet(SortedSets);// Respects order |
使用合適的引數和返回型別
- 通過類來支援介面型別輸入
- 儘可能地使用最特定的輸入引數型別
- 如果已經有一個更好的型別存在,就不要使用string型別
- 不要用浮點型來修飾貨幣值
- 使用Double(64位)而不要使用Float(32位)
- 在方法上引數順序要一致,尤其是引數型別相同時,則尤為重要
123 | #include char*strcpy(char*dest,char*src);voidbcopy(void*src,void*dst,intn); |
java.util.Collections – first parameter always collection to be modified
or queriedjava.util.concurrent – time always specified as long delay, TimeUnit
unit
避免使用長引數列表
- 三個或三個以內的引數是最完美的
- 長引數列表是有害的,程式設計師容易出錯,並且程式在編譯、執行時會表現不好
- 縮短引數的兩種方法:Break up method、建立引數助手類
最好避免這種情況出現:
1234 | // Eleven parameters including four consecutive intsHWND CreateWindow(LPCTSTR lpClassName,LPCTSTR lpWindowName,DWORD dwStyle,intx,inty,intnWidth,intnHeight,HWND hWndParent,HMENU hMenu,HINSTANCE hInstance,LPVOID lpParam); |
返回值勿需進行異常處理
比如,返回零長度字串或者空集合
123456 | packagejava.awt.image;publicinterfaceBufferedImageOp{// Returns the rendering hints for this operation,// or null if no hints have been set.publicRenderingHints getRenderingHints();} |
API中的異常設計
丟擲異常來說明異常狀況;不要強迫客戶端使用異常來控制流。
12345678910111213 | privatebyte[]a=newbyte[BUF_SIZE];voidprocessBuffer(ByteBuffer buf){try{while(true){buf.get(a);processBytes(tmp,BUF_SIZE);}}catch(BufferUnderflowExceptione){intremaining=buf.remaining();buf.get(a,0,remaining);processBytes(bufArray,remaining);}} |
Conversely, don’t fail silently
1 | ThreadGroup.enumerate(Thread[]list) |
支援Unchecked Exceptions
- Checked——客戶端肯定會做一些恢復措施
- Unchecked——程式設計錯誤
- 過度使用Checked異常會產生一些模板程式碼
1234567 | try{Foof=(Foo)super.clone();....}catch(CloneNotSupportedExceptione){// This can't happen, since we’re CloneablethrownewAssertionError();} |
異常中應該包含捕獲錯誤的(Failure-Capture)資訊
- 允許診斷和修復或恢復
- 對於Unchecked異常,有異常訊息就行了
- 對於Checked異常,提供訪問器
重構API設計
在Vector中進行Sublist操作
12345 | publicclassVector{publicintindexOf(Objectelem,intindex);publicintlastIndexOf(Objectelem,intindex);...} |
分析:
- 在搜尋上不強大
- 沒有文件很難使用
重構Sublist操作
1234 | publicinterfaceList{List subList(intfromIndex,inttoIndex);...} |
分析:
- 非常強大——支援所有操作
- 使用介面來減少概念權重:較高的動力重量(power-to-weight)比
- 沒有文件也易於使用
執行緒區域性變數
123456789 | // Broken - inappropriate use of String as capability.// Keys constitute a shared global namespace.publicclassThreadLocal{privateThreadLocal(){}// Non-instantiable// Sets current thread’s value for named variable.publicstaticvoidset(Stringkey,Objectvalue);// Returns current thread’s value for named variable.publicstaticObjectget(Stringkey);} |
執行緒區域性變數重構1