前段时间组织优化我们的原生模块 API（iOS、Android 模块封装成 JavaScript 接口），于是学习了几篇 JavaScript API 设计的文章，尽管是旧文，但受益匪浅，这里记录一下。
好的 API 设计：在自描述的同时，达到抽象的目标。
设计良好的 API ，开发者可以快速上手，没必要经常抱着手册和文档，也没必要频繁光顾技术支持社区。
流畅的接口
方法链：流畅易读，更易理解
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
// 常见的 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"); }); |
设置和获取操作，可以合二为一；方法越多，文档可能越难写
|
1 2 3 4 5 6 7 8 9 10 |
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 元素设置样式：
|
1 2 3 4 5 |
jQuery("#some-selector") .css("background", "red") .css("color", "white") .css("font-weight", "bold") .css("padding", 10); |
这个方法可以接受一个 JSON 对象：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
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); |
处理类型
定义方法的时候，需要决定它可以接收什么样的参数。我们不清楚人们如何使用我们的代码，但可以更有远见，考虑支持哪些参数类型。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
// 原来的代码 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) 这样的字符串。
如果你需要确保传入的参数类型（字符串，数字，布尔），可以这样转换：
|
1 2 3 4 5 |
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 对象：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
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 , 然而它实际是传进来的 |
给参数命名
|
1 2 3 4 5 |
event.initMouseEvent( "click", true, true, window, 123, 101, 202, 101, 202, true, false, false, false, 1, null); |
Event.initMouseEvent 这个方法简直丧心病狂，不看文档的话，谁能说出每个参数是什么意思？
给每个参数起个名字，赋个默认值，可好
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
event.initMouseEvent( type="click", canBubble=true, cancelable=true, view=window, detail=123, screenX=101, screenY=202, clientX=101, clientY= |
