寫給自己看的程式碼可以將就,寫給團隊甚至社群用的 API 不行。好的接口會讓使用者「猜都不用猜就知道怎麼用」,這背後有規律可循。以下整理七個實用原則。
好的接口具備四個特質。
改一個元素的顏色,原生寫法:
document.querySelectorAll('#id')[0].style.color = 'red';
封裝之後:
a('#a', 'red');
從一行幾十個字元縮到一個函數呼叫,這就是簡易性帶來的價值。
但 a('#a', 'red') 有個問題:第一次看到的人完全不知道 a 是什麼。人天生怕記,用一個字母換來少打字,代價是每次使用都得回想一次對應關係。當一套框架有幾十上百個 API,這種映射成本會累積成災難。
function letSomeElementChangeColor(selector, color) {
document.querySelectorAll(selector)[0].style.color = color;
}
加上語意之後,任何人看名稱就知道用途。
但 letSomeElementChangeColor 又太長了。原生 DOM API 就有這個毛病:getElementsByClassName、getElementsByName、querySelectorAll,語意清晰但難記。折衷之道是在語意不變差的前提下縮短:
function setColor(selector, color) { /* ... */ }
易讀、易記、易用,三者兼顧。
如果每個操作都要重新取一次元素:
setColor('#id', 'red');
setFontSize('#id', '12px');
setBackgroundColor('#id', 'pink');
元素被重複查詢三次,效能差;每加一個屬性就要新增一個方法,擴充性差。改成讓每個方法回傳自己:
function getElement(selector) {
this.style = document.querySelectorAll(selector)[0].style;
}
getElement.prototype.color = function (color) {
this.style.color = color;
return this;
};
getElement.prototype.background = function (bg) {
this.style.backgroundColor = bg;
return this;
};
getElement.prototype.fontSize = function (size) {
this.style.fontSize = size;
return this;
};
var el = new getElement('#id');
el.color('red').background('pink').fontSize('12px');
這正是 jQuery 受歡迎的核心原因:$ 這個符號本身毫無語意,但它足夠短,加上鏈式寫法與一致的命名,整體使用體驗非常順。
相關接口應維持同一種風格。整套 API 若能給人熟悉舒適的感覺,學習曲線會大幅降低。命名既要短又要自描述,最關鍵的是保持一致。
所謂「電腦科學中只有兩件難事:快取失效與命名」,說的就是這件事。選一個用詞然後貫徹,選一種風格然後堅持:
// 不一致
setColor, letBackGround, changefontSize, makedisplay
// 一致
setColor, setBackground, setFontSize, setDisplay
目標是讓人讀你的原始碼像讀同一個人寫的文章。
function setColor(color) {
if (typeof color !== 'string') return;
// ...
}
在入口擋掉不合法的輸入,比讓錯誤在深處爆發要好追蹤得多。
參數一多,位置參數就成了夢魘:
function fn(param1, param2, /* ... */ paramN) { }
呼叫方必須記住順序,錯一個就全錯。改用對象並提供預設值:
function fn(options) {
var default = extend({
param1: 'default',
param2: 'default'
// ...
}, options);
}
好處有三:參數有名字、順序不重要、不傳也能正常運作。缺點是無法靠參數個數判斷必填與否,實務上可再搭配必填檢查。
軟體設計最重要的原則之一:不要修改接口,而是擴展它。這同時要求接口職責單一——身兼多職的函數很難擴展。
// 難以擴展:想再加改字體大小,只能回頭改函數本體
function set(selector, color) {
document.querySelectorAll(selector)[0].style.color = color;
document.querySelectorAll(selector)[0].style.backgroundColor = color;
}
// 易於擴展:回傳元素,讓呼叫方接著做
function set(selector, color) {
var el = document.querySelectorAll(selector)[0];
el.style.color = color;
el.style.backgroundColor = color;
return el;
}
function setAgain(selector, color, px) {
var el = set(selector, color);
el.style.fontSize = px;
return el;
}
回傳值就是擴展點。此外,this 與 call / apply 的靈活運用也是擴展手段:
function sayBonjour() { alert(this.a); }
obj.a = '你好';
obj.say = sayBonjour;
obj.say(); // 作為方法調用
sayBonjour.call(obj); // 顯式綁定上下文
用 typeof 做型別檢測,或用 try...catch 包住可能出錯的區塊。typeof 對未宣告的變數不會拋錯,這點在檢查全域狀態時特別有用。
大多數開發者不希望出錯後還要自己猜哪裡壞了。把訊息直接寫進 console,並保留 try...catch 作為後路:
function error(a) {
if (typeof a !== 'string') {
console.error('param a must be of type string');
}
}
function risky() {
try {
// 可能出錯的程式碼
} catch (ex) {
console.warn(ex);
}
}
錯誤訊息要說清楚「哪個參數、期望什麼、實際拿到什麼」,這比丟一個 TypeError 有用一百倍。
可預見性為接口提供健壯性——你必須為「非預期輸入」預留位置。
// 不可預見:傳了不存在的 id 就炸
function set(selector, color) {
document.getElementById(selector).style.color = color;
}
對照 Zepto 的 init 實作,可以看到成熟庫在入口處做了大量分支處理:空值回傳空集合、HTML 片段走 fragment 解析、函數當作 DOM Ready 回呼、陣列與類數組各自正規化、CSS 選擇器交給 qsa。核心思路是把外部的檢測搬到內部,讓使用者不必自己判斷型別。
不過也要節制:Zepto 那段程式碼分支極多,可讀性因此變差。可預見性的目標是「常見誤用不會炸」,而非「任何輸入都要支援」。把資源投在最可能發生的幾種誤用上即可。
最好的接口是不看文檔也會用,但接口一多就沒這麼理想。註解的原則是扼要,寫給半年後的自己,也寫給接手的人:
// 註解接口,這裡僅為示範
function commentary() {
// 定義沒有字面意義的變數時,說明它是什麼、能不能刪
var a; // 佔位變數,無實際用途
// 在關鍵與易生歧義處落筆
return go.Navigate('hash', function () {
data.clear(); // 路由到 hash 頁面前清空所有資料
});
}
文檔方面推薦 Markdown,GitHub 原生支援、語法簡單、程式碼高亮現成可用,是撰寫 API 文件最省力的選擇。

這七條原則其實指向同一個目標:降低使用者的認知負擔。命名一致、參數單純、回傳值留出擴展點、入口做好防禦、錯誤訊息講人話——每一條都在替呼叫方省事。API 設計沒有捷徑,但這些原則能讓你少走很多彎路。