JavaScript 的 API 設計原則

發表於2016-06-14

前言

本篇博文來自一次公司內部的前端分享，從多個方面討論了在設計介面時的原則，總共包含了七個大塊。系滷煮自己總結的一些經驗教訓。同時也參考了一些文章，地址會在後面貼出來。很難做到詳盡充實，如果有好的建議或者不對的地方，還望不吝賜教斧正。

一、介面的流暢性

好的介面是流暢易懂的，他主要體現如下幾個方面：

1.簡單

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

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

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

封裝之後

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

function a(selector, color) {

document.querySelectorAll(selector)[0].style.color = color

}

a('#a', 'red');

從幾十個字母長長的一行到簡簡單單的一個函式呼叫，體現了api簡單易用

2.可閱讀性

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

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

function letSomeElementChangeColor(selector, color) {

document.querySelectorAll(selector, color);

}

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

3.減少記憶成本

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

function setColor(selector, color) {
 xxxxxxxxxxxx
}

function setColor(selector, color) {

xxxxxxxxxxxx

}

在意義不做大的變化前提下，縮減函式名稱。使得它易讀易記易用；

4.可延伸

所謂延伸就是指函式的使用像流水一樣按照書寫的順序執行形成執行鏈條:

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

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 = color;
  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');

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;

}

//呼叫

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';

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	$('id').css({color:'red', fontSize:'12px', backgroundColor:'pink'})

二、一致性

1.介面的一致性

相關的介面保持一致的風格，一整套 API 如果傳遞一種熟悉和舒適的感覺，會大大減輕開發者對新工具的適應性。命名這點事：既要短，又要自描述，最重要的是保持一致性 “在電腦科學界只有兩件頭疼的事：快取失效和命名問題” — Phil Karlton 選擇一個你喜歡的措辭，然後持續使用。選擇一種風格，然後保持這種風格。

Nightware:

setColor,
letBackGround
changefontSize
makedisplay

setColor,

letBackGround

changefontSize

makedisplay

dream:

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

setColor;

setBackground;

setFontSize

set.........

儘量地保持程式碼風格和命名風格，使人讀你的程式碼像是閱讀同一個人寫的文章一樣。

三、引數的處理

1.引數的型別

判斷引數的型別為你的程式提供穩定的保障

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

//我們規定，color接受字串型別

function setColor(color) {

if(typeof color !== 'string') return;

dosomething

}

2.使用json方式傳參

使用json的方式傳值很多好處，它可以給引數命名，可以忽略引數的具體位置，可以給引數預設值等等比如下面這種糟糕的情況:

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

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

你必須對應地把每一個引數按照順序傳入，否則你的方法就會偏離你預期去執行，正確的方法是下面的做法。

function fn(json) {
//為必須的引數設定預設值
   var default = extend({
	param: 'default',
	param1: 'default'
	......
   },json)
}

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;
}

//需要同時改變某個元素的字型和背景

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

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);
  }
}

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)
}

//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();
  });
}