歡迎光臨
每天分享高質量文章

JavaScript API 設計原則

作者:伯樂在線 – 塗鴉碼龍

網址:http://web.jobbole.com/83378/

前段時間組織優化我們的原生模塊 API(iOS、Android 模塊封裝成 JavaScript 接口),於是學習了幾篇 JavaScript API 設計的文章,儘管是舊文,但受益匪淺,這裡記錄一下。

好的 API 設計:在自描述的同時,達到抽象的標的。

設計良好的 API ,開發者可以快速上手,沒必要經常抱著手冊和文件,也沒必要頻繁光顧技術支持社區。

流暢的接口

方法鏈:流暢易讀,更易理解

// 常見的 API 呼叫方式:改變一些顏色,添加事件監聽

var elem = document.getElementById(“foobar”);

elem.style.background = “red”;

elem.style.color = “green”;

elem.addEventListener(‘click’, function(event) {

alert(“hello world!”);

}, true);

//(設想的)方法鏈 API

DOMHelper.getElementById(‘foobar’)

.setStyle(“background”, “red”)

.setStyle(“color”, “green”)

.addEvent(“click”, function(event) {

alert(“hello world”);

});

設置和獲取操作,可以合二為一;方法越多,文件可能越難寫

var $elem = jQuery(“#foobar”);

//setter

$elem.setCss(“background”, “green”);

//getter

$elem.getCss(“color”) === “red”;

//getter, setter 合二為一

$elem.css(“background”, “green”);

$elem.css(“color”) === “red”;

一致性

相關的接口保持一致的風格,一整套 API 如果傳遞一種熟悉和舒適的感覺,會大大減輕開發者對新工具的適應性。

命名這點事:既要短,又要自描述,最重要的是保持一致性

“There are only two hard problems in computer science: cache-invalidation and naming things.”

“在計算機科學界只有兩件頭疼的事:快取失效和命名問題”

— Phil Karlton

選擇一個你喜歡的措辭,然後持續使用。選擇一種風格,然後保持這種風格。

處理引數

需要考慮大家如何使用你提供的方法,是否會重覆呼叫?為何會重覆呼叫?你的 API 如何幫助開發者減少重覆的呼叫?

接收 map 映射引數,回呼或者序列化的屬性名,不僅讓你的 API 更乾凈,而且使用起來更舒服、高效。

jQuery 的 css() 方法可以給 DOM 元素設置樣式:

jQuery(“#some-selector”)

.css(“background”, “red”)

.css(“color”, “white”)

.css(“font-weight”, “bold”)

.css(“padding”, 10);

這個方法可以接受一個 JSON 物件:

jQuery(“#some-selector”).css({

“background” : “red”,

“color” : “white”,

“font-weight” : “bold”,

“padding” : 10

});

// 通過傳一個 map 映射系結事件

jQuery(“#some-selector”).on({

“click” : myClickHandler,

“keyup” : myKeyupHandler,

“change” : myChangeHandler

});

// 為多個事件系結同一個處理函式

jQuery(“#some-selector”).on(“click keyup change”, myEventHandler);

處理型別

定義方法的時候,需要決定它可以接收什麼樣的引數。我們不清楚人們如何使用我們的代碼,但可以更有遠見,考慮支持哪些引數型別。

// 原來的代碼

DateInterval.prototype.days = function(start, end) {

return Math.floor((end – start) / 86400000);

};

// 修改後的代碼

DateInterval.prototype.days = function(start, end) {

if (!(start instanceof Date)) {

start = new Date(start);

}

if (!(end instanceof Date)) {

end = new Date(end);

}

return Math.floor((end.getTime() – start.getTime()) / 86400000);

};

加了短短的 6 行代碼,我們的方法強大到可以接收 Date 物件,數字的時間戳,甚至像 Sat Sep 08 2012 15:34:35 GMT+0200 (CEST) 這樣的字串。

如果你需要確保傳入的引數型別(字串,數字,布爾),可以這樣轉換:

function castaway(some_string, some_integer, some_boolean) {

some_string += “”;

some_integer += 0; // parseInt(some_integer, 10) 更安全些

some_boolean = !!some_boolean;

}

處理 undefined

為了使你的 API 更健壯,需要鑒別是否真正的 undefined 值被傳遞進來,可以檢查 arguments 物件:

function testUndefined(expecting, someArgument) {

if (someArgument === undefined) {

console.log(“someArgument 是 undefined”);

}

if (arguments.length > 1) {

console.log(” 然而它實際是傳進來的 “);

}

}

testUndefined(“foo”);

// 結果: someArgument 是 undefined

testUndefined(“foo”, undefined);

// 結果: someArgument 是 undefined , 然而它實際是傳進來的

給引數命名

event.initMouseEvent(

“click”, true, true, window,

123, 101, 202, 101, 202,

true, false, false, false,

1, null);

Event.initMouseEvent 這個方法簡直喪心病狂,不看文件的話,誰能說出每個引數是什麼意思?

給每個引數起個名字,賦個預設值,可好

event.initMouseEvent(

type=”click”,

canBubble=true,

cancelable=true,

view=window,

detail=123,

screenX=101,

screenY=202,

clientX=101,

clientY=202,

ctrlKey=true,

altKey=false,

shiftKey=false,

metaKey=false,

button=1,

relatedTarget=null);

ES6, 或者 Harmony 就有 預設引數值 和 rest 引數 了。

引數接收 JSON 物件

與其接收一堆引數,不如接收一個 JSON 物件:

function nightmare(accepts, async, beforeSend, cache, complete, /* 等 28 個引數 */) {

if (accepts === “text”) {

// 準備接收純文本

}

}

function dream(options) {

options = options || {};

if (options.accepts === “text”) {

// 準備接收純文本

}

}

呼叫起來也更簡單了:

nightmare(“text”, true, undefined, false, undefined, /* 等 28 個引數 */);

dream({

accepts: “text”,

async: true,

cache: false

});

引數預設值

引數最好有預設值,通過 jQuery.extend() , _.extend() 和 Protoype 的 Object.extend,可以改寫預設的預設值。

var default_options = {

accepts: “text”,

async: true,

beforeSend: null,

cache: false,

complete: null,

// …

};

function dream(options) {

var o = jQuery.extend({}, default_options, options || {});

console.log(o.accepts);

}

dream({ async: false });

// prints: “text”

擴展性

回呼(callbacks)

通過回呼, API 用戶可以改寫你的某一部分代碼。把一些需要自定義的功能開放成可配置的回呼函式,允許 API 用戶輕鬆改寫你的預設代碼。

API 接口一旦接收回呼,確保在文件中加以說明,並提供代碼示例。

事件(events)

事件接口最好見名知意,可以自由選擇事件名字,避免與原生事件 重名。

處理錯誤

不是所有的錯誤都對開發者除錯代碼有用:

// jQuery 允許這麼寫

$(document.body).on(‘click’, {});

// 點擊時報錯

// TypeError: ((p.event.special[l.origType] || {}).handle || l.handler).apply is not a function

// in jQuery.min.js on Line 3

這樣的錯誤除錯起來很痛苦,不要浪費開發者的時間,直接告訴他們犯了什麼錯:

if (Object.prototype.toString.call(callback) !== ‘[object Function]’) { // 看備註

throw new TypeError(“callback is not a function!”);

}

備註:typeof callback === “function” 在老的瀏覽器上會有問題,object會當成個function 。

可預測性

好的 API 具有可預測性,開發者可以根據例子推斷它的用法。

Modernizr’s 特性檢測 是個例子:

a) 它使用的屬性名完全與 HTML5、CSS 概念和 API 相匹配

b) 每一個單獨的檢測一致地傳回 true 或 false 值

// 所有這些屬性都傳回 ‘true’ 或 ‘false’

Modernizr.geolocation

Modernizr.localstorage

Modernizr.webworkers

Modernizr.canvas

Modernizr.borderradius

Modernizr.boxshadow

Modernizr.flexbox

依賴於開發者已熟悉的概念也可以達到可預測的目的。

jQuery’s 選擇器語法 就是一個顯著的例子,CSS1-CSS3 的選擇器可直接用於它的 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

比例協調

好的 API 並不一定是小的 API,API 的體積大小要跟它的功能相稱。

比如 Moment.js,著名的日期解析和格式化的庫,可以稱之為均衡,它的 API 既簡潔又功能明確。

像 Moment.js 這樣特定功能的庫,確保 API 的專註和小巧非常重要。

編寫 API 文件

軟體開發最艱難的任務之一是寫文件,實際上每個人都恨寫文件,怨聲載道的是沒有一個好用的文件工具。

以下是一些文件自動生成工具:

  • YUIDoc (requires Node.js, npm)

  • JsDoc Toolkit (requires Node.js, npm)

  • Markdox (requires Node.js, npm)

  • Dox (requires Node.js, npm)

  • Docco (requires Node.js, Python, CoffeeScript)

  • JSDuck (reqires Ruby, gem)

  • JSDoc 3 (requires Java)

最重要的是:確保文件跟代碼同步更新。

參考資料:

  • 好的 API 設計

  • Designing Better JavaScript APIs

  • Secrets of Awesome JavaScript API Design

赞(0)

分享創造快樂