前谷歌首席Java架構師談如何設優秀的API

jopen 9年前發布 | 24K 次閱讀 Java

隨著近來軟件規模的日益龐大，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）、講究對稱、代碼應該易讀。如下所示：

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 中的方法設計

模塊能做到的，客戶端就不要做

減少模板代碼的使用：

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!
 }
 }

遵守最小驚訝原則

用戶 API 只需根據需求來設計即可，不必讓客戶感到驚訝，小心弄巧成拙：

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 形式對所有可用數據提供編程式訪問

public 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

使用合適的參數和返回類型

通過類來支持接口類型輸入

盡可能地使用最特定的輸入參數類型

如果已經有一個更好的類型存在，就不要使用 string 類型

不要用浮點型來修飾貨幣值

使用 Double (64 位)而不要使用 Float (32 位)

在方法上參數順序要一致，尤其是參數類型相同時，則尤為重要

#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
</blockquote>

避免使用長參數列表
三個或三個以內的參數是最完美的

長參數列表是有害的，程序員容易出錯，并且程序在編譯、運行時會表現不好

縮短參數的兩種方法：Break up method、創建參數助手類
</ul>

最好避免這種情況出現：
// 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
ThreadGroup.enumerate (Thread[] list)
支持 Unchecked Exceptions
Checked——客戶端肯定會做一些恢復措施

Unchecked——編程錯誤

過度使用 Checked 異常會產生一些模板代碼
</ul>
try {
 Foo f = (Foo) super.clone ();
 ....
} catch (CloneNotSupportedException e) {
 // This can't happen, since we’re Cloneable
 throw new AssertionError ();
}
異常中應該包含捕獲錯誤的（Failure-Capture）信息
允許診斷和修復或恢復

對于 Unchecked 異常，有異常消息就行了

對于 Checked 異常，提供訪問器
</ul>

重構 API 設計

在 Vector 中進行 Sublist 操作
 public class Vector {
 public int indexOf (Object elem, int index);
 public int lastIndexOf (Object elem, int index);
 ...
} 
分析：

在搜索上不強大

沒有文檔很難使用
</ul>

重構 Sublist 操作

public interface List { List subList (int fromIndex, int toIndex); ... }

分析：

非常強大——支持所有操作

使用接口來減少概念權重：較高的動力重量（power-to-weight）比

沒有文檔也易于使用
</ul>

線程局部變量

// 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
public 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); }
可以運行，但是需要使用模板代碼。
static ThreadLocal.Key serialNumberKey = ThreadLocal.getKey (); ThreadLocal.set (serialNumberKey, nextSerialNumber ()); System.out.println (ThreadLocal.get (serialNumberKey));

線程局部變量重構2

public class ThreadLocal { public ThreadLocal () { } public void set (Object value); public Object get (); }

從 API 和客戶端代碼中刪除了無用代碼。
static ThreadLocal serialNumber = new ThreadLocal (); serialNumber.set (nextSerialNumber ()); System.out.println (serialNumber.get ());

總結

API 設計是一件非常高端大氣上檔次的工藝，對程序員、終端用戶和公司都會有所提升。不要盲目地去遵守文中所提及的規則、說明等，但也不要去侵犯他們，API 設計不是件簡單的工藝，也不是一種可以孤立行動的活。當然完美永遠無法實現，但我們要努力去追求完美。

來自: CSDN

</strong>

本文由用戶 jopen 自行上傳分享，僅供網友學習交流。所有權歸原作者，若您的權利被侵害，請聯系管理員。

轉載本站原創文章，請注明出處，并保留原始鏈接、圖片水印。

本站是一個以用戶分享為主的開源技術平臺，歡迎各類分享！

本文地址：http://www.baiduhome.net/news/view/e58c2b

Java

前谷歌首席Java架構師談如何設優秀的API

相關資訊

相關經驗

相關文檔