前几日组织机构强化他们的原生植物组件 API（iOS、Android 组件PCB成 JavaScript USB），只好自学了两篇 JavaScript API 结构设计的该文，虽然是旧文，但受益匪浅，这儿历史记录呵呵。
好的 API 结构设计：在自描述的与此同时，达至抽象化的最终目标。
结构设计较好的 API ，开发人员能加速入门，没必要性时常抱着指南和文件格式，也没必要性频密来来往往相关服务街道社区。
简洁的USB
形式链：简洁易懂，更易认知
//常用的 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”;一致性
相关的USB保持一致的风格，一整套 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 USB一旦接收回调，确保在文件格式中加以说明，并提供代码示例。
该事件（events）
该事件USB最好见名知意，能自由选择该事件名字，避免与原生植物该事件 重名。
处理错误
不是所有的错误都对开发人员调试代码有用：
// 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
via：http://jinlong.github.io/2015/08/31/secrets-of-awesome-javascript-api-design/
