API 是庫與使用者的契約。優秀的 API 設計如同優秀的 UI 設計:直觀、一致、可預測、容錯。本文從藝術設計四大原則——和諧一致、平衡、對稱、重點突出——延伸出 JavaScript API 設計實務準則,並以 jQuery、Kendo UI、Backbone、Modernizr 等知名庫為例實證分析。
相似功能應有相似的 API 形式、命名、參數順序、回傳值。降低認知負荷,讓開發者「學一通、處處通」。
// TreeView
$('#tree').kendoTreeView({ dataSource: [...] });
// PanelBar
$('#panel').kendoPanelBar({ dataSource: [...] });
// Grid
$('#grid').kendoGrid({ dataSource: [...], columns: [...] });
// 所有元件:$(selector).kendoWidgetName(config)
統一前綴 `kendo` + 元件名,配置物件結構高度一致,熟悉 jQuery 的開發者零學習成本上手。
const Book = Backbone.Model.extend({ /* ... */ });
const Library = Backbone.Collection.extend({ model: Book });
const BookView = Backbone.View.extend({ /* ... */ });
const Router = Backbone.Router.extend({ routes: {...} });
單一 `.extend()` 方法支援 Model/Collection/View/Router 所有擴展,極致協調。
API 各部分視覺權重均衡、行為可預測、功能互補。避免「上帝物件」或「貧血介面」。
// 所有屬性:布林值、命名對應 HTML5/CSS 標準名
Modernizr.flexbox; // true/false
Modernizr.webgl; // true/false
Modernizr.cssgrid; // true/false
Modernizr.fetch; // true/false
// 統一回傳型別、命名規範、語義清晰
平衡體現於:
// success: function(data, textStatus, jqXHR) {}
// error: function(jqXHR, textStatus, errorThrown) {} // 參數順序不同!
// 後來統一為 jqXHR 物件包裝
對稱操作應成對出現:`get`/`set`、`on`/`off`、`add`/`remove`、`show`/`hide`、`enable`/`disable`。缺一不可,否則產生「API 缺口」。
$(el).on('click', handler); // 綁定
$(el).off('click', handler); // 解除
$(el).one('click', handler); // 一次性綁定(對稱補充)
localStorage.setItem(key, value);
localStorage.getItem(key);
localStorage.removeItem(key);
localStorage.clear(); // 批次清除對稱補充
核心功能 API 應最容易發現、最簡單使用、文檔最豐富。次要/進階功能不應干擾主流程。
// 核心:極簡調用
axios.get('/users/1');
axios.post('/users', {name: 'John'});
// 進階:配置物件、攔截器、取消令牌、適配器
axios({method: 'get', url: '/users/1', timeout: 5000, headers: {...}});
API 設計不是主觀偏好,而是可被原則指導的工程決策。一致性降低學習曲線,平衡保證預期可靠,對稱消除認知缺口,重點突出引導核心價值。以此四原則審視、重構、設計你的 JavaScript API,將創造出開發者喜愛、傳播廣泛、經得起時間考驗的優雅介面。