「設計」是個相當普遍的概念,一般可理解為在動手做某件事之前,先形成一個計畫或框架。在《牛津英語詞典》中,設計是把藝術、體系、硬體或更多事物編織成一體的主線。軟體設計——特別是作為其子類的 API 設計——也是如此。然而,API 設計卻常常得不到軟體開發應有的重視,因為為其他程式設計師寫程式碼的重要性,往往被視為不如應用 UI 設計與最終用戶體驗。
但 API 作為我們在自己函式庫中對外提供的公共介面,能向呼叫我們程式碼的開發者展現這個函式庫的特點與功能,因此 API 設計與 UI 設計同樣重要。事實上,兩者都是為了讓應用能提供更好的用戶體驗。應用的 UI 在用戶體驗中佔有舉足輕重的地位,而應用的 API 就是開發者的用戶體驗。因此,API 設計應該獲得與用戶介面同等的關注與重視。正如同我們在意 UI 的功效、簡潔與優雅,我們也應該以同樣的標準來衡量 API 的功效、簡潔與程式碼之美!
JavaScript API 設計對所有開發者都構成了獨特的挑戰,無論你開發的是公開函式庫還是內部函式庫。JavaScript 的動態性、函式庫使用者的匿名性,以及需求的模稜兩可,都給 API 設計者帶來了嚴峻的考驗。然而,好的 API 設計沒有捷徑,但我們卻可以從當代一些流行的 JavaScript 函式庫中歸納出若干設計準則!
糟糕的 JavaScript API 設計會給使用你 API 的開發者、以及你自己帶來高昂的成本。差的設計會造成浪費:使用者因琢磨不透你的介面而虛耗時間,而 API 開發者則忙於應對日益增多的疑問、解決使用者的困惑。然而幾乎所有 API 在最初被開發時,本意都是為了提取相同功能、方便呼叫並節省時間。但設計不良的 API 會讓函式庫使用者與你一起懷疑:這些函式庫真的能省時嗎?
優秀的 API 設計,一方面完成了提取的目標,另一方面也實現了自我描述。當一個 API 被良好設計,使用者能快速而直觀地完成工作,完全不必反覆翻閱文件或求助於支援網站。你也能透過封裝那些開發者原本得花大量時間自行實作的功能,來為函式庫開發者省下時間。好的設計不僅節省開發者的時間,還能讓他們看起來更聰明、更稱職。幫助你的用戶顯得聰明能幹,自然也讓你更顯專業!
無論哪種程式語言或框架,API 設計都很重要;而對 JavaScript 來說,它的重要性更甚於許多其他語言。首先,作為一门動態且後期綁定的語言,JavaScript 沒有編譯器能充當安全網或檢測單元功能,因此它無法主動發現你程式碼中的錯誤。Linting 或檢驗框架如 JSLint 與 JSHint 確實能幫上忙——這些工具能指出 JavaScript 中一些常見的錯誤,但當我們使用 API 時,它們卻無力偵測出問題。
這一切就都取決於你了。你可以打造一個設計良好的 API,引導用戶掉進眾所周知的「成功的坑」——也就是說,你的函式庫對開發者而言舒適而熟悉,同時提供正向回饋,並在開發者與你的程式碼互動時建立起信心。
「掉進成功的坑裡」最好的例子,就是 jQuery 運用 CSS 選擇器語法來取得 DOM 元素。例如,若我想取得所有帶有 blogPost 類別的 article 元素,我可以用 jQuery 這樣寫:
$("article.blogPost").fadeIn(); 選擇器 article.blogPost 與下面這段 CSS 使用完全相同的語法,這絕非偶然:
article.blogPost { border-radius: 10px; background-color: salmon; box-shadow: 0px 0px 10px 2px #ccc; } jQuery 的選擇器引擎被設計成能讓我與其他開發者,運用既有的 CSS 選擇器知識來與它互動。結果可想而知:如果 jQuery 要我用一套全新的、為特定目的打造的語法,我就會失去那份快速、明顯與高效。
我們可以從 jQuery 這類框架中汲取靈感,並將它應用於自己的設計。然而,汲取靈感並不等於抄襲,這其中有個拿捏的分寸——任何設計 API 的人,如果只是單純建立在別人的想法之上,無論好壞,都將照單全收。如果我們能把在優秀 JavaScript 中歸納出的準則,運用到其他領域,就能開發出擁有良好 API 的框架,而這些 API 設計能適用於任何情境。
雖然軟體不像繪畫或建築那樣有視覺評價標準,我們卻仍傾向用形容實體的詞彙來描述軟體品質。例如,用「優雅的」與「漂亮的」來讚美軟體並不罕見。如果以類似實體的形容詞來描述軟體介面是合理的,那麼當然也可以用相同的原則來評價軟體設計。
本節將把四個源自藝術領域的流行設計原則,延伸到 API 設計中:
對每個原則,我都會列出一個或多個實例,說明流行的 JavaScript 函式庫 API 是如何遵循這些原則的。
在藝術作品中,一致性是一件作品背後不可或缺的觀念,也就是設計者如何把事物組合成連貫的整體。協調性則指作品中相似元素的佈局,會在整體觀照下產生一種簡潔的感覺。
對 API 設計者而言,這些原則可以透過在類別庫中使用類似或統一的元素來實現。以 Kendo UI 為例,這是一個用於建立 Rich Web 應用的 JavaScript 框架。Kendo UI 提供了一系列 UI 控制項與工具,它們都能透過一個簡單的語法來初始化。比如,我想從一個無序清單建立樹狀控制項(TreeView),只需呼叫:
$("ul.tree").kendoTreeView({ /* Configuration goes here */ }); 
Kendo UI 樹狀元件
如果我想透過一個清單建立面板 PanelBar,只要稍微改成不同的呼叫方式:
$("ul.panel").kendoPanelBar({ /* Configuration goes here */ }); 
Kendo UI 面板元件
Kendo UI 對所有元件採用一致的 kendoX 語法,促成了整體的協調。更重要的是,這樣的設計依賴 jQuery 為 DOM 元素封裝的統一層,使設計對所有熟悉 jQuery 的開發者都更友善。數百萬開發者使用類似的「土語」(jQuery 語法),Kendo UI 因此得以順利地跨庫使用。
另一個協調的案例是 Backbone 的 [object].extend 語法,用來建立物件、繼承並擴展 Backbone 的 Models、Views、Collections 與 Routers 功能。用下面的程式碼就能建立一個帶有 Backbone 完整支援、又能自訂所需功能的 Model:
var Book = Backbone.Model.extend({ initialize: function() { ... }, author: function() { ... }, pubDate: function() { ... }, }); 統一與協調的目的,是讓 API 新手感到熟悉而舒適。透過功能不同、語法卻相同或相似的方式,API 變得親切,大大減輕了開發者上手新工具的負擔。
下一條原則是平衡——在組織元素時,不會讓某個部分過於沉重而蓋過其他部分、導致使用不穩。在藝術作品中,平衡就是視覺權重;即使不對稱,作品仍能給人一種不對稱下的平衡感,因為它遵循某種模式。在 API 設計的語境中,平衡指的是程式碼的視覺權重與可預測性(看得出功能)。
平衡的 API 讓人覺得各組成部分彼此相屬,它們行為一致,或互補地完成同一個目標。延伸來說,平衡的 API 也讓開發者能輕易預測並使用其他 API。以 Modernizr 的屬性檢測為例,它的平衡性體現在兩方面:a) 屬性名對應 HTML5 與 CSS 術語和 API 名稱;b) 每個屬性檢測都統一地回傳 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

只要存取單一屬性,開發者就能了解相關資訊,並據此存取每一個其他屬性——一個高品質 API 的強大之處,正在於它的簡單。平衡性也保證了我與 Modernizr 互動的程式碼,在每次讀寫時都保持一致的字面加權,不論我採用什麼慣例。另一方面,如果 Modernizr 新增了一個為 Canvas 補平的 API,那不僅類別庫的視覺加權會受到新 API 的影響,Modernizr 的範圍與用途也會大幅擴張,而我在與 API 互動時的可預測性也就受到了限制。
達到平衡的另一種方式,是依靠開發者對既有概念的熟悉來獲得可預測性。一個典型例子就是 jQuery 的選擇器語法,它把 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 透過沿用一個熟悉的概念並映射到自己的類別庫,jQuery 避免了另創一套全新的選擇器語法,同時也建立了一套機制,讓新用戶能透過一個可預測的 API 快速把函式庫投入生產。
接著是相稱性,它用來衡量作品中元素的大小與數量。與其說「好的 API 就是小的 API」,不如說相稱性是相對於用途的大小。一個相稱的 API,其介面規模與它的能力範圍相匹配。
舉例來說,Moment.js——一個流行的日期轉換與格式化類別庫——可以說具備相稱性,因為它的 API 表層緊湊,且與類別庫的目的明確匹配。Moment.js 專門處理日期,它的 API 提供了便利的功能來操作 JavaScript 的 Date 物件:
moment().format('dddd'); moment().startOf('hour').fromNow(); 
對於像 Moment.js 這種目標明確的類別庫,保持 API 的專注與簡單至關重要;而對於更龐大、更廣泛的類別庫,API 的規模則應當能反映類別庫自身的能力。
以 Underscore 為例,作為一個多功能的工具庫,它提供了大量便利函式,專為幫助開發者處理 JavaScript 的集合、陣列、函式與物件而設計。它的 API 量遠遠超過像 Moment.js 這樣的庫,但 Underscore 也是相稱的,因為庫中每個函式都有其明確的功效與目的。看下面的例子,前兩個用 Underscore 來處理陣列,最後一個處理字串:
_.each(["Todd", "Burke", "Derick"], function(name){ alert(name); }); _.map([1, 2, 3], function(num){ return num * 3; }); _.isNumber("ten"); // False 
當一個庫逐漸成長,維持比例的挑戰也變得更加嚴峻。為確保加進庫中的每個功能與函式都能強化庫的目的,需要投入更多考量。對於像 Kendo UI 這樣的大型庫,追求易擴展並不意味著我們得把每個功能都塞進去。對於像 Kendo 一樣龐大的庫,每個功能物件與特性都應該證明自己的價值,才配被納入。例如,Kendo UI 的 JavaScript 基於 DataSource,它能被用來查詢與處理遠端資料:
var dataSource = new kendo.data.DataSource({ transport: { read: { url: "https://search.twitter.com/search.json", dataType: "jsonp", data: { q: "API Design" } } }, schema: { data: "results" } }); 乍看之下,它像是一個習以為常的資料源,感覺超出了庫本身的基本目的。然而,今日網站的裝飾無不需要動態資料的支撐。資料源的引入,讓 Kendo UI 得以在整個庫的範圍內,用一套穩定而舒適的範式來解決遠端資料問題。
讓一個 API 淪為名副其實的 JavaScript 垃圾抽屜,是擴展函式庫的一大危機,但這並非唯一的危機。掉進「不讓 API 隨庫成長」的陷阱,或出於某些人為原因限制庫的規模,同樣都是危險的!不妥善處理 API 增長的最佳反例,就是 jQuery 的 jQuery 或 $ 函式。和我一樣喜歡 jQuery 的開發者成千上萬,但它這個門戶方法確實有點亂:從 DOM 選擇到在 jQuery 物件中包含 DOM 元素,這個方法提供了超過 11 種獨立的超載呼叫方式。
大體而言,有些並不十分相關的特性被硬塞進了同一個 API。從宏觀來看,jQuery 是個龐大的庫,其比例可以說是合理的;但另一方面,當我們硬把一個功能塞進單一介面、又不顧庫的比例時,jQuery 這個方法就顯得比例失衡了。
如果你發現自己正把一個不相干的特性硬塞進既有的方法,或正絞盡腦汁想為一個並不適合 API 的函式找到加入的理由,那麼你該做的,是鬆開束縛、讓庫得以呼吸。當你的用戶呼叫一個新的、能自我描述名稱的函式時,他們會更省時,也不會為既有方法增加負擔。
在藝術作品中,強調是利用對比使作品的某一側脫穎而出,形成焦點。在許多 API 中,焦點可能是某個通道或類別庫主要方法的錨點。另一個關於強調性的例子,是「鏈式」呼叫方式或流暢 API(fluent API),它透過凸顯類別庫的核心物件來增強強調效果。jQuery 傾向於在眾多功能演示中強調這個物件:
$('ul.first').find('.overdue') .css('background-color','red') .end() .find('.due-soon') .css('background-color', 'yellow'); 對許多現代類別庫而言,另一個強調的例子是可擴展性:類別庫建立者沒有提供的部分,會為你提供工具,讓你自行完成相關擴展。
一個典型例子可參考 jQuery 的 fn(發音近似「effin」)命名空間,這個通用的擴展點透過數不清的插件與補充類別庫完成:
(function($) { $.fn.kittehfy = function() { return this.each(function(idx, el) { var width = el.width, height = el.height; var src= "https://placekitten.com/"; el.src= src + width + "/" + height; }); }; })(jQuery); 另一個擴展性的例子是 Backbone 的「extend」函式,我們在本文中已見過:
var DocumentRow = Backbone.View.extend({ tagName: "li", className: "row", events: { "click .icon": "open", "click .button.edit": "openEditDialog" }, render: function() { ... } }); 
可擴展之所以是強調性的一環,是因為它讓我們意識到:既有的類別庫並不意味著一切都是完美的,同時也鼓勵我們去擴展適合自己的類別庫。當類別庫支援擴展時,它們不僅開啟了新的用途,也讓無數開發者受益於通用的場景。最好的例子莫過於 Backbone.Marionette 框架——一個擴展自 Backbone 的類別庫,其目標是「簡化大型 JavaScript 應用的結構」。若非有像 Backbone 這樣可擴展的類別庫,Marionette 之類的框架將變得極其複雜,甚至無從實現。
如果你不是一位 JavaScript 函式庫作者,而是應用開發者或函式庫實作者,你可能會認為本文的原則與你無關。畢竟,我們大多數人聽到「API」時,往往想到的是第三方函式庫,正如我在本文中的範例一樣。
但事實是,API 一如它的定義所言,無非就是一個提供給他人使用的、隔離功能的介面。現在,讓我用一句老話來強調很重要的一點:編寫模組化的 JavaScript 程式碼是為了實用,使用的次數並不重要。
正如本文引用的類別庫,你也可以把自己的 JavaScript 程式碼公開介面給他人使用。即使你的程式碼用戶只是一小群人、內部團隊——甚至你只是為自己打造一個私有類別庫——你也不必像公開類別庫作者那樣拘泥於本文的每一條 API 設計原則。善用 API 設計的好處在於:即使只服務一位使用者,也要像服務數百萬使用者那樣去設計。
因為 API 的設計代表著開發者的用戶體驗,它就像 UI 設計之於最終用戶那樣重要。正如我們能透過學習一些原則、參考好壞例子來打造優秀的 UI,我們也能以同樣的方式學會更好的 API 設計。應用文中提到的四個原則,以及你自己發現的其他原則,能幫助你建立優秀的 API,並讓用戶獲得良好的體驗。