JavaScript的API設(shè)計(jì)原則

作者：佚名 2017-06-19 14:21:01

本篇博文來自一次公司內(nèi)部的前端分享，從多個(gè)方面討論了在設(shè)計(jì)接口時(shí)的原則，總共包含了七個(gè)大塊。系鹵煮自己總結(jié)的一些經(jīng)驗(yàn)教訓(xùn)。同時(shí)也參考了一些文章，地址會在后面貼出來。很難做到詳盡充實(shí)，如果有好的建議或者不對的地方，還望不吝賜教斧正。

前言

一、接口的流暢性

好的接口是流暢易懂的，他主要體現(xiàn)如下幾個(gè)方面：

1.簡單

操作某個(gè)元素的css屬性，下面是原生的方法:

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

封裝之后

function a(selector, color) { 
 
  document.querySelectorAll(selector)[0].style.color = color 
 
} 
a('#a', 'red');

從幾十個(gè)字母長長的一行到簡簡單單的一個(gè)函數(shù)調(diào)用，體現(xiàn)了api簡單易用

2.可閱讀性

a(‘#a’, ‘red’)是個(gè)好函數(shù)，幫助我們簡單實(shí)用地改變某個(gè)元素，但問題來了，如果***次使用改函數(shù)的人來說會比較困惑，a函數(shù)是啥函數(shù)，沒有人告訴他。開發(fā)接口有必要知道一點(diǎn)，人都是懶惰的，從顏色賦值這個(gè)函數(shù)來說，雖然少寫了代碼，但是增加了記憶成本。每次做這件事情的時(shí)候都需要有映射關(guān)系。 a—->color. 如果是簡單的幾個(gè)無所謂，但是通常一套框架都有幾十甚至上百的api，映射成本增加會使得程序員哥哥崩潰。我們需要的就是使得接口有意義，下面我們改寫一下a函數(shù)：

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

letSomeElementChangeColor相對于a來說被賦予了語言意義，任何人都會知道它的意義

3.減少記憶成本

我們剛剛的函數(shù)也是這樣的它太長了letSomeElementChangeColor雖然減少了映射成本，但是增加了記憶成本。要知道，包括學(xué)霸在內(nèi)，任何人都不喜歡被單詞。原生獲取dom的api也同樣有這個(gè)問題 document.getElementsByClassName; document.getElementsByName; document.querySelectorAll;這些api給人的感覺就是單詞太長了，雖然他給出的意義是很清晰，然而這種做法是建立在犧牲簡易性的基礎(chǔ)上進(jìn)行的。于是我們又再次改寫這個(gè)之前函數(shù)

function setColor(selector, color) { 
 
  xxxxxxxxxxxx 
 
}

在意義不做大的變化前提下，縮減函數(shù)名稱。使得它易讀易記易用;

4.可延伸

所謂延伸就是指函數(shù)的使用像流水一樣按照書寫的順序執(zhí)行形成執(zhí)行鏈條:

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

用我們之前的之前的方法是再次封裝兩個(gè)函數(shù) setFontSize, setbackgroundColor; 然后執(zhí)行它們 setColor(‘id’, ‘red’);setFontSiez(‘id’, ’12px’); setbackgroundColor(‘id’, ‘pink’); 顯然，這樣的做法沒有懶出境界來;id元素每次都需要重新獲取，影響性能，失敗;每次都需要添加新的方法失敗每次還要調(diào)用這些方法，還是失敗。下面我們將其改寫為可以延伸的函數(shù) 首先將獲取id方法封裝成對象,然后再對象的每個(gè)方法中返回這個(gè)對象：

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 = color; 
 
  return this; 
 
} 
 
getElement.prototype.fontSize = function(size) { 
 
  this.style.fontSize = size; 
 
  return this; 
 
} 
 
  
 
//調(diào)用 
 
var el = new getElement('#id') 
 
el.color('red').background('pink').fontSize('12px');

簡單、流暢、易讀后面我們會在參數(shù)里面講到如何繼續(xù)優(yōu)化。所以，大家都比較喜歡用jquery的api，雖然一個(gè)$符號并不代表任何現(xiàn)實(shí)意義，但簡單的符號有利于我們的使用。它體現(xiàn)了以上的多種原則，簡單，易讀，易記，鏈?zhǔn)綄懛ǎ鄥⑻幚怼?/p>

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.接口的一致性

相關(guān)的接口保持一致的風(fēng)格，一整套 API 如果傳遞一種熟悉和舒適的感覺，會大大減輕開發(fā)者對新工具的適應(yīng)性。命名這點(diǎn)事：既要短，又要自描述，最重要的是保持一致性 “在計(jì)算機(jī)科學(xué)界只有兩件頭疼的事：緩存失效和命名問題” — Phil Karlton 選擇一個(gè)你喜歡的措辭，然后持續(xù)使用。選擇一種風(fēng)格，然后保持這種風(fēng)格。

Nightware:

setColor, 
 
letBackGround 
 
changefontSize 
 
makedisplay

dream:

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

盡量地保持代碼風(fēng)格和命名風(fēng)格，使人讀你的代碼像是閱讀同一個(gè)人寫的文章一樣。

三、參數(shù)的處理

1.參數(shù)的類型

判斷參數(shù)的類型為你的程序提供穩(wěn)定的保障

//我們規(guī)定，color接受字符串類型 
 
function setColor(color) { 
 
  if(typeof color !== 'string') return; 
 
dosomething 
 
}

2.使用json方式傳參

使用json的方式傳值很多好處，它可以給參數(shù)命名，可以忽略參數(shù)的具體位置，可以給參數(shù)默認(rèn)值等等比如下面這種糟糕的情況:

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

你必須對應(yīng)地把每一個(gè)參數(shù)按照順序傳入，否則你的方法就會偏離你預(yù)期去執(zhí)行，正確的方法是下面的做法。

function fn(json) { 
 
//為必須的參數(shù)設(shè)置默認(rèn)值 
 
   var default = extend({ 
 
param: 'default', 
 
param1: 'default' 
 
...... 
 
   },json) 
 
}

這段函數(shù)代碼，即便你不傳任何參數(shù)進(jìn)來，他也會預(yù)期運(yùn)行。因?yàn)樵诼暶鞯臅r(shí)候，你會根據(jù)具體的業(yè)務(wù)決定參數(shù)的缺省值。

四、可擴(kuò)展性

軟件設(shè)計(jì)最重要的原則之一：永遠(yuǎn)不修改接口，指擴(kuò)展它!可擴(kuò)展性同時(shí)會要求接口的職責(zé)單一，多職責(zé)的接口很難擴(kuò)展。舉個(gè)栗子：

//需要同時(shí)改變某個(gè)元素的字體和背景 
 
// Nightmare: 
 
function set(selector, color) { 
 
  document.querySelectroAll(selector).style.color = color; 
 
  document.querySelectroAll(selector).style.backgroundColor = color; 
 
} 
 
  
 
//無法擴(kuò)展改函數(shù)，如果需要再次改變字體的大小的話，只能修改此函數(shù)，在函數(shù)后面填加改變字體大小的代碼 
 
  
 
//Dream 
 
function set(selector, color) { 
 
  var el = document.querySelectroAll(selector); 
 
  el.style.color = color; 
 
  el.style.backgroundColor = color; 
 
  return el; 
 
} 
 
  
 
//需要設(shè)置字體、背景顏色和大小 
 
function setAgain (selector, color, px) { 
 
  var el = set(selector, color) 
 
  el.style.fontSize = px; 
 
  return el; 
 
}

以上只是簡單的添加顏色，業(yè)務(wù)復(fù)雜而代碼又不是你寫的時(shí)候，你就必須去閱讀之前的代碼再修改它，顯然是不符合開放-封閉原則的。修改后的function是返回了元素對象，使得下次需要改變時(shí)再次得到返回值做處理。

2.this的運(yùn)用

可擴(kuò)展性還包括對this的以及call和apply方法的靈活運(yùn)用：

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

五、對錯(cuò)誤的處理

1.預(yù)見錯(cuò)誤

可以用類型檢測 typeof 或者try…catch。 typeof 會強(qiáng)制檢測對象不拋出錯(cuò)誤，對于未定義的變量尤其有用。

2.拋出錯(cuò)誤

大多數(shù)開發(fā)者不希望出錯(cuò)了還需要自己去找?guī)?yīng)得代碼，***方式是直接在console中輸出，告訴用戶發(fā)生了什么事情。我們可以用到瀏覽器的輸出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); 
 
  } 
 
}

六、可預(yù)見性

可預(yù)見性味程序接口提供健壯性，為保證你的代碼順利執(zhí)行，必須為它考慮到非正常預(yù)期的情況。我們看下不可以預(yù)見的代碼和可預(yù)見的代碼的區(qū)別用之前的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的源碼，可以看見，作者在預(yù)見傳入的參數(shù)時(shí)做了很多的處理。其實(shí)可預(yù)見性是為程序提供了若干的入口，無非是一些邏輯判斷而已。zepto在這里使用了很多的是非判斷，同時(shí)導(dǎo)致了代碼的冗長，不適合閱讀。總之，可預(yù)見性真正需要你做的事多寫一些對位置實(shí)物的參數(shù)。把外部的檢測改為內(nèi)部檢測。是的使用的人用起來舒心放心開心。吶!做人嘛最重要的就是海森啦。

七、注釋和文檔的可讀性

一個(gè)***的接口是不需要文檔我們也會使用它，但是往往接口量一多和業(yè)務(wù)增加，接口使用起來也會有些費(fèi)勁。所以接口文檔和注釋是需要認(rèn)真書寫的。注釋遵循簡單扼要地原則，給多年后的自己也給后來者看：

//注釋接口，為了演示PPT用 
 
function commentary() { 
 
  //如果你定義一個(gè)沒有字面意義的變量時(shí)，***為它寫上注釋：a：沒用的變量，可以刪除 
 
  var a; 
 
  
 
  //在關(guān)鍵和有歧義的地方寫上注釋，猶如畫龍點(diǎn)睛：路由到hash界面后將所有的數(shù)據(jù)清空結(jié)束函數(shù) 
 
  return go.Navigate('hash', function(){ 
 
    data.clear(); 
 
  }); 
 
}