設計這個詞的一般理解是「為即將做的事先形成計畫或框架」。 software design,特別是其中的 API 設計,同樣如此——只是它受到的關注遠少於 UI 設計。
這個偏斜並不合理。API 是你寫的程式庫對外呈現的公共介面,它向呼叫你程式碼的開發者傳達了這個庫的特點與能力。應用程式的 UI 決定終端使用者的體驗,應用程式的 API 決定開發者的體驗。兩者的重要性相當,衡量標準也應該相當:功效、簡潔、優雅。
JavaScript 是動態且晚期綁定的語言,沒有編譯器能當安全網。JSLint、JSHint 這類工具能指出常見錯誤,但它們無法在 API 使用層級保護你。
這意味著責任全在設計者身上:你可以打造一個引導使用者「掉進成功的坑」的 API——讓庫對開發者而言舒適、熟悉,並在互動中建立信心。
最好的例子是 jQuery 用 CSS 選擇器語法選取 DOM 元素:
$("article.blogPost").fadeIn();
而 article.blogPost 這個語法與 CSS 裡的寫法完全相同,絕非偶然:
article.blogPost {
border-radius: 10px;
background-color: salmon;
box-shadow: 0px 0px 10px 2px #ccc;
}
jQuery 刻意讓既有知識直接可用。如果它自創一套新語法,數百萬開發者就得重新學習,效率與直觀性都會流失。
從優秀程式庫中提取原則是對的,照抄則不是——抄襲會連對方的缺點一起繼承。
一致性是作品背後貫穿的觀念,協調性是相似元素的統一佈局,讓整體給人簡潔感。
Kendo UI 是個好例子。所有元件都用同一套 kendoXxx 語法初始化:
$("ul.tree").kendoTreeView({ /* 設定 */ });

Kendo UI 樹狀元件
$("ul.panel").kendoPanelBar({ /* 設定 */ });

Kendo UI 面板元件
統一的命名讓整體協調,而更重要的是它建立在 jQuery 物件之上,因此對熟悉 jQuery 的開發者來說毫無門檻。
Backbone 的 [object].extend() 也是同一手法——Model、View、Collection、Router 全部沿用同一個擴充語法:
var Book = Backbone.Model.extend({
initialize: function () { ... },
author: function () { ... },
pubDate: function () { ... }
});
一致性的目的很明確:讓新手感到熟悉。功能不同但語法相同,學習負擔就大幅降低。
平衡指的是組織元素時,不讓某個部分過重而壓過其他部分。在 API 的語境下,我指的具體而言是程式碼的視覺權重與可預測性。
Modernizr 的特性偵測是個典範,它在兩個層面平衡:屬性名對應 HTML5 與 CSS 的既有術語,且每個測試都統一回傳 true 或 false:
Modernizr.geolocation
Modernizr.localstorage
Modernizr.webworkers
Modernizr.canvas
Modernizr.borderradius
Modernizr.boxshadow

知道一個屬性,你就能推測其他所有屬性。這種可預測性本身就是價值:讀寫每個屬性的視覺權重一致,不受開發者個人風格影響。反過來說,如果 Modernizr 突然加入一個 polyfill 用的 API,不僅視覺權重被破壞,整個庫的範圍與用途都會跟著模糊。
另一種達成平衡的方式是借用開發者已熟悉的概念。jQuery 的選擇器再次是例子:
$("#grid") // 依 ID 選取
$("ul.nav > li") // .nav 下所有 li
$("ul li:nth-child(2)") // 每個清單的第二項
映射既有概念,就等於免費繼承了龐大的既有知識。
相稱性衡量的是「元素的大小與數量」。重點不是「API 越小越好」,而是API 的表面積要與它的能力範圍相匹配。
Moment.js 是相稱的正面例子——它的 API 緊湊,與「處理日期」這個明確目的完全對應:
moment().format('dddd');
moment().startOf('hour').fromNow();

而 Underscore 作為通用工具庫,API 數量遠多於 Moment.js,卻同樣是相稱的——因為每個函式都有明確的用途:
_.each(["Todd", "Burke", "Derick"], function (name) { alert(name); });
_.map([1, 2, 3], function (num) { return num * 3; });
_.isNumber("ten"); // false

Kendo UI 的 DataSource 值得一談。乍看之下,「查詢與處理遠端資料」似乎超出了一個 UI 元件庫的本分:
var dataSource = new kendo.data.DataSource({
transport: {
read: {
url: "https://search.twitter.com/search.json",
dataType: "jsonp",
data: { q: "API Design" }
}
},
schema: { data: "results" }
});
但當代網站幾乎都需要動態資料。把資料來源抽象成一個統一元件,讓整個庫能用同一套語意處理遠端資料——這個擴充是相稱的,因為它服務於庫的核心目的。
反例是 jQuery 的 $ 函式。從 DOM 選取、建立元素、包裝既有 DOM、到 $(document).ready,這個入口函式提供了超過十一種不同的多載行為。有些特性彼此關聯不大,卻被硬塞進同一個介面。就整體而言 jQuery 的體量與能力是相稱的;問題出在它把太多功能擠進單一入口。
實務判準很簡單:如果你發現自己正在把不相關的特性硬塞進既有方法,或正在替一個不該存在的函式找理由,那就是該讓它獨立出來的時候。使用者呼叫一個能自我說明的函式,比在一個過載的介面上猜測省時間得多。
強調性是用對比製造焦點。在 API 中,焦點可能是主要方法或核心概念。
jQuery 的鏈式呼叫就是透過語法本身突顯核心物件:
$('ul.first').find('.overdue')
.css('background-color', 'red')
.end()
.find('.due-soon')
.css('background-color', 'yellow');
另一種強調形式是可擴充性——庫的作者承認自己沒提供的那部分,留一個機制讓你自行補上。
jQuery 的 fn 命名空間是最典型的擴充點,數不清的插件由此而生:
(function ($) {
$.fn.kittehfy = function () {
return this.each(function (idx, el) {
var width = el.width, height = el.height;
el.src = "https://placekitten.com/" + 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 的定義就是「提供給他人使用的、隔離功能的介面」。即使你的「他人」只是身邊幾個同事,甚至只有你自己,設計品質的重要性並不會因此降低。
正如 UI 設計的原則能透過觀察好壞例子來學習,API 設計也一樣。把上面四個原則——一致性、平衡、相稱性、強調性——套用到你自己的模組介面上,你會發現程式碼的重用性與可維護性有明顯改善。而找出屬於你自己專案情境的第五、第六條原則,會是更有價值的事。