前段時間組織優化我們的原生模組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 如果傳遞一種熟悉和舒適的感覺,會大幅減輕開發者對新工具的適應性。
命名這點事:既要短,又要自描述,最重要的是保持一致性
##選擇一個你喜歡的措辭,然後持續使用。選擇一種風格,然後保持這種風格。 處理參數要考慮大家如何使用你提供的方法,是否會重複呼叫?為何會重複呼叫?你的 API 如何幫助開發者減少重複的呼叫?“There are only two hard problems in computer science: cache-invalidation and naming things.」
「在電腦科學界只有兩件頭痛的事:快取失效與命名問題」
— Phil Karlton
接收map映射參數,回呼或序列化的屬性名,不僅讓你的 API 更乾淨,而且使用起來更舒服、有效率。
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( 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() http://www.php.cn/) 和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!"); }
備註:可預測性好的 API 具有可預測性,開發者可以根據範例推斷它的用法。 Modernizr's 特性偵測 是一個例子:a) 它使用的屬性名稱完全與HTML5、CSS 概念和API 相符b) 每一個單獨的偵測一致地傳回true 或false 值typeof callback === "function"
在舊的瀏覽器上會有問題,
object會當成個
function。
// 所有这些属性都返回 '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 的專注和小巧非常重要。
軟體開發最艱難的任務之一是寫文檔,實際上每個人都恨寫文檔,怨聲載道的是沒有一個好用的文檔工具。
以下是一些文件自動產生工具:
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
#
以上是JavaScript API 設計原則的具體介紹的詳細內容。更多資訊請關注PHP中文網其他相關文章!