JavaScript API的设计原则

本篇内容介绍了“JavaScript 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://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)

最重要的是：确保文档跟代码同步更新。

“JavaScript API的设计原则”的内容就介绍到这里了，感谢大家的阅读。如果想了解更多行业相关的知识可以关注亿速云网站，小编将为大家输出更多高质量的实用文章！