JavaScript API 設計原則

網+線下沙龍 | 移動APP模式創新：給你一個做APP的理由>>

好的 API 設計：在自描述的同時，達到抽象的目標。

設計良好的 API ，開發者可以快速上手，沒必要經常抱著手冊和文檔，也沒必要頻繁光顧技術支持社區。

流暢的介面

方法鏈：流暢易讀，更易理解

1. //常見的 API 調用方式：改變一些顏色，添加事件監聽 
2. var elem = document.getElementById("foobar"); 
3. elem.style.background = "red"; 
4. elem.style.color = "green"; 
5. elem.addEventListener('click', function(event) { 
6.   alert("hello world!"); 
7. }, true); 
8.  
9. //（設想的）方法鏈 API 
10. DOMHelper.getElementById('foobar') 
11.   .setStyle("background", "red") 
12.   .setStyle("color", "green") 
13.   .addEvent("click", function(event) { 
14.     alert("hello world"); 
15.   }); 

設置和獲取操作，可以合二為一；方法越多，文檔可能越難寫

1. var $elem = jQuery("#foobar"); 
2.  
3. //setter 
4. $elem.setCss("background", "green"); 
5. //getter 
6. $elem.getCss("color") === "red"; 
7.  
8. //getter, setter 合二為一 
9. $elem.css("background", "green"); 
10. $elem.css("color") === "red"; 

一致性

相關的介面保持一致的風格，一整套 API 如果傳遞一種熟悉和舒適的感覺，會大大減輕開發者對新工具的適應性。

命名這點事：既要短，又要自描述，最重要的是保持一致性

“There are only two hard problems in computer science: cache-invalidation and naming things.”
“在電腦科學界只有兩件頭疼的事：緩存失效和命名問題”
— Phil Karlton

選擇一個你喜歡的措辭，然後持續使用。選擇一種風格，然後保持這種風格。

處理參數

需要考慮大家如何使用你提供的方法，是否會重覆調用？為何會重覆調用？你的 API 如何幫助開發者減少重覆的調用？
接收map映射參數，回調或者序列化的屬性名，不僅讓你的 API 更乾凈，而且使用起來更舒服、高效。

jQuery 的 css() 方法可以給 DOM 元素設置樣式：

1. jQuery("#some-selector") 
2.   .css("background", "red") 
3.   .css("color", "white") 
4.   .css("font-weight", "bold") 
5.   .css("padding", 10); 

這個方法可以接受一個 JSON 對象：

1. jQuery("#some-selector").css({ 
2.   "background" : "red", 
3.   "color" : "white", 
4.   "font-weight" : "bold", 
5.   "padding" : 10 
6. }); 
7.  
8. //通過傳一個 map 映射綁定事件 
9. jQuery("#some-selector").on({ 
10.   "click" : myClickHandler, 
11.   "keyup" : myKeyupHandler, 
12.   "change" : myChangeHandler 
13. }); 
14.  
15. //為多個事件綁定同一個處理函數 
16. jQuery("#some-selector").on("click keyup change", myEventHandler); 

處理類型

定義方法的時候，需要決定它可以接收什麼樣的參數。我們不清楚人們如何使用我們的代碼，但可以更有遠見，考慮支持哪些參數類型。

1. //原來的代碼 
2. DateInterval.prototype.days = function(start, end) { 
3.   return Math.floor((end - start) / 86400000); 
4. }; 
5.  
6. //修改後的代碼 
7. DateInterval.prototype.days = function(start, end) { 
8.   if (!(start instanceof Date)) { 
9.     start = new Date(start); 
10.   } 
11.   if (!(end instanceof Date)) { 
12.     end = new Date(end); 
13.   } 
14.  
15.   return Math.floor((end.getTime() - start.getTime()) / 86400000); 
16. }; 

加了短短的6行代碼，我們的方法強大到可以接收 Date 對象，數字的時間戳，甚至像 Sat Sep 08 2012 15:34:35 GMT+0200 (CEST) 這樣的字元串

如果你需要確保傳入的參數類型（字元串，數字，布爾），可以這樣轉換：

1. function castaway(some_string, some_integer, some_boolean) { 
2.   some_string += ""; 
3.   some_integer += 0; // parseInt(some_integer, 10) 更安全些 
4.   some_boolean = !!some_boolean; 
5. } 

處理 undefined

為了使你的 API 更健壯，需要鑒別是否真正的 undefined 值被傳遞進來，可以檢查 arguments 對象：

1. function testUndefined(expecting, someArgument) { 
2.   if (someArgument === undefined) { 
3.     console.log("someArgument 是 undefined"); 
4.   } 
5.   if (arguments.length > 1) { 
6.     console.log("然而它實際是傳進來的"); 
7.   } 
8. } 
9.  
10. testUndefined("foo"); 
11. // 結果: someArgument 是 undefined 
12. testUndefined("foo", undefined); 
13. // 結果:  someArgument 是 undefined , 然而它實際是傳進來的 

給參數命名

1. event.initMouseEvent( 
2.   "click", true, true, window, 
3.   123, 101, 202, 101, 202, 
4.   true, false, false, false, 
5.   1, null); 

Event.initMouseEvent 這個方法簡直喪心病狂，不看文檔的話，誰能說出每個參數是什麼意思？

給每個參數起個名字，賦個預設值，可好

1. event.initMouseEvent( 
2.   type="click", 
3.   canBubble=true, 
4.   cancelable=true, 
5.   view=window, 
6.   detail=123, 
7.   screenX=101, 
8.   screenY=202, 
9.   clientX=101, 
10.   clientY=202, 
11.   ctrlKey=true, 
12.   altKey=false, 
13.   shiftKey=false, 
14.   metaKey=false, 
15.   button=1, 
16.   relatedTarget=null); 

ES6, 或者 Harmony 就有 預設參數值 和 rest 參數 了。

參數接收 JSON 對象

與其接收一堆參數，不如接收一個 JSON 對象：

1. function nightmare(accepts, async, beforeSend, cache, complete, /* 等28個參數 */) { 
2.   if (accepts === "text") { 
3.     // 準備接收純文本 
4.   } 
5. } 
6.  
7. function dream(options) { 
8.   options = options || {}; 
9.   if (options.accepts === "text") { 
10.     // 準備接收純文本 
11.   } 
12. } 

調用起來也更簡單了：

1. nightmare("text", true, undefined, false, undefined, /* 等28個參數 */); 
2.  
3. dream({ 
4.   accepts: "text", 
5.   async: true, 
6.   cache: false 
7. }); 

參數預設值

參數最好有預設值，通過 jQuery.extend() http://underscorejs.org/#extend) 和 Protoype 的 Object.extend ，可以覆蓋預設的預設值。

1. var default_options = { 
2.   accepts: "text", 
3.   async: true, 
4.   beforeSend: null, 
5.   cache: false, 
6.   complete: null, 
7.   // … 
8. }; 
9.  
10. function dream(options) { 
11.   var o = jQuery.extend({}, default_options, options || {}); 
12.   console.log(o.accepts); 
13. } 
14.  
15. dream({ async: false }); 
16. // prints: "text" 

擴展性

回調（callbacks）

通過回調， API 用戶可以覆蓋你的某一部分代碼。把一些需要自定義的功能開放成可配置的回調函數，允許 API 用戶輕鬆覆蓋你的預設代碼。

API 介面一旦接收回調，確保在文檔中加以說明，並提供代碼示例。

事件（events）

事件介面最好見名知意，可以自由選擇事件名字，避免與原生事件 重名。

處理錯誤

不是所有的錯誤都對開發者調試代碼有用：

1. // jQuery 允許這麼寫 
2. $(document.body).on('click', {}); 
3.  
4. // 點擊時報錯 
5. //   TypeError: ((p.event.special[l.origType] || {}).handle || l.handler).apply is not a function 
6. //   in jQuery.min.js on Line 3 

這樣的錯誤調試起來很痛苦，不要浪費開發者的時間，直接告訴他們犯了什麼錯：

1. if (Object.prototype.toString.call(callback) !== '[object Function]') { // 看備註 
2.   throw new TypeError("callback is not a function!"); 
3. } 
4.     備註：typeof callback === "function" 在老的瀏覽器上會有問題，object 會當成個 function 。 

可預測性

好的 API 具有可預測性，開發者可以根據例子推斷它的用法。

Modernizr’s 特性檢測 是個例子：

a) 它使用的屬性名完全與 HTML5、CSS 概念和 API 相匹配

b) 每一個單獨的檢測一致地返回 true 或 false 值

1. // 所有這些屬性都返回 'true' 或 'false' 
2. Modernizr.geolocation 
3. Modernizr.localstorage 
4. Modernizr.webworkers 
5. Modernizr.canvas 
6. Modernizr.borderradius 
7. Modernizr.boxshadow 
8. Modernizr.flexbox 

依賴於開發者已熟悉的概念也可以達到可預測的目的。

jQuery’s 選擇器語法 就是一個顯著的例子，CSS1-CSS3 的選擇器可直接用於它的 DOM 選擇器引擎。

1. $("#grid") // Selects by ID 
2. $("ul.nav > li") // All LIs for the UL with class "nav" 
3. $("ul li:nth-child(2)") // Second item in each list 

比例協調

好的 API 並不一定是小的 API，API 的體積大小要跟它的功能相稱。

比如 Moment.js ，著名的日期解析和格式化的庫，可以稱之為均衡，它的 API 既簡潔又功能明確。

像 Moment.js 這樣特定功能的庫，確保 API 的專註和小巧非常重要。

編寫 API 文檔

軟體開發最艱難的任務之一是寫文檔，實際上每個人都恨寫文檔，怨聲載道的是沒有一個好用的文檔工具。

以下是一些文檔自動生成工具：

• YUIDoc (requires Node.js, npm)

• JsDoc Toolkit (requires Node.js, npm)

• Markdox (requires Node.js, npm)

• Dox (requires Node.js, npm)

• Docco (requires Node.js, Python, CoffeeScript)

• JSDuck (reqires Ruby, gem)

• JSDoc 3 (requires Java)