前段時間組織優化我們的原生模組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 如果傳遞一種熟悉和舒適的感覺，會大幅減輕開發者對新工具的適應性。
命名這點事：既要短，又要自描述，最重要的是保持一致性
##選擇一個你喜歡的措辭，然後持續使用。選擇一種風格，然後保持這種風格。 處理參數要考慮大家如何使用你提供的方法，是否會重複呼叫？為何會重複呼叫？你的 API 如何幫助開發者減少重複的呼叫？“There are only two hard problems in computer science: cache-invalidation and naming things.」
「在電腦科學界只有兩件頭痛的事：快取失效與命名問題」
— Phil Karlton
接收map映射參數，回呼或序列化的屬性名，不僅讓你的 API 更乾淨，而且使用起來更舒服、有效率。
css() 方法可以為DOM 元素設定樣式：
jQuery("#some-selector")
.css("background", "red")
.css("color", "white")
.css("font-weight", "bold")
.css("padding", 10);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);
};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 值被傳遞進來，可以檢查 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( 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);
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
});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"// 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 3if (Object.prototype.toString.call(callback) !== '[object Function]') { // 看备注
throw new TypeError("callback is not a function!");
}備註：可預測性好的 API 具有可預測性，開發者可以根據範例推斷它的用法。 Modernizr's 特性偵測 是一個例子：a) 它使用的屬性名稱完全與HTML5、CSS 概念和API 相符b) 每一個單獨的偵測一致地傳回true 或false 值typeof callback === "function"
在舊的瀏覽器上會有問題，object會當成個function。
// 所有这些属性都返回 'true' 或 'false' Modernizr.geolocation Modernizr.localstorage Modernizr.webworkers Modernizr.canvas Modernizr.borderradius Modernizr.boxshadow Modernizr.flexbox
$("#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軟體開發最艱難的任務之一是寫文檔，實際上每個人都恨寫文檔，怨聲載道的是沒有一個好用的文檔工具。
以下是一些文件自動產生工具：
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
#
以上是JavaScript API 設計原則的具體介紹的詳細內容。更多資訊請關注PHP中文網其他相關文章！
