JavaScript API 設計原則

2016-03-29 09:59:11

前段時間組織優化我們的原生模塊 API（iOS、Android 模塊封裝成 JavaScript 接口），于是學習了幾篇 JavaScript API 設計的文章，盡管是舊文，但受益匪淺，這里記錄一下。

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

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

流暢的接口

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

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

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

var $elem = jQuery("#foobar"); 
 
//setter 
$elem.setCss("background", "green"); 
//getter 
$elem.getCss("color") === "red"; 
 
//getter, setter 合二為一 
$elem.css("background", "green"); 
$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 元素設置樣式：

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

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

jQuery("#some-selector").css({ 
  "background" : "red", 
  "color" : "white", 
  "font-weight" : "bold", 
  "padding" : 10 
}); 
 
//通過傳一個 map 映射綁定事件 
jQuery("#some-selector").on({ 
  "click" : myClickHandler, 
  "keyup" : myKeyupHandler, 
  "change" : myChangeHandler 
}); 
 
//為多個事件綁定同一個處理函數 
jQuery("#some-selector").on("click keyup change", myEventHandler);

處理類型

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

//原來的代碼 
DateInterval.prototype.days = function(start, end) { 
  return Math.floor((end - start) / 86400000); 
}; 
 
//修改后的代碼 
DateInterval.prototype.days = function(start, end) { 
  if (!(start instanceof Date)) { 
    start = new Date(start); 
  } 
  if (!(end instanceof Date)) { 
    end = new Date(end); 
  } 
 
  return Math.floor((end.getTime() - start.getTime()) / 86400000); 
};

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

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

function castaway(some_string, some_integer, some_boolean) { 
  some_string += ""; 
  some_integer += 0; // parseInt(some_integer, 10) 更安全些 
  some_boolean = !!some_boolean; 
}

處理 undefined

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

function testUndefined(expecting, someArgument) { 
  if (someArgument === undefined) { 
    console.log("someArgument 是 undefined"); 
  } 
  if (arguments.length > 1) { 
    console.log("然而它實際是傳進來的"); 
  } 
} 
 
testUndefined("foo"); 
// 結果: someArgument 是 undefined 
testUndefined("foo", undefined); 
// 結果:  someArgument 是 undefined , 然而它實際是傳進來的

給參數命名

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

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

給每個參數起個名字，賦個默認值，可好

event.initMouseEvent( 
  type="click", 
  canBubble=true, 
  cancelable=true, 
  view=window, 
  detail=123, 
  screenX=101, 
  screenY=202, 
  clientX=101, 
  clientY=202, 
  ctrlKey=true, 
  altKey=false, 
  shiftKey=false, 
  metaKey=false, 
  button=1, 
  relatedTarget=null);

ES6, 或者 Harmony 就有默認參數值和 rest 參數了。

參數接收 JSON 對象

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

function nightmare(accepts, async, beforeSend, cache, complete, /* 等28個參數 */) { 
  if (accepts === "text") { 
    // 準備接收純文本 
  } 
} 
 
function dream(options) { 
  options = options || {}; 
  if (options.accepts === "text") { 
    // 準備接收純文本 
  } 
}

調用起來也更簡單了：

nightmare("text", true, undefined, false, undefined, /* 等28個參數 */); 
 
dream({ 
  accepts: "text", 
  async: true, 
  cache: false 
});

參數默認值

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

var default_options = { 
  accepts: "text", 
  async: true, 
  beforeSend: null, 
  cache: false, 
  complete: null, 
  // … 
}; 
 
function dream(options) { 
  var o = jQuery.extend({}, default_options, options || {}); 
  console.log(o.accepts); 
} 
 
dream({ async: false }); 
// prints: "text"

擴展性

回調（callbacks）

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

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

事件（events）

事件接口***見名知意，可以自由選擇事件名字，避免與原生事件重名。

處理錯誤

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

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

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

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

可預測性

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

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

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

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

// 所有這些屬性都返回 'true' 或 'false' 
Modernizr.geolocation 
Modernizr.localstorage 
Modernizr.webworkers 
Modernizr.canvas 
Modernizr.borderradius 
Modernizr.boxshadow 
Modernizr.flexbox

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

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

$("#grid") // Selects by ID 
$("ul.nav > li") // All LIs for the UL with class "nav" 
$("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)

最重要的是：確保文檔跟代碼同步更新。

參考資料：

好的 API 設計

Designing Better JavaScript APIs

Secrets of Awesome JavaScript API Design

責任編輯：王雪燕來源： Alon's Blog

JavaScript API 設計原則