作者：Alon
原文地址：
http://jinlong.github.io/2015/08/31/secrets-of-awesome-javascript-api-design/
前段時(shí)間組織優(yōu)化我們的原生模塊 API（iOS、Android 模塊封裝成 JavaScript 接口），于是學(xué)習(xí)了幾篇 JavaScript API 設(shè)計(jì)的文章，盡管是舊文，但受益匪淺此改，這里記錄一下。
好的 API 設(shè)計(jì)：在自描述的同時(shí)，達(dá)到抽象的目標(biāo)另萤。
設(shè)計(jì)良好的 API ，開發(fā)者可以快速上手诅挑，沒必要經(jīng)常抱著手冊和文檔四敞，也沒必要頻繁光顧技術(shù)支持社區(qū)。
流暢的接口
方法鏈：流暢易讀拔妥，更易理解忿危。
//常見的 API 調(diào)用方式：改變一些顏色，添加事件監(jiān)聽
var elem = document.getElementById("foobar");
elem.style.background = "red";
elem.style.color = "green";
elem.addEventListener('click', function(event) {
alert("hello world!");
}, true);
//（設(shè)想的）方法鏈 API
DOMHelper.getElementById('foobar')
.setStyle("background", "red")
.setStyle("color", "green")
.addEvent("click", function(event) {
alert("hello world");
});
設(shè)置和獲取操作没龙，可以合二為一铺厨；方法越多，文檔可能越難寫硬纤。
var $elem = jQuery("#foobar");
//setter
$elem.setCss("background", "green");
//getter
$elem.getCss("color") === "red";
//getter, setter 合二為一
$elem.css("background", "green");
$elem.css("color") === "red";
一致性
相關(guān)的接口保持一致的風(fēng)格解滓，一整套 API 如果傳遞一種熟悉和舒適的感覺，會(huì)大大減輕開發(fā)者對新工具的適應(yīng)性筝家。
命名這點(diǎn)事：既要短洼裤，又要自描述，最重要的是保持一致性溪王。
“There are only two hard problems in computer science: cache-invalidation and naming things.”“在計(jì)算機(jī)科學(xué)界只有兩件頭疼的事：緩存失效和命名問題”— Phil Karlton
選擇一個(gè)你喜歡的措辭逸邦，然后持續(xù)使用。選擇一種風(fēng)格在扰，然后保持這種風(fēng)格缕减。
處理參數(shù)
需要考慮大家如何使用你提供的方法，是否會(huì)重復(fù)調(diào)用芒珠？為何會(huì)重復(fù)調(diào)用桥狡？
你的 API 如何幫助開發(fā)者減少重復(fù)的調(diào)用？接收map映射參數(shù)皱卓，回調(diào)或者序列化的屬性名裹芝，不僅讓你的 API 更干凈，而且使用起來更舒服娜汁、高效嫂易。
jQuery 的 css()方法可以給 DOM 元素設(shè)置樣式：
jQuery("#some-selector")
.css("background", "red")
.css("color", "white")
.css("font-weight", "bold")
.css("padding", 10);
這個(gè)方法可以接受一個(gè) JSON 對象：
jQuery("#some-selector").css({
"background" : "red",
"color" : "white",
"font-weight" : "bold",
"padding" : 10
});
//通過傳一個(gè) map 映射綁定事件
jQuery("#some-selector").on({
"click" : myClickHandler,
"keyup" : myKeyupHandler,
"change" : myChangeHandler
});
//為多個(gè)事件綁定同一個(gè)處理函數(shù)
jQuery("#some-selector").on("click keyup change", myEventHandler);
處理類型
定義方法的時(shí)候，需要決定它可以接收什么樣的參數(shù)掐禁。我們不清楚人們?nèi)绾问褂梦覀兊拇a怜械，但可以更有遠(yuǎn)見颅和，考慮支持哪些參數(shù)類型。
//原來的代碼
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行代碼缕允，我們的方法強(qiáng)大到可以接收Date對象峡扩，數(shù)字的時(shí)間戳，甚至像Sat Sep 08 2012 15:34:35 GMT+0200 (CEST)這樣的字符串障本。
如果你需要確保傳入的參數(shù)類型（字符串教届，數(shù)字，布爾）驾霜，可以這樣轉(zhuǎn)換：
function castaway(some_string, some_integer, some_boolean) {
some_string += "";
some_integer += 0; // parseInt(some_integer, 10) 更安全些
some_boolean = !!some_boolean;
}
處理 undefined
為了使你的 API 更健壯案训，需要鑒別是否真正的undefined值被傳遞進(jìn)來，可以檢查arguments對象：
function testUndefined(expecting, someArgument) {
if (someArgument === undefined) {
console.log("someArgument 是 undefined");
}
if (arguments.length > 1) {
console.log("然而它實(shí)際是傳進(jìn)來的");
}
}
testUndefined("foo");
// 結(jié)果: someArgument 是 undefined
testUndefined("foo", undefined);
// 結(jié)果: someArgument 是 undefined , 然而它實(shí)際是傳進(jìn)來的
給參數(shù)命名
event.initMouseEvent(
"click", true, true, window,
123, 101, 202, 101, 202,
true, false, false, false,
1, null);
Event.initMouseEvent 這個(gè)方法簡直喪心病狂粪糙，不看文檔的話强霎，誰能說出每個(gè)參數(shù)是什么意思？
給每個(gè)參數(shù)起個(gè)名字猜旬，賦個(gè)默認(rèn)值，可好：
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 就有 默認(rèn)參數(shù)值 和 rest 參數(shù) 了倦卖。
參數(shù)接收 JSON 對象
與其接收一堆參數(shù)洒擦，不如接收一個(gè) JSON 對象：
function nightmare(accepts, async, beforeSend, cache, complete, /* 等28個(gè)參數(shù) */) {
if (accepts === "text") {
// 準(zhǔn)備接收純文本
}
}
function dream(options) {
options = options || {};
if (options.accepts === "text") {
// 準(zhǔn)備接收純文本
}
}
調(diào)用起來也更簡單了：
nightmare("text", true, undefined, false, undefined, /* 等28個(gè)參數(shù) */);
dream({
accepts: "text",
async: true,
cache: false
});
參數(shù)默認(rèn)值
參數(shù)最好有默認(rèn)值，通過 [jQuery.extend()](http://api.jquery.com/jQuery.extend/%20%20,%20_.extend() http://underscorejs.org/#extend) 和 Protoype 的 Object.extend 怕膛，可以覆蓋預(yù)設(shè)的默認(rèn)值熟嫩。
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"
擴(kuò)展性
回調(diào)（callbacks）
通過回調(diào)， API 用戶可以覆蓋你的某一部分代碼褐捻。把一些需要自定義的功能開放成可配置的回調(diào)函數(shù)掸茅，允許 API 用戶輕松覆蓋你的默認(rèn)代碼。
API 接口一旦接收回調(diào)柠逞，確保在文檔中加以說明昧狮，并提供代碼示例。
事件（events）
事件接口最好見名知意板壮，可以自由選擇事件名字逗鸣，避免與原生事件重名。
處理錯(cuò)誤
不是所有的錯(cuò)誤都對開發(fā)者調(diào)試代碼有用：
// jQuery 允許這么寫
$(document.body).on('click', {});
// 點(diǎn)擊時(shí)報(bào)錯(cuò)
// TypeError: ((p.event.special[l.origType] || {}).handle || l.handler).apply is not a function
// in jQuery.min.js on Line 3
這樣的錯(cuò)誤調(diào)試起來很痛苦绰精，不要浪費(fèi)開發(fā)者的時(shí)間撒璧，直接告訴他們犯了什么錯(cuò)：
if (Object.prototype.toString.call(callback) !== '[object Function]') { // 看備注
throw new TypeError("callback is not a function!");
}
備注：typeof callback === "function"在老的瀏覽器上會(huì)有問題，object會(huì)當(dāng)成個(gè)function笨使。
可預(yù)測性
好的 API 具有可預(yù)測性升熊，開發(fā)者可以根據(jù)例子推斷它的用法漩氨。
Modernizr’s 特性檢測 是個(gè)例子：
a) 它使用的屬性名完全與 HTML5、CSS 概念和 API 相匹配
b) 每一個(gè)單獨(dú)的檢測一致地返回 true 或 false 值
// 所有這些屬性都返回 'true' 或 'false'
Modernizr.geolocation
Modernizr.localstorage
Modernizr.webworkers
Modernizr.canvas
Modernizr.borderradius
Modernizr.boxshadow
Modernizr.flexbox
依賴于開發(fā)者已熟悉的概念也可以達(dá)到可預(yù)測的目的。
jQuery’s 選擇器語法 就是一個(gè)顯著的例子，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
比例協(xié)調(diào)
好的 API 并不一定是小的 API烤送，API 的體積大小要跟它的功能相稱。
比如 Moment.js 妻往，著名的日期解析和格式化的庫，可以稱之為均衡好渠，它的 API 既簡潔又功能明確。
像 Moment.js 這樣特定功能的庫霍掺，確保 API 的專注和小巧非常重要。
編寫 API 文檔
軟件開發(fā)最艱難的任務(wù)之一是寫文檔兔魂，實(shí)際上每個(gè)人都恨寫文檔，怨聲載道的是沒有一個(gè)好用的文檔工具勺良。
以下是一些文檔自動(dòng)生成工具：
- 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)
最重要的是：確保文檔跟代碼同步更新链蕊。
