JavaScript的API设计原则

时间: 2018-01-05阅读: 836标签: js知识

前言

本篇文章来自一次公司内部的前端分享,从多个方面讨论了在设计接口时遵循的原则,总共包含了七个大块。系卤煮自己总结的一些经验和教训。本篇博文同时也参考了其他一些文章,相关地址会在后面贴出来。很难做到详尽充实,如果有好的建议或者不对的地方,还望不吝赐教斧正。


一、接口的流畅性

好的接口是流畅易懂的,他主要体现如下几个方面:


1.简单

操作某个元素的css属性,下面是原生的方法:

document.querySelector('#id').style.color = 'red';

封装之后

function a(selector, color) {
   document.querySelector(selector).style.color = color
}
a('#a', 'red');

从几十个字母长长的一行到简简单单的一个函数调用,体现了api设计原则之一:简单易用。


2.可阅读性

a(‘#a’, ‘red’)是个好函数,帮助我们简单实用地改变某个元素,但问题来了,如果第一次使用该函数的人来说会比较困惑,a函数是啥函数,没有人告诉他。开发接口有必要知道一点,大多数人都是懒惰的(包括卤煮自己),从颜色赋值这个函数来说,虽然少写了代码,但是增加了单词字母的个数,使得它不再好记。每次做这件事情的时候都需要有映射关系: a—->color. 如果是简单的几个api倒是无所谓,但是通常一套框架都有几十甚至上百的api,映射成本增加会使得程序员哥哥崩溃。 我们需要的就是使得接口名称有意义,下面我们改写一下a函数:

function letSomeElementChangeColor(selector, color) {
    document.querySelectorAll(selector, color).style.color = color; 
}

letSomeElementChangeColor相对于a来说被赋予了现实语言上的意义,任何人都不需要看说明也能知道它的功能。


3.减少记忆成本

我们刚刚的函数太长了,letSomeElementChangeColor虽然减少了映射成本,有了语言上的意义,但是毫无疑问增加了记忆成本。要知道,包括学霸在内,任何人都不喜欢背单词。不仅仅在此处,原生获取dom的api也同样有这个问题: document.getElementsByClassName; document.getElementsByName; document.querySelectorAll;这些api给人的感觉就是单词太长了,虽然他给出的意义是很清晰,然而这种做法是建立在牺牲简易性和简忆性的基础上进行的。于是我们又再次改写这个之前函数

function setColor(selector, color) {
   //xxxxxxxxxxxx
}

在语言意义不做大的变化前提下,缩减函数名称。使得它易读易记易用。


4.可延伸

所谓延伸就是指函数的使用像流水一样按照书写的顺序执行形成执行链条:

document.getElementById('id').style.color = 'red';
document.getElementById('id').style.fontSize = '12px';
document.getElementById('id').style.backgourdColor = 'pink';

如果我们需要实现像以上有强关联性的业务时,用我们之前的之前的方法是再次封装两个函数 setFontSize, setbackgroundColor; 然后执行它们 setColor(‘id’, ‘red’);setFontSiez(‘id’, ‘12px’); setbackgroundColor(‘id’, ‘pink’); 显然,这样的做法没有懒出境界来;id元素每次都需要重新获取,影响性能,失败;每次都需要添加新的方法,失败; 每次还要调用这些方法,还是失败。下面我们将其改写为可以延伸的函数 首先将获取id方法封装成对象,然后再对象的每个方法中返回这个对象:

function getElement(selector) {
 this.style = document.querySelecotrAll(selector).style;
}
getElement.prototype.color = function(color) {
 this.style.color = color;
 return this;
}
getElement.prototype.background = function(bg) {
 this.style.backgroundColor = bg;
 return this;
}
getElement.prototype.fontSize = function(size) {
 this.style.fontSize = size;
 return this;
}

//调用
var el = new getElement('#id')
el.color('red').background('pink').fontSize('12px');

简单、流畅、易读,它们看起来就像行云流水一样,即在代码性能上得到了提升优化,又在视觉上悦目。后面我们会在参数里面讲到如何继续优化。 
所以,大家都比较喜欢用jquery的api,虽然一个$符号并不代表任何现实意义,但简单的符号有利于我们的使用。它体现了以上的多种原则,简单,易读,易记,链式写法,多参处理。 
Nightmare:

document.getElementById('id').style.color = 'red';
document.getElementById('id').style.fontSize = '12px';
document.getElementById('id').style.backgourdColor = 'pink';

dream:

$('id').css({color:'red', fontSize:'12px', backgroundColor:'pink'})


二、一致性

1.接口的一致性

相关的接口保持一致的风格,一整套 API 如果传递一种熟悉和舒适的感觉,会大大减轻开发者对新工具的适应性。 命名这点事:既要短,又要自描述,最重要的是保持一致性 “在计算机科学界只有两件头疼的事:缓存失效和命名问题” — Phil Karlton 选择一个你喜欢的措辞,然后持续使用。选择一种风格,然后保持这种风格。 
Nightmare:

setColor,
letBackGround
changefontSize
makedisplay

dream:

setColor;
setBackground;
setFontSize
set.........

尽量地保持代码风格和命名风格,使别人读你的代码像是阅读同一个人写的文章一样。


三、参数的处理

1.参数的类型

判断参数的类型为你的程序提供稳定的保障

//我们规定,color接受字符串类型
function setColor(color) {
 if(typeof color !== 'string') return;
 dosomething
}


2.使用json方式传参

使用json的方式传值很多好处,它可以给参数命名,可以忽略参数的具体位置,可以给参数默认值等等 比如下面这种糟糕的情况:

function fn(param1, param2...............paramN)

你必须对应地把每一个参数按照顺序传入,否则你的方法就会偏离你预期去执行,正确的方法是下面的做法。

function fn(json) {
  //为必须的参数设置默认值
 var default = extend({
   param: 'default',
   param1: 'default'
  // ......
 },json)
}

这段函数代码,即便你不传任何参数进来,他也会预期运行。因为在声明的时候,你会根据具体的业务预先决定参数的缺省值。


四、可扩展性

软件设计最重要的原则之一:永远不修改接口,而是去扩展它!可扩展性同时会要求接口的职责单一,多职责的接口很难扩展。 举个栗子:

//需要同时改变某个元素的字体和背景
// Nightmare:
function set(selector, color) {
 document.querySelectroAll(selector).style.color = color;
 document.querySelectroAll(selector).style.backgroundColor = color;
}
//无法扩展改函数,如果需要再次改变字体的大小的话,只能修改此函数,在函数后面填加改变字体大小的代码
//Dream
function set(selector, color) {
 var el = document.querySelectroAll(selector);
 el.style.color = color;
 el.style.backgroundColor = color;
 return el;
}
//需要设置字体、背景颜色和大小
function setAgain (selector, color, px) {
 var el = set(selector, color)
 el.style.fontSize = px;
 return el;
}

以上只是简单的添加颜色,业务复杂而代码又不是你写的时候,你就必须去阅读之前的代码再修改它,显然是不符合开放-封闭原则的。修改后的function是返回了元素对象,使得下次需要改变时再次得到返回值做处理。


2.this的运用

可扩展性还包括对this的以及call和apply方法的灵活运用:

function sayBonjour() {
 alert(this.a)
}
obj.a = 1;
obj.say = sayBonjour;
obj.say();//1
//or
sayBonjour.call||apply(obj);//1


五、对错误的处理

1.预见错误

可以用 类型检测 typeof 或者try…catch。 typeof 会强制检测对象不抛出错误,对于未定义的变量尤其有用。


2.抛出错误

大多数开发者不希望出错了还需要自己去找带对应得代码,最好方式是直接在console中输出,告诉用户发生了什么事情。我们可以用到浏览器为我们提供的api输出这些信息:console.log/warn/error。你还可以为自己的程序留些后路: try…catch。

function error (a) {
 if(typeof a !== 'string') {
   console.error('param a must be type of string')
 }
}
function error() {
 try {
   // some code excucete here maybe throw wrong
 }catch(ex) {
   console.wran(ex);
 }
}


六、可预见性

可预见性味程序接口提供健壮性,为保证你的代码顺利执行,必须为它考虑到非正常预期的情况。我们看下不可以预见的代码和可预见的代码的区别用之前的setColor

//nighware
function set(selector, color) {
 document.getElementById(selector).style.color = color;
}

//dream
zepto.init = function(selector, context) {
 var dom
 // If nothing given, return an empty Zepto collection
 if (!selector) return zepto.Z()
 // Optimize for string selectors
 else if (typeof selector == 'string') {
   selector = selector.trim()
   // If it's a html fragment, create nodes from it
   // Note: In both Chrome 21 and Firefox 15, DOM error 12
   // is thrown if the fragment doesn't begin with <
   if (selector[0] == '<' && fragmentRE.test(selector))
     dom = zepto.fragment(selector, RegExp.$1, context), selector = null
   // If there's a context, create a collection on that context first, and select
   // nodes from there
   else if (context !== undefined) return $(context).find(selector)
   // If it's a CSS selector, use it to select nodes.
   else dom = zepto.qsa(document, selector)
 }
 // If a function is given, call it when the DOM is ready
 else if (isFunction(selector)) return $(document).ready(selector)
 // If a Zepto collection is given, just return it
 else if (zepto.isZ(selector)) return selector
 else {
   // normalize array if an array of nodes is given
   if (isArray(selector)) dom = compact(selector)
   // Wrap DOM nodes.
   else if (isObject(selector))
     dom = [selector], selector = null
   // If it's a html fragment, create nodes from it
   else if (fragmentRE.test(selector))
     dom = zepto.fragment(selector.trim(), RegExp.$1, context), selector = null
   // If there's a context, create a collection on that context first, and select
   // nodes from there
   else if (context !== undefined) return $(context).find(selector)
   // And last but no least, if it's a CSS selector, use it to select nodes.
   else dom = zepto.qsa(document, selector)
 }
 // create a new Zepto collection from the nodes found
 return zepto.Z(dom, selector)
}


以上是zepto的源码,可以看见,作者在预见传入的参数时做了很多的处理。其实可预见性是为程序提供了若干的入口,无非是一些逻辑判断而已。zepto在这里使用了很多的是非判断,这样做的好处当然是代码比之前更健壮,但同时导致了代码的冗长,不适合阅读。总之,可预见性真正需要你做的事多写一些对位置实物的参数。把外部的检测改为内部检测。是的使用的人用起来舒心放心开心。呐!做人嘛最重要的就是海森啦。


七、注释和文档的可读性

一个最好的接口是不需要文档我们也会使用它,但是往往接口量一多和业务增加,接口使用起来也会有些费劲。所以接口文档和注释是需要认真书写的。注释遵循简单扼要地原则,给多年后的自己也给后来者看:

//注释接口,为了演示PPT用
function commentary() {
 //如果你定义一个没有字面意义的变量时,最好为它写上注释:a:没用的变量,可以删除
 var a;
 //在关键和有歧义的地方写上注释,犹如画龙点睛:路由到hash界面后将所有的数据清空结束函数
 return go.Navigate('hash', function(){
   data.clear();
 });
}

原文:http://www.cnblogs.com/constantince/p/5580003.html   

站长推荐

1.阿里云: 本站目前使用的是阿里云主机,安全/可靠/稳定。点击领取2000元代金券、了解最新阿里云产品的各种优惠活动点击进入

2.腾讯云: 提供云服务器、云数据库、云存储、视频与CDN、域名等服务。腾讯云各类产品的最新活动,优惠券领取点击进入

3.广告联盟: 整理了目前主流的广告联盟平台,如果你有流量,可以作为参考选择适合你的平台点击进入

链接: http://www.fly63.com/article/detial/326

JavaScript的声明提升

在JavaScript中,当出现var声明的变量或者function声明的函数时,会将该声明提到当前作用域的前面执行,这便是声明提升。值得注意的是,只是提升了声明操作,赋值还是在原来的位置进行。声明提升包括变量声明提升和函数声明提升。

base91 for javascript

原理和 base64 是一样的,ASCII 共有94个可打印字符,base64 使用了其中 64 个,base91 使用了 91 个。

javascript中什么是句柄?

一个句柄是指使用的一个唯一的整数值,即一个4字节(64位程序中为8字节)长的数值,来标识应用程序中的不同对象和同类中的不同的实例。

javascript不可变性是什么?

不可变性即某个变量在进行了某个操作之后,其本身没有发生变化,比如对于字符串而言,对字符串的任何操作都会改变字符串本身的值,而是在字符串的基础上复制出来一个然后再改变,这样我们就说是不可变的

为什么javascript不起作用?

JavaScript是一种属于网络的脚本语言,已经被广泛用于Web应用开发,常用来为网页添加各式各样的动态功能,为用户提供更流畅美观的浏览效果。通常JavaScript脚本是通过嵌入在HTML中来实现自身的功能的。

javascript怎么判断按钮被点击?

JavaScript可以通过Event对象的target事件或srcElement(IE浏览器支持)来判断按钮是否被点击。Event对象代表事件的状态,比如事件在其中发生的元素、键盘按键的状态、鼠标的位置、鼠标按钮的状态。

javascript由几部分组成?

JavaScript有三部分组成。分别为核心(ECMAScript) 、文档对象模型(DOM)、浏览器对象模型(BOM)。这三部分分别描述了该语言的语法和基本对象、处理网页内容的方法和接口、与浏览器进行交互的方法和接口。

Js输出方式有哪些?

在编写JavaScript代码的时候, 一定要记住每一句代码后面都需要添加一个分号, 并且这个分号必须是英文的分号,我们会发现有时候不写分号程序也能够运行, 这里并不是因为不需要分号, 而是浏览器自动帮助我们添加了分号

7个常见的 JavaScript 测验及解答

我相信学习新事物并评估我们所知的东西对自己的进步非常有用,可以避免了我们觉得自己的知识过时的情况。在本文中,我将介绍一些常见的 JavaScript 知识。请享用!

JavaScript中“javascript:void(0) ”是什么意思

expression 是一个要计算的 Javascript 标准的表达式。表达式外侧的圆括号是可选的,鉴于规范化,以及养成好习惯,建议写上去。当我们使用 void 操作符指定超级链接时,表达式会被计算但是不会在当前文档处装入任何内容。

内容以共享、参考、研究为目的,不存在任何商业目的。其版权属原作者所有,如有侵权或违规,请与小编联系!情况属实本人将予以删除!

文章投稿关于web前端网站点搜索站长推荐网站地图站长QQ:522607023

小程序专栏: 土味情话心理测试脑筋急转弯幽默笑话段子句子语录成语大全运营推广