Google首席软件工程师Joshua Bloch谈如何设计一款优秀的API【附PPT】
生活随笔
收集整理的這篇文章主要介紹了
Google首席软件工程师Joshua Bloch谈如何设计一款优秀的API【附PPT】
小編覺得挺不錯的,現在分享給大家,幫大家做個參考.
要：API設計看似簡單，其實里面的學問還不少，在整個設計流程中，一不小心就會陷入各種陷阱之中，給你帶來后患無窮的危害。Joshua Bloch是Google的首席Java架構師，他在一篇PPT里向大家講述了如何設計一款優秀的API。
if?(car.speed()?>?2?*?SPEED_LIMIT)?? ?generateAlert("Watch?out?for?cops!");??
模塊能做到的，客戶端就不要做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.?? ?private?static?final?void?writeDoc(Document?doc,?OutputStream?out)throws?IOException{?? ?try?{?? ?Transformer?t?=?TransformerFactory.newInstance().newTransformer();?? ?t.setOutputProperty(OutputKeys.DOCTYPE_SYSTEM,?doc.getDoctype().getSystemId());?? ?t.transform(new?DOMSource(doc),?new?StreamResult(out));?? ?}?catch(TransformerException?e)?{?? ?throw?new?AssertionError(e);?//?Can’t?happen!?? ?}?? ?}?? 遵守最小驚訝原則public?class?Thread?implements?Runnable?{?? ?//?Tests?whether?current?thread?has?been?interrupted.?? ?//?Clears?the?interrupted?status?of?current?thread.?? ?public?static?boolean?interrupted();?? ?}?? 故障快速報告應盡快生成//?A?Properties?instance?maps?strings?to?strings?? ?public?class?Properties?extends?Hashtable?{?? ?public?Object?put(Object?key,?Object?value);?? ?//?Throws?ClassCastException?if?this?properties?? ?//?contains?any?keys?or?values?that?are?not?strings?? ?public?void?save(OutputStream?out,?String?comments);?? ?}?? 以String形式對所有可用數據提供編程式訪問[java]?view plaincopypublic?class?Throwable?{?? ?public?void?printStackTrace(PrintStream?s);?? ?public?StackTraceElement[]?getStackTrace();?//?Since?1.4?? }?? public?final?class?StackTraceElement?{?? ?public?String?getFileName();?? ?public?int?getLineNumber();?? ?public?String?getClassName();?? ?public?String?getMethodName();?? ?public?boolean?isNativeMethod();?? }?? 方法重載要細心public?TreeSet(Collection?c);?//?Ignores?order?? public?TreeSet(SortedSet?s);?//?Respects?order?? #include?<string.h>?? ?char?*strcpy?(char?*dest,?char?*src);?? ?void?bcopy?(void?*src,?void?*dst,?int?n);?? java.util.Collections – first parameter always collection to be modified or queried?
?java.util.concurrent – time always specified as long delay, TimeUnit unit避免使用長參數列表//?Eleven?parameters?including?four?consecutive?ints?? HWND?CreateWindow(LPCTSTR?lpClassName,?LPCTSTR?lpWindowName,?? ?DWORD?dwStyle,?int?x,?int?y,?int?nWidth,?int?nHeight,?? ?HWND?hWndParent,?HMENU?hMenu,?HINSTANCE?hInstance,?LPVOID?lpParam);?? package?java.awt.image;?? ?public?interface?BufferedImageOp?{?? ?//?Returns?the?rendering?hints?for?this?operation,?? ?//?or?null?if?no?hints?have?been?set.?? ?public?RenderingHints?getRenderingHints();?? ?}?? API中的異常設計
private?byte[]?a?=?new?byte[BUF_SIZE];?? ?void?processBuffer?(ByteBuffer?buf)?{?? ?try?{?? ?while?(true)?{?? ?buf.get(a);?? ?processBytes(tmp,?BUF_SIZE);?? ?}?? ?}?catch?(BufferUnderflowException?e)?{?? ?int?remaining?=?buf.remaining();?? ?buf.get(a,?0,?remaining);?? ?processBytes(bufArray,?remaining);?? ?}?? ?}?? Conversely, don’t fail silently?
[java]?view plaincopyThreadGroup.enumerate(Thread[]?list)?? try?{?? ?Foo?f?=?(Foo)?super.clone();?? ?....?? }?catch?(CloneNotSupportedException?e)?{?? ?//?This?can't?happen,?since?we’re?Cloneable?? ?throw?new?AssertionError();?? }?? 異常中應該包含捕獲錯誤的（Failure-Capture）信息
public?class?Vector?{?? ?public?int?indexOf(Object?elem,?int?index);?? ?public?int?lastIndexOf(Object?elem,?int?index);?? ?...?? }?? 分析：public?interface?List?{?? ?List?subList(int?fromIndex,?int?toIndex);?? ?...?? }?? 分析：
[java]?view plaincopy//?Broken?-?inappropriate?use?of?String?as?capability.?? //?Keys?constitute?a?shared?global?namespace.?? public?class?ThreadLocal?{?? private?ThreadLocal()?{?}?//?Non-instantiable?? //?Sets?current?thread’s?value?for?named?variable.?? public?static?void?set(String?key,?Object?value);?? //?Returns?current?thread’s?value?for?named?variable.?? public?static?Object?get(String?key);?? }?? 線程局部變量重構1[java]?view plaincopypublic?class?ThreadLocal?{?? private?ThreadLocal()?{?}?//?Noninstantiable?? public?static?class?Key?{?Key()?{?}?}?? //?Generates?a?unique,?unforgeable?key?? public?static?Key?getKey()?{?return?new?Key();?}?? public?static?void?set(Key?key,?Object?value);?? public?static?Object?get(Key?key);?? }?? 可以運行，但是需要使用模板代碼。?
[java]?view plaincopystatic?ThreadLocal.Key?serialNumberKey?=?ThreadLocal.getKey();?? ?ThreadLocal.set(serialNumberKey,?nextSerialNumber());?? ?System.out.println(ThreadLocal.get(serialNumberKey));?? 線程局部變量重構2[java]?view plaincopypublic?class?ThreadLocal?{?? ?public?ThreadLocal()?{?}?? ?public?void?set(Object?value);?? ?public?Object?get();?? ?}?? 從API和客戶端代碼中刪除了無用代碼。?
[java]?view plaincopystatic?ThreadLocal?serialNumber?=?new?ThreadLocal();?? ?serialNumber.set(nextSerialNumber());?? ?System.out.println(serialNumber.get());?? 總結
【編者按】隨著近來軟件規模的日益龐大，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）、講究對稱、代碼應該易讀。如下所示：
重視文檔
開發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中的方法設計
模塊能做到的，客戶端就不要做
減少模板代碼的使用：?
用戶API只需根據需求來設計即可，不必讓客戶感到驚訝，小心弄巧成拙：?
- 編譯時最好是靜態類型、泛型；
- 方法里應該包含錯誤自動提交機制。
- 避免模棱兩可的重載，例如多個重載適用于同一個實物
- 即使你能分清，也最好不要這樣做，最好起個不同的名字
- 如果非要定義這種重載，相同的參數確保相同的行為
使用合適的參數和返回類型
- 通過類來支持接口類型輸入
- 盡可能地使用最特定的輸入參數類型
- 如果已經有一個更好的類型存在，就不要使用string類型
- 不要用浮點型來修飾貨幣值
- 使用Double(64位)而不要使用Float(32位)
- 在方法上參數順序要一致，尤其是參數類型相同時，則尤為重要
?java.util.concurrent – time always specified as long delay, TimeUnit unit避免使用長參數列表
- 三個或三個以內的參數是最完美的
- 長參數列表是有害的，程序員容易出錯，并且程序在編譯、運行時會表現不好
- 縮短參數的兩種方法：Break up method、創建參數助手類
最好避免這種情況出現：
[java]?view plaincopy返回值勿需進行異常處理
比如，返回零長度字符串或者空集合
[java]?view plaincopy拋出異常來說明異常狀況；不要強迫客戶端使用異常來控制流。
[java]?view plaincopy[java]?view plaincopy
支持Unchecked Exceptions
- Checked——客戶端肯定會做一些恢復措施
- Unchecked——編程錯誤
- 過度使用Checked異常會產生一些模板代碼
- 允許診斷和修復或恢復
- 對于Unchecked異常，有異常消息就行了
- 對于Checked異常，提供訪問器
在Vector中進行Sublist操作?
- 在搜索上不強大
- 沒有文檔很難使用
重構Sublist操作?
- 非常強大——支持所有操作
- 使用接口來減少概念權重：較高的動力重量（power-to-weight）比
- 沒有文檔也易于使用
[java]?view plaincopy
[java]?view plaincopy
[java]?view plaincopy
API設計是一件非常高端大氣上檔次的工藝，對程序員、終端用戶和公司都會有所提升。不要盲目地去遵守文中所提及的規則、說明等，但也不要去侵犯他們，API設計不是件簡單的工藝，也不是一種可以孤立行動的活。當然完美永遠無法實現，但我們要努力去追求完美。
http://www.csdn.net/article/2014-02-18/2818441-How-to-design-a-good-API
總結
以上是生活随笔為你收集整理的Google首席软件工程师Joshua Bloch谈如何设计一款优秀的API【附PPT】的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 佛山天一众合科技发展有限公司(离家很近)
- 下一篇： Wince6 RIL层移植