作者：Alon
原文地址：
http://jinlong.github.io/2015/08/31/secrets-of-awesome-javascript-api-design/
前段时间组织优化我们的原生模块 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://api.jquery.com/jQuery.extend/%20%20,%20_.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)
最重要的是：确保文档跟代码同步更新。
