JavaScript API 设计原则的具体介绍

黄舟

发布时间：2017-03-08 15:02:07

1434人浏览过

来源于php中文网

原创

前段时间组织优化我们的原生模块 API（iOS、Android 模块封装成 JavaScript 接口），于是学习了几篇 JavaScript API 设计的文章，尽管是旧文，但受益匪浅，这里记录一下。

好的 API 设计：在自描述的同时，达到抽象的目标。

设计良好的 API ，开发者可以快速上手，没必要经常抱着手册和文档，也没必要频繁光顾技术支持社区。

流畅的接口

方法链：流畅易读，更易理解

立即学习“Java免费学习笔记（深入）”；

//常见的 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://www.php.cn/) 和 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）

事件接口最好见名知意，可以自由选择事件名字，避免与原生事件重名。

处理错误

不是所有的错误都对开发者调试代码有用：

企业网站管理系统源码2.0

这是一款比较精美的企业网站管理系统源码，功能比较完整，比较适合新手学习交流使用，也可以作为毕业设计或者课程设计使用，感兴趣的朋友可以下载看看哦。功能介绍：该源码主要包括前台和后台两大部分，具体功能如下：网站前台模块：主要包括企业简介、新闻中心、产品展示、公司证书、工程业绩、联系我们、客户系统、人才招聘等信息的浏览，以及客户留言的功能。网站后台模块1、常规管理：企业简介、链接管理、投票管理、系统设置

下载

// 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

javascript什么是作用域_全局和局部作用域如何划分【教程】

javascript为何需要事件循环机制【教程】

如何用javascript进行表单验证？_如何即时反馈用户的输入错误？【教程】

javascript Reflect是什么_怎样操作对象元属性【教程】

JavaScript 中 if-else 逻辑失效的常见原因：索引与值混淆问题

java速学教程(入门到精通)

java怎么学习？java怎么入门？java在哪学？java怎么学才快？不用担心，这里为大家提供了java速学教程(入门到精通)，有需要的小伙伴保存下载就能学习啦！

下载