隨著大資料、公共平臺等網際網路技術的日益成熟，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。

大家可以點選加入群：【Java高階架構進階群】：854180697 裡面有Java高階大牛直播講解知識點 走的就是高階路線 ，（如果你想跳槽換工作 但是技術又不夠 或者工作上遇到了瓶頸 ，我這裡有一個JAVA的免費直播課程 ，講的是高階的知識點基礎不好的誤入喲 ，只要你有1-5年的開發經驗可以加群找我要課堂連結 ，注意：是免費的 沒有開發經驗誤入哦）

API設計原則

每個API介面應該只專注一件事，並做好：如果它很難命名，那麼這或許是個不好的徵兆，好的名稱可以驅動開發、並且只需拆分與合併模組即可

1. API應儘可能地輕小：滿足需求、對有疑問的地方可以暫時不使用（函式、類、方法、引數等，你可以不新增，但千萬不要刪除）、概念性的東西比體積重要、尋找一個良好的動力體積比；
2. 實現不要影響API：關注實現細節（不要迷惑使用者、不要隨便改變實現方式）、意識到具體的實現細節（不要有越權的方法行為，例如不要制訂雜湊函式、所有的調優引數都是可疑的）；
3. 不要讓實現細節“洩露”到API（例如on-disk和on-the-wire格式等異常情況）；
4. 最小化可訪問：設計人員應儘量把類及成員設為私有，公共類不應該有公共欄位（包括異常例項），最大限度地提高資訊隱藏，允許模組可以被使用、理解、構建、測試和獨立除錯；
5. 命名問題：應該見名知意，避免含糊的縮寫、對同一樣東西的命名應該有個一致性的字首（遍及整個平臺API）、講究對稱、程式碼應該易讀。如下所示：

if (car.speed() > 2 * SPEED_LIMIT)
 generateAlert("Watch out for cops!");

重視文件

開發API時要意識到文件的重要性。元件重用不是紙上談兵的東西，既需要好的設計，也需要優秀的文件，這二者缺一不可，即使我們看到了良好的設計而未見文件，那麼元件重用也是不妥的。

文件應包含每個類、介面、方法、建構函式、引數和異常，此外，還要小心對待文件的狀態空間。

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 
 char *strcpy (char *dest, char *src);
 void bcopy (void *src, void *dst, int n);

ava.util.Collections – first parameter always collection to be modified
or queried
java.util.concurrent – time always specified as long delay, TimeUnit
unit

避免使用長引數列表

• 三個或三個以內的引數是最完美的
• 長引數列表是有害的，程式設計師容易出錯，並且程式在編譯、執行時會表現不好
• 縮短引數的兩種方法：Break up method、建立引數助手類

最好避免這種情況出現：

// 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異常會產生一些模板程式碼

try {
 Foo f = (Foo) super.clone();
 ....
} catch (CloneNotSupportedException e) {
 // This can't happen, since we’re Cloneable
 throw new AssertionError();
}

異常中應該包含捕獲錯誤的（Failure-Capture）資訊

• 允許診斷和修復或恢復
• 對於Unchecked異常，有異常訊息就行了
• 對於Checked異常，提供訪問器

重構API設計

在Vector中進行Sublist操作

public class Vector {
 public int indexOf(Object elem, int index);
 public int lastIndexOf(Object elem, int index);
 ...
}

分析：

在搜尋上不強大
沒有文件很難使用
重構Sublist操作

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

分析：

• 非常強大——支援所有操作
• 使用介面來減少概念權重：較高的動力重量（power-to-weight）比

沒有文件也易於使用
執行緒區域性變數

 // 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設計不是件簡單的工藝，也不是一種可以孤立行動的活。當然完美永遠無法實現，但我們要努力去追求完美。

寫在最後：歡迎留言討論，私信“Java”或“架構資料”有驚喜！加關注，持續更新！！！