你的位置:首页 > 网页设计

[网页设计]JavaScript API 设计原则


网+线下沙龙 | 移动APP模式创新:给你一个做APP的理由>>

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

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

流畅的接口

方法链:流畅易读,更易理解

  1. //常见的 API 调用方式:改变一些颜色,添加事件监听 
  2. var elem = document.getElementById("foobar"); 
  3. elem.style.background = "red"; 
  4. elem.style.color = "green"; 
  5. elem.addEventListener('click', function(event) { 
  6.   alert("hello world!"); 
  7. }, true); 
  8.  
  9. //(设想的)方法链 API 
  10. DOMHelper.getElementById('foobar') 
  11.   .setStyle("background", "red") 
  12.   .setStyle("color", "green") 
  13.   .addEvent("click", function(event) { 
  14.     alert("hello world"); 
  15.   }); 

设置和获取操作,可以合二为一;方法越多,文档可能越难写

  1. var $elem = jQuery("#foobar"); 
  2.  
  3. //setter 
  4. $elem.setCss("background", "green"); 
  5. //getter 
  6. $elem.getCss("color") === "red"; 
  7.  
  8. //getter, setter 合二为一 
  9. $elem.css("background", "green"); 
  10. $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. jQuery("#some-selector") 
  2.   .css("background", "red") 
  3.   .css("color", "white") 
  4.   .css("font-weight", "bold") 
  5.   .css("padding", 10); 

这个方法可以接受一个 JSON 对象:

  1. jQuery("#some-selector").css({ 
  2.   "background" : "red", 
  3.   "color" : "white", 
  4.   "font-weight" : "bold", 
  5.   "padding" : 10 
  6. }); 
  7.  
  8. //通过传一个 map 映射绑定事件 
  9. jQuery("#some-selector").on({ 
  10.   "click" : myClickHandler, 
  11.   "keyup" : myKeyupHandler, 
  12.   "change" : myChangeHandler 
  13. }); 
  14.  
  15. //为多个事件绑定同一个处理函数 
  16. jQuery("#some-selector").on("click keyup change", myEventHandler); 

处理类型

定义方法的时候,需要决定它可以接收什么样的参数。我们不清楚人们如何使用我们的代码,但可以更有远见,考虑支持哪些参数类型。

  1. //原来的代码 
  2. DateInterval.prototype.days = function(start, end) { 
  3.   return Math.floor((end - start) / 86400000); 
  4. }; 
  5.  
  6. //修改后的代码 
  7. DateInterval.prototype.days = function(start, end) { 
  8.   if (!(start instanceof Date)) { 
  9.     start = new Date(start); 
  10.   } 
  11.   if (!(end instanceof Date)) { 
  12.     end = new Date(end); 
  13.   } 
  14.  
  15.   return Math.floor((end.getTime() - start.getTime()) / 86400000); 
  16. }; 

加了短短的6行代码,我们的方法强大到可以接收 Date 对象,数字的时间戳,甚至像 Sat Sep 08 2012 15:34:35 GMT+0200 (CEST) 这样的字符串

如果你需要确保传入的参数类型(字符串,数字,布尔),可以这样转换:

  1. function castaway(some_string, some_integer, some_boolean) { 
  2.   some_string += ""; 
  3.   some_integer += 0; // parseInt(some_integer, 10) 更安全些 
  4.   some_boolean = !!some_boolean; 

处理 undefined

为了使你的 API 更健壮,需要鉴别是否真正的 undefined 值被传递进来,可以检查 arguments 对象:

  1. function testUndefined(expecting, someArgument) { 
  2.   if (someArgument === undefined) { 
  3.     console.log("someArgument 是 undefined"); 
  4.   } 
  5.   if (arguments.length > 1) { 
  6.     console.log("然而它实际是传进来的"); 
  7.   } 
  8.  
  9. testUndefined("foo"); 
  10. // 结果: someArgument 是 undefined 
  11. testUndefined("foo", undefined); 
  12. // 结果:  someArgument 是 undefined , 然而它实际是传进来的 

给参数命名

  1. event.initMouseEvent( 
  2.   "click", true, true, window, 
  3.   123, 101, 202, 101, 202, 
  4.   true, false, false, false, 
  5.   1, null); 

Event.initMouseEvent 这个方法简直丧心病狂,不看文档的话,谁能说出每个参数是什么意思?

给每个参数起个名字,赋个默认值,可好

  1. event.initMouseEvent( 
  2.   type="click", 
  3.   canBubble=true, 
  4.   cancelable=true, 
  5.   view=window, 
  6.   detail=123, 
  7.   screenX=101, 
  8.   screenY=202, 
  9.   clientX=101, 
  10.   clientY=202, 
  11.   ctrlKey=true, 
  12.   altKey=false, 
  13.   shiftKey=false, 
  14.   metaKey=false, 
  15.   button=1, 
  16.   relatedTarget=null); 

ES6, 或者 Harmony 就有 默认参数值 和 rest 参数 了。

参数接收 JSON 对象

与其接收一堆参数,不如接收一个 JSON 对象:

  1. function nightmare(accepts, async, beforeSend, cache, complete, /* 等28个参数 */) { 
  2.   if (accepts === "text") { 
  3.     // 准备接收纯文本 
  4.   } 
  5.  
  6. function dream(options) { 
  7.   options = options || {}; 
  8.   if (options.accepts === "text") { 
  9.     // 准备接收纯文本 
  10.   } 

调用起来也更简单了:

  1. nightmare("text", true, undefined, false, undefined, /* 等28个参数 */); 
  2.  
  3. dream({ 
  4.   accepts: "text", 
  5.   async: true, 
  6.   cache: false 
  7. }); 

参数默认值

参数最好有默认值,通过 jQuery.extend() http://underscorejs.org/#extend) 和 Protoype 的 Object.extend ,可以覆盖预设的默认值。

  1. var default_options = { 
  2.   accepts: "text", 
  3.   async: true, 
  4.   beforeSend: null, 
  5.   cache: false, 
  6.   complete: null, 
  7.   // … 
  8. }; 
  9.  
  10. function dream(options) { 
  11.   var o = jQuery.extend({}, default_options, options || {}); 
  12.   console.log(o.accepts); 
  13.  
  14. dream({ async: false }); 
  15. // prints: "text" 

扩展性

回调(callbacks)

通过回调, API 用户可以覆盖你的某一部分代码。把一些需要自定义的功能开放成可配置的回调函数,允许 API 用户轻松覆盖你的默认代码。

API 接口一旦接收回调,确保在文档中加以说明,并提供代码示例。

事件(events)

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

处理错误

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

  1. // jQuery 允许这么写 
  2. $(document.body).on('click', {}); 
  3.  
  4. // 点击时报错 
  5. //   TypeError: ((p.event.special[l.origType] || {}).handle || l.handler).apply is not a function 
  6. //   in jQuery.min.js on Line 3 

这样的错误调试起来很痛苦,不要浪费开发者的时间,直接告诉他们犯了什么错:

  1. if (Object.prototype.toString.call(callback) !== '[object Function]') { // 看备注 
  2.   throw new TypeError("callback is not a function!"); 
  3.     备注:typeof callback === "function" 在老的浏览器上会有问题,object 会当成个 function 。 

可预测性

好的 API 具有可预测性,开发者可以根据例子推断它的用法。

Modernizr’s 特性检测 是个例子:

a) 它使用的属性名完全与 HTML5、CSS 概念和 API 相匹配

b) 每一个单独的检测一致地返回 true 或 false 值

  1. // 所有这些属性都返回 'true' 或 'false' 
  2. Modernizr.geolocation 
  3. Modernizr.localstorage 
  4. Modernizr.webworkers 
  5. Modernizr.canvas 
  6. Modernizr.borderradius 
  7. Modernizr.boxshadow 
  8. Modernizr.flexbox 

依赖于开发者已熟悉的概念也可以达到可预测的目的。

jQuery’s 选择器语法 就是一个显著的例子,CSS1-CSS3 的选择器可直接用于它的 DOM 选择器引擎。

  1. $("#grid") // Selects by ID 
  2. $("ul.nav > li") // All LIs for the UL with class "nav" 
  3. $("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)