設(shè)計(jì)是一個(gè)很普遍的概念，一般是可以理解為為即將做的某件事先形成一個(gè)計(jì)劃或框架。 (牛津英語(yǔ)詞典)中，設(shè)計(jì)是一種將藝術(shù)，體系，硬件或者更多的東西編織到一塊的主線。軟件設(shè)計(jì)，特別是作為軟件設(shè)計(jì)的次類的API設(shè)計(jì)，也是一樣的。但是API設(shè)計(jì)常常很少關(guān)注軟件發(fā)展，因?yàn)闉槠渌绦騿T寫代碼的重要性要次于應(yīng)用UI設(shè)計(jì)和最終用戶體驗(yàn)。

但是API設(shè)計(jì)，作為我們自己寫的庫(kù)中提供的公共接口，能夠向調(diào)用我們代碼的開發(fā)者表現(xiàn)出我們庫(kù)的一些特點(diǎn)和功能，所以API設(shè)計(jì)和UI設(shè)計(jì)一樣重要。事實(shí)上，兩者都是為應(yīng)用可以提供更好的用戶體驗(yàn)具有基本的方式。應(yīng)用UI在用戶UX中占有很重要的位置，應(yīng)用API是開發(fā)者的UX。因此，應(yīng)用API設(shè)計(jì)應(yīng)該被給予和我們提供給用戶的接口相同水平的考慮和關(guān)注。正像我們關(guān)注UI的功效，簡(jiǎn)潔性和優(yōu)美，我們也應(yīng)該同樣的評(píng)估API的功效，簡(jiǎn)潔性和代碼的優(yōu)美性！

API設(shè)計(jì)——javascript API設(shè)計(jì)的內(nèi)容，呈現(xiàn)了唯一的挑戰(zhàn)對(duì)所有的開發(fā)者，不管是否你正在開發(fā)一個(gè)公共的庫(kù)或者一個(gè)內(nèi)部的庫(kù)。javascript的動(dòng)態(tài)性，庫(kù)使用者的匿名和需求的模棱兩可都給API設(shè)計(jì)者呈現(xiàn)了一個(gè)令人畏懼的挑戰(zhàn)。然而對(duì)于一個(gè)好的API設(shè)計(jì)是沒(méi)有捷徑的，但是可以從現(xiàn)代流行的一些javascript庫(kù)中提取出一些設(shè)計(jì)準(zhǔn)則是可能的！

API設(shè)計(jì): 天使和惡魔的斗爭(zhēng)

javascript API中差的設(shè)計(jì)會(huì)給使用你API的開發(fā)者和你帶來(lái)高的花費(fèi)。差的設(shè)計(jì)會(huì)導(dǎo)致浪費(fèi)，使用你API的開發(fā)者會(huì)因?yàn)樵O(shè)法搞弄明白你接口而浪費(fèi)時(shí)間，而API的開發(fā)者會(huì)因?yàn)樘幚聿粩嘣黾拥男枨蠛徒鉀Q使用者的困惑而浪費(fèi)時(shí)間。然而幾乎所有的API當(dāng)初被開發(fā)的時(shí)候，都是為了能夠提取相同的功能，方便調(diào)用并節(jié)約時(shí)間。但設(shè)計(jì)不好的API會(huì)使你的庫(kù)使用者和你產(chǎn)生疑惑，這些庫(kù)真的能節(jié)約時(shí)間嗎？

優(yōu)秀的API設(shè)計(jì)，一方面，完成了提取的目標(biāo)，同時(shí)也實(shí)現(xiàn)了自我描述。當(dāng)一個(gè)API被良好的設(shè)計(jì)，使用者可以快速地和直觀地完成工作，完全不用不停的使用文檔或者持續(xù)的訪問(wèn)支持或者解答網(wǎng)站。你也可以通過(guò)封裝一些開發(fā)者需要自己花大量時(shí)間開發(fā)的一些特征來(lái)節(jié)約庫(kù)開發(fā)者的時(shí)間。好的設(shè)計(jì)不僅節(jié)約開發(fā)者的時(shí)間，可以使他們看起來(lái)更加聰明和有責(zé)任。同樣幫助你的用戶看起來(lái)聰明和能干也會(huì)使你看起來(lái)更加的牛逼！

對(duì)于javascript來(lái)說(shuō)，API設(shè)計(jì)特別重要

不管什么編程語(yǔ)言或者框架，API設(shè)計(jì)是重要的，API設(shè)計(jì)的重要性對(duì)于javascript來(lái)說(shuō)是高于其它許多語(yǔ)言的。首先，作為一個(gè)動(dòng)態(tài)的和后期綁定的語(yǔ)言，javascript沒(méi)有編譯器可以實(shí)現(xiàn)一個(gè)安全網(wǎng)或者檢測(cè)單元功能，所以javascript不可以發(fā)現(xiàn)你代碼中的錯(cuò)誤。Linting 或檢驗(yàn)框架 如 JSLint 和JSHint 可以幫助我們。這些框架的功能可以指出javascript中的一些普遍的錯(cuò)誤，但是當(dāng)我們使用API時(shí)，他們卻不能發(fā)現(xiàn)javascript的錯(cuò)誤。

這一切都取決于你，你可以開發(fā)一個(gè)具有良好設(shè)計(jì)的API，這個(gè)API可以幫助你的用戶掉進(jìn)眾所周知的“成功坑”，這就意味著你的庫(kù)對(duì)于開發(fā)者來(lái)說(shuō)是舒服的和熟悉的，同時(shí)也提供了積極的強(qiáng)化和當(dāng)開發(fā)者和你的代碼交互時(shí)建立的信心。

“掉進(jìn)成功的坑里”最好的例子是jQuery 通過(guò)CSS選擇器語(yǔ)法獲取DOM元素的運(yùn)用。例如，如果我想要獲取所有帶有類名的article元素，我可以運(yùn)用jQuery這樣做:
 

$("article.blogPost").fadeIn();

選擇器article.blogPost和下面展現(xiàn)使用完全一樣的語(yǔ)法，這絕不是偶然的！
 

article.blogPost {
 border-radius: 10px;
 background-color: salmon;
 box-shadow: 0px 0px 10px 2px #ccc;
}

jQuery的選擇器引擎被設(shè)計(jì)為了使我和其他開發(fā)者能夠使我對(duì)CSS選擇器的理解和它的引擎進(jìn)行交互。結(jié)果可想而知，如果jQuery需要我用一種新的，為特定目的形成的語(yǔ)法，我將失去快速，明顯和高效。

我們可以獲得靈感從這些框架中，如jQuery,或者其他框架，并應(yīng)用這些靈感到我們的設(shè)計(jì)中。然而，獲得靈感并不是抄襲，有個(gè)度的問(wèn)題，任何設(shè)計(jì)過(guò)API的人如果是僅僅的基于別人的想法，不管好與壞，他都將繼承。如果我們將在好的javascript中獲得的準(zhǔn)則運(yùn)用到其他領(lǐng)域中，我們能開發(fā)擁有好的API的框架，這些API設(shè)計(jì)能被運(yùn)用在任何情況下。

出色的Javascript APIs設(shè)計(jì)秘訣

雖然軟件不具有與繪畫或建筑類似的視覺(jué)評(píng)價(jià)標(biāo)準(zhǔn)，我們?nèi)詢A向于使用與物理實(shí)體一樣的形容詞來(lái)描述軟件質(zhì)量。例如，使用“優(yōu)雅的”與“漂亮的”來(lái)贊美軟件并不罕見。如果用與物理實(shí)體相似的形容詞描述軟件接口是合理的話，那么當(dāng)然也可以使用與之相同的原則來(lái)評(píng)價(jià)軟件設(shè)計(jì)。

在本節(jié)，將四個(gè)來(lái)自藝術(shù)領(lǐng)域的流行設(shè)計(jì)原則擴(kuò)展至API設(shè)計(jì)中：

1.     和諧一致
2.     平衡
3.     對(duì)稱
4.     重點(diǎn)突出

對(duì)每一個(gè)原則，將列出一到多個(gè)實(shí)例來(lái)說(shuō)明，這些例子表明流行的Javascript庫(kù)API設(shè)計(jì)是怎樣遵循這些原則的。

原則1：一致性&協(xié)調(diào)性

在藝術(shù)作品中，一致性是一個(gè)作品背后不可缺少的觀念，或者說(shuō)設(shè)計(jì)者如何把一些事物組成連貫的一個(gè)整體。協(xié)調(diào)性，從另一方面來(lái)說(shuō)，是一個(gè)作品相似元素的布局，這會(huì)在考慮整體時(shí)產(chǎn)生一種簡(jiǎn)潔的感覺(jué)。

對(duì)于API的設(shè)計(jì)者，這些原則可以通過(guò)在類庫(kù)使用類似的和（或者）統(tǒng)一的元素來(lái)實(shí)現(xiàn)。就拿Kendo UI來(lái)說(shuō)吧，一個(gè)創(chuàng)建富web應(yīng)用程序的javascript框架。Kendo UI提供了一系列的UI控件和工具，這些都可以通過(guò)一個(gè)簡(jiǎn)單的語(yǔ)法初始化。比如，如果我想從一個(gè)無(wú)序列表創(chuàng)建一個(gè)樹形控件（TreeView），我只需調(diào)用以下方法:
 

$("ul.tree").kendoTreeView({ /* Configuration goes here */ });

Kendo UI樹形組件

如果我想通過(guò)一個(gè)列表創(chuàng)建一個(gè)面板PanelBar，我只需稍微改成不同的調(diào)用方法.
 

$("ul.panel").kendoPanelBar({ /* Configuration goes here */ });

Kendo UI 面板組件

Kendo UI 對(duì)所有組件使用一致的kendoX語(yǔ)法，促進(jìn)整體的協(xié)調(diào)。更重要的，這樣的設(shè)計(jì)依賴jQuery對(duì)象為DOM元素封裝了統(tǒng)一的一層，使設(shè)計(jì)有利于所有熟悉jQuery開發(fā)者。數(shù)百萬(wàn)開發(fā)者使用類似的“土語(yǔ)”(jQuery語(yǔ)法)，Kendo UI可以順利地跨庫(kù)使用。

另一個(gè)協(xié)調(diào)的案例是Backbone的[object].extend語(yǔ)法創(chuàng)建對(duì)象，繼承和擴(kuò)展Backbone的Models,Views,Collections和Routers的功能。用如下代碼就可以創(chuàng)建一個(gè)Backbone Model，帶有Backbone的完整支持，也可以自定義我需要的功能：
 

var Book = Backbone.Model.extend({
 initialize: function() { ... },
 author: function() { ... },
 pubDate: function() { ... },
});

統(tǒng)一和協(xié)調(diào)的目的是讓API新手感覺(jué)熟悉和舒服。通過(guò)雖然功能不同，但是語(yǔ)法相同或相似，使API變得熟悉，大大減輕了開發(fā)者使用新工具的負(fù)擔(dān)。

原則 2 ：平衡

下一條原則是平衡，組織元素時(shí)不會(huì)讓某個(gè)部分過(guò)于重量級(jí)而蓋過(guò)其它部分，使用時(shí)不穩(wěn)定。藝術(shù)作品里，平衡就是視覺(jué)權(quán)重。即使不對(duì)稱，作品中仍能感覺(jué)到不對(duì)稱下的平衡，因?yàn)樗裱撤N模式。上下文中的API設(shè)計(jì)的平衡，我特指代碼的視覺(jué)權(quán)重和可預(yù)測(cè)性（看得出功能）。

平衡的API讓人覺(jué)得其組成部分屬于彼此，他們行為相同，或互補(bǔ)地完成一個(gè)目標(biāo)。通過(guò)擴(kuò)展，APIs也可以感覺(jué)平衡，它們?cè)试S開發(fā)人員簡(jiǎn)單的預(yù)測(cè)其他API并使用。如Modernizr的屬性測(cè)試，它們的平衡性在兩個(gè)方面，a)屬性名對(duì)應(yīng)HTML5和CSS術(shù)語(yǔ)和API名稱，b)每個(gè)屬性測(cè)試統(tǒng)一地返回true或false值。
 

// All of these properties will be 'true' or 'false' for a given browser
 Modernizr.geolocation
 Modernizr.localstorage
 Modernizr.webworkers
 Modernizr.canvas
 Modernizr.borderradius
 Modernizr.boxshadow
 Modernizr.flexbox

 訪問(wèn)一個(gè)單一的屬性來(lái)告訴開發(fā)者需要了解到的相關(guān)屬性，以便通過(guò)它訪問(wèn)每一個(gè)其他屬性，一個(gè)高質(zhì)量API的強(qiáng)大之處就在于它的簡(jiǎn)單。平衡性也保證了我寫和Modernizr交互的代碼在每次讀寫時(shí)具有相同的視覺(jué)加權(quán)。如何在我使用和訪問(wèn)API時(shí)看起來(lái)和感覺(jué)上一樣，而不顧我的慣例。另一方面，如果Modernizr添加了一個(gè)polyfill Canvas的API，不僅僅是類庫(kù)的視覺(jué)加權(quán)受到新API的影響，Modernizr的范圍和用途也將大大擴(kuò)大，并且我在和API交互時(shí)可預(yù)測(cè)性也受到了限制。

達(dá)到平衡的另一種方式是通過(guò)依靠開發(fā)人員對(duì)概念的熟悉獲得可預(yù)測(cè)性的結(jié)果。一個(gè)典型的例子就是（jquery選擇器的語(yǔ)法），它映射css1-3的選擇器到自己的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

例如，Moment.js，一個(gè)流行的日期轉(zhuǎn)換和格式化類庫(kù)，可以把它視為具有相稱性，因?yàn)樗腁PI表層是緊湊的，它和類庫(kù)的目的明確的匹配。Moment.js用于處理日期，它的API提供了便利的功能用來(lái)處理javascript Date對(duì)象:
 

moment().format('dddd');
moment().startOf('hour').fromNow();

 對(duì)于一個(gè)有針對(duì)性的類庫(kù)，像Moment.js，保持API的專注和簡(jiǎn)單是非常重要的。對(duì)于更大和更廣闊的類庫(kù)，API的大小應(yīng)當(dāng)能夠反映出類庫(kù)自身的能力。

拿Underscore來(lái)說(shuō)，作為一個(gè)多種用途功效的庫(kù)，它提供大量便利的函數(shù)，這些被設(shè)計(jì)的函數(shù)是用來(lái)幫助開發(fā)者處理javascript集合，數(shù)組，函數(shù)和對(duì)象。它的API量遠(yuǎn)遠(yuǎn)超過(guò)像Moment.js這樣的庫(kù)，但是Underscore也是成比例的，因?yàn)閹?kù)中每個(gè)函數(shù)都有自己的功效目的。考慮下面的例子，前兩個(gè)例子用Underscore來(lái)處理數(shù)組，最后一個(gè)來(lái)處理字符串。
 

_.each(["Todd", "Burke", "Derick"], function(name){
 alert(name);
});
 
_.map([1, 2, 3], function(num){
 return num * 3;
});
 
_.isNumber("ten"); // False

 當(dāng)一個(gè)庫(kù)逐漸成長(zhǎng)的過(guò)程中，維持比例的挑戰(zhàn)變的更加具有嚴(yán)峻。為了確保添加進(jìn)庫(kù)的每個(gè)功能和函數(shù)都能加強(qiáng)庫(kù)的目的，需要更多的考慮投入。對(duì)于一個(gè)大的庫(kù)像kendo UI,易擴(kuò)展性的目的并不是意味著我們需要往庫(kù)中添加每個(gè)特性。對(duì)于一個(gè)像kendo一樣大的庫(kù)，功能對(duì)象和特性應(yīng)該證明它們的價(jià)值才能被庫(kù)包含。例如， Kendo UI's JavaScript 基于DataSource, 它能夠被用來(lái)查詢和處理遠(yuǎn)程數(shù)據(jù)。
 

var dataSource = new kendo.data.DataSource({
 transport: {
  read: {
   url: "http://search.twitter.com/search.json",
    dataType: "jsonp",
    data: { q: "API Design" }
   }
  },
 schema: { data: "results" }
});

初看第一眼，它好像一個(gè)習(xí)以為常的數(shù)據(jù)源，感覺(jué)超出了庫(kù)本身的基本目的。然而今天網(wǎng)站的裝飾都需要?jiǎng)討B(tài)數(shù)據(jù)的支持。數(shù)據(jù)源的引入允許Kendo UI可以使用一個(gè)穩(wěn)定，并舒適的范式在整個(gè)庫(kù)范圍內(nèi)來(lái)解決遠(yuǎn)程數(shù)據(jù)。
 

讓一個(gè)API轉(zhuǎn)變?yōu)橐粋€(gè)名符其實(shí)的javascript垃圾抽屜，對(duì)于一個(gè)庫(kù)的擴(kuò)展這是危險(xiǎn)的，但對(duì)于庫(kù)來(lái)說(shuō)，這也不是唯一的危險(xiǎn)。掉入一個(gè)不讓你的API伴隨著庫(kù)的成長(zhǎng)圈套，或者由于某些人為原因，限制你庫(kù)的大小，這些同樣都是危險(xiǎn)的！

不處理API增長(zhǎng)最好的一個(gè)例子是jQuery的 jQuery or $ function。和我一樣有成千上萬(wàn)的開發(fā)者喜歡jQurey, 但它的門戶方法是有點(diǎn)亂的，從DOM選擇到在jQuery對(duì)象中包含DOM元素，這個(gè)方法提供了超過(guò)11個(gè)獨(dú)立超負(fù)荷選擇方式。

就大部分而言，有些不是十分相關(guān)的特性被硬塞進(jìn)同一個(gè)API。從全局看，jQuery是一個(gè)大的庫(kù)并且能被認(rèn)為庫(kù)比例是合理的。另一方面，當(dāng)我們嘗試將一個(gè)功能硬塞進(jìn)一個(gè)單一接口并且不考慮庫(kù)比例，jQuery方法也可以實(shí)現(xiàn)這樣的功能。

如果你發(fā)現(xiàn)你正在將一個(gè)不相干的特性強(qiáng)塞進(jìn)已經(jīng)存在的方法，或者正在想法設(shè)法使一個(gè)并不適合API的函數(shù)的添加合理化，你需要做的改變是松開皮帶并且讓庫(kù)呼吸。你的用戶在調(diào)用一個(gè)新的可以自我描述名字的函數(shù)時(shí)，將會(huì)更加節(jié)省時(shí)間，并且不會(huì)給另一個(gè)已經(jīng)存在的方法添加負(fù)擔(dān)。

原則 4: 強(qiáng)調(diào)性

在藝術(shù)作品中，強(qiáng)調(diào)是利用對(duì)比來(lái)使作品中某一方面脫穎而出形成一個(gè)焦點(diǎn)。在許多API中，焦點(diǎn)可能是一個(gè)通道或者類庫(kù)主要方法的錨點(diǎn)。另外一個(gè)關(guān)于強(qiáng)調(diào)性的例子可以參考“鏈接”方式或者fluent API，它通過(guò)增加強(qiáng)調(diào)性效果突出了類庫(kù)中心對(duì)象。jquery傾向于從許多功能演示中的強(qiáng)調(diào)這個(gè)對(duì)象:

$('ul.first').find('.overdue')
 .css('background-color','red')
 .end()
 .find('.due-soon')
 .css('background-color', 'yellow');

對(duì)于許多現(xiàn)代的類庫(kù)，另一個(gè)關(guān)于強(qiáng)調(diào)的例子是可擴(kuò)展性：類庫(kù)創(chuàng)建者沒(méi)有提供的那部分，會(huì)為你提供一個(gè)工具你可以自己完成相關(guān)擴(kuò)展。

一個(gè)典型的例子可以參考, 一般的擴(kuò)展點(diǎn)可以通過(guò)數(shù)不清的插件和補(bǔ)充的類庫(kù)來(lái)完成:

(function($) {
 $.fn.kittehfy = function() {
  return this.each(function(idx, el) {    
   var width = el.width,
    height = el.height;
   var src= "http://placekitten.com/";
   el.src= src + width + "/" + height;
  });
 };
})(jQuery);

var DocumentRow = Backbone.View.extend({
 tagName: "li",
 className: "row",
 events: {
  "click .icon": "open",
  "click .button.edit": "openEditDialog"
 },
 render: function() { ... }
});

 可擴(kuò)展作為強(qiáng)調(diào)性的一方面是因?yàn)樗屛覀円庾R(shí)到這樣的一個(gè)事實(shí)，已有的類庫(kù)并不意味著一切是完美的，同時(shí)也鼓勵(lì)我們擴(kuò)展適合自己的類庫(kù)。當(dāng)類庫(kù)支持?jǐn)U展時(shí)，它們不僅開啟了新的用途，也使無(wú)數(shù)開發(fā)者受益于一般的用途。一個(gè)最好的例子是Backbone.Marionette框架，一個(gè)擴(kuò)展于Backbone的類庫(kù)，它的目標(biāo)是“簡(jiǎn)化大型的javascript應(yīng)用程序的結(jié)構(gòu)”。如果不是像Backbone那樣的類庫(kù)擴(kuò)展，Marionette之類的類庫(kù)將變得非常復(fù)雜，甚至不可能實(shí)現(xiàn)。

API 設(shè)計(jì)：不只為庫(kù)代碼編寫者

如果你不是一位 JavaScript 庫(kù)的編寫者，而是一位 JavaScript 應(yīng)用開發(fā)者或庫(kù)的實(shí)現(xiàn)者，你可能會(huì)認(rèn)為本文中的原則并不適用于你。畢竟，我們大多數(shù)人在聽到“API”的時(shí)候，往往想到的是第三方庫(kù)，一如我在本文中的示例一樣

事實(shí)是，API ，如同其定義所言，無(wú)非就是一個(gè)提供給他人利用的隔離功能的接口。 現(xiàn)在，讓我用一句老話來(lái)強(qiáng)調(diào)很重要的一點(diǎn)：編寫模塊化的 JS 代碼是為了實(shí)用，使用的次數(shù)并不重要。

正如本文中引用的類庫(kù)，你可以把自己的javascript代碼公開接口給其他人。即使你的代碼的用戶是一小部分或內(nèi)部團(tuán)隊(duì)——甚至你構(gòu)建自己的一個(gè)私有類庫(kù)——你不必像一個(gè)公開類庫(kù)的作者那樣考慮本文中API設(shè)計(jì)原則和這些原則的實(shí)現(xiàn)。利用API設(shè)計(jì)的好處是即使只針對(duì)一個(gè)使用者，也要像對(duì)數(shù)百萬(wàn)使用者一樣設(shè)計(jì)。

因?yàn)锳PI的設(shè)計(jì)代表著對(duì)開發(fā)者的用戶體驗(yàn)，它就像UI設(shè)計(jì)對(duì)于最終用戶的重要性一樣。正如我們可以通過(guò)學(xué)習(xí)一些原則和參考一些好的或者壞的例子來(lái)開發(fā)出優(yōu)秀的UI一樣，我們也可以通過(guò)同樣的方式學(xué)習(xí)到更好的API設(shè)計(jì)。應(yīng)用文中提到的四個(gè)原則，以及其他你自己發(fā)現(xiàn)的原則，可以幫助你建立出優(yōu)秀的API，并且讓用戶得到良好的體驗(yàn)。

最新評(píng)論