DIV CSS 佈局教程網

JavaScript API 設計準則:打造如藝術品般優雅的介面
編輯:JavaScript基礎知識     

「設計」是個相當普遍的概念,一般可理解為在動手做某件事之前,先形成一個計畫或框架。在《牛津英語詞典》中,設計是把藝術、體系、硬體或更多事物編織成一體的主線。軟體設計——特別是作為其子類的 API 設計——也是如此。然而,API 設計卻常常得不到軟體開發應有的重視,因為為其他程式設計師寫程式碼的重要性,往往被視為不如應用 UI 設計與最終用戶體驗。

但 API 作為我們在自己函式庫中對外提供的公共介面,能向呼叫我們程式碼的開發者展現這個函式庫的特點與功能,因此 API 設計與 UI 設計同樣重要。事實上,兩者都是為了讓應用能提供更好的用戶體驗。應用的 UI 在用戶體驗中佔有舉足輕重的地位,而應用的 API 就是開發者的用戶體驗。因此,API 設計應該獲得與用戶介面同等的關注與重視。正如同我們在意 UI 的功效、簡潔與優雅,我們也應該以同樣的標準來衡量 API 的功效、簡潔與程式碼之美!

JavaScript API 設計對所有開發者都構成了獨特的挑戰,無論你開發的是公開函式庫還是內部函式庫。JavaScript 的動態性、函式庫使用者的匿名性,以及需求的模稜兩可,都給 API 設計者帶來了嚴峻的考驗。然而,好的 API 設計沒有捷徑,但我們卻可以從當代一些流行的 JavaScript 函式庫中歸納出若干設計準則!

API 設計:天使與惡魔的拉鋸

糟糕的 JavaScript API 設計會給使用你 API 的開發者、以及你自己帶來高昂的成本。差的設計會造成浪費:使用者因琢磨不透你的介面而虛耗時間,而 API 開發者則忙於應對日益增多的疑問、解決使用者的困惑。然而幾乎所有 API 在最初被開發時,本意都是為了提取相同功能、方便呼叫並節省時間。但設計不良的 API 會讓函式庫使用者與你一起懷疑:這些函式庫真的能省時嗎?

優秀的 API 設計,一方面完成了提取的目標,另一方面也實現了自我描述。當一個 API 被良好設計,使用者能快速而直觀地完成工作,完全不必反覆翻閱文件或求助於支援網站。你也能透過封裝那些開發者原本得花大量時間自行實作的功能,來為函式庫開發者省下時間。好的設計不僅節省開發者的時間,還能讓他們看起來更聰明、更稱職。幫助你的用戶顯得聰明能幹,自然也讓你更顯專業!

對 JavaScript 而言,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 設計能適用於任何情境。

出色的 JavaScript API 設計秘訣

雖然軟體不像繪畫或建築那樣有視覺評價標準,我們卻仍傾向用形容實體的詞彙來描述軟體品質。例如,用「優雅的」與「漂亮的」來讚美軟體並不罕見。如果以類似實體的形容詞來描述軟體介面是合理的,那麼當然也可以用相同的原則來評價軟體設計。

本節將把四個源自藝術領域的流行設計原則,延伸到 API 設計中:

  1. 和諧一致
  2. 平衡
  3. 對稱
  4. 重點突出

對每個原則,我都會列出一個或多個實例,說明流行的 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 之類的框架將變得極其複雜,甚至無從實現。

API 設計:不只是函式庫作者的事

如果你不是一位 JavaScript 函式庫作者,而是應用開發者或函式庫實作者,你可能會認為本文的原則與你無關。畢竟,我們大多數人聽到「API」時,往往想到的是第三方函式庫,正如我在本文中的範例一樣。

但事實是,API 一如它的定義所言,無非就是一個提供給他人使用的、隔離功能的介面。現在,讓我用一句老話來強調很重要的一點:編寫模組化的 JavaScript 程式碼是為了實用,使用的次數並不重要。

正如本文引用的類別庫,你也可以把自己的 JavaScript 程式碼公開介面給他人使用。即使你的程式碼用戶只是一小群人、內部團隊——甚至你只是為自己打造一個私有類別庫——你也不必像公開類別庫作者那樣拘泥於本文的每一條 API 設計原則。善用 API 設計的好處在於:即使只服務一位使用者,也要像服務數百萬使用者那樣去設計。

因為 API 的設計代表著開發者的用戶體驗,它就像 UI 設計之於最終用戶那樣重要。正如我們能透過學習一些原則、參考好壞例子來打造優秀的 UI,我們也能以同樣的方式學會更好的 API 設計。應用文中提到的四個原則,以及你自己發現的其他原則,能幫助你建立優秀的 API,並讓用戶獲得良好的體驗。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved