JavaScript API 设计基准

作者: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";

一致性

连锁的接口保持一致的作风,1整套 API
借使传递1种纯熟和清爽的觉得,会大大减轻开发者对新工具的适应性。

命名这一点事:既要短,又要自描述,最要害的是维系①致性。

“There are only two hard problems in computer science:
cache-invalidation and naming
things.”“在微型总结机科学界唯有两件脑仁疼的事:缓存失效和命名难点”— PhilKarlton

慎选贰个你欣赏的用语,然后持续利用。选用壹种风格,然后保持那种风格。

拍卖参数

亟需思量我们怎么运用你提供的不二等秘书籍,是还是不是会再次调用?为啥会再次调用?

你的 API
如何援救开发者减弱重复的调用?接收map映射参数,回调或然体系化的属性名,不仅让你的
API 更彻底,而且接纳起来更舒畅(Jennifer)、高效。

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 对象

与其吸收一群参数,不及接收3个 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 具有可预测性,开发者能够依照例子测度它的用法。

CoffeeScript,Modernizr’s
脾性检查测试

是个例子:

a) 它应用的习性名完全与 HTML伍、CSS 概念和 API 相匹配
b) 每八个独门的检查评定1致地再次来到 true 或 false 值

// 所有这些属性都返回 'true' 或 'false'
Modernizr.geolocation
Modernizr.localstorage
Modernizr.webworkers
Modernizr.canvas
Modernizr.borderradius
Modernizr.boxshadow
Modernizr.flexbox

重视于开发者已精晓的概念也能够高达可预测的目标。

jQuery’s
选用器语法

即是3个醒目的事例,CSS一-CSS三 的选用器可间接用来它的 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 的令人瞩目和Mini格外重要。

编写 API 文档

软件开发最辛勤的职务之1是写文书档案,实际上各种人都恨写文书档案,怨声载道的是从未有过2个好用的文书档案工具。

以下是有些文书档案自动生成工具:

最要紧的是:确认保障文档跟代码同步更新。

参考资料: