JavaScript API 設(shè)計(jì)原則
好的 API 設(shè)計(jì)：在自描述的同時(shí)，達(dá)到抽象的目標(biāo)。
設(shè)計(jì)良好的 API ，開發(fā)者可以快速上手，沒必要經(jīng)常抱著手冊(cè)和文檔，也沒必要頻繁光顧技術(shù)支持社區(qū)。
流暢的接口
方法鏈：流暢易讀，更易理解
- //常見的 API 調(diào)用方式：改變一些顏色，添加事件監(jiān)聽
- var elem = document.getElementById("foobar");
- elem.style.background = "red";
- elem.style.color = "green";
- elem.addEventListener('click', function(event) {
- alert("hello world!");
- }, true);
- //（設(shè)想的）方法鏈 API
- DOMHelper.getElementById('foobar')
- .setStyle("background", "red")
- .setStyle("color", "green")
- .addEvent("click", function(event) {
- alert("hello world");
- });
設(shè)置和獲取操作，可以合二為一；方法越多，文檔可能越難寫
- var $elem = jQuery("#foobar");
- //setter
- $elem.setCss("background", "green");
- //getter
- $elem.getCss("color") === "red";
- //getter, setter 合二為一
- $elem.css("background", "green");
- $elem.css("color") === "red";
一致性
相關(guān)的接口保持一致的風(fēng)格，一整套 API 如果傳遞一種熟悉和舒適的感覺，會(huì)大大減輕開發(fā)者對(duì)新工具的適應(yīng)性。
命名這點(diǎn)事：既要短，又要自描述，最重要的是保持一致性
“There are only two hard problems in computer science: cache-invalidation and naming things.”
“在計(jì)算機(jī)科學(xué)界只有兩件頭疼的事：緩存失效和命名問題”
— Phil Karlton
選擇一個(gè)你喜歡的措辭，然后持續(xù)使用。選擇一種風(fēng)格，然后保持這種風(fēng)格。
處理參數(shù)
需要考慮大家如何使用你提供的方法，是否會(huì)重復(fù)調(diào)用？為何會(huì)重復(fù)調(diào)用？你的 API 如何幫助開發(fā)者減少重復(fù)的調(diào)用？
接收map映射參數(shù)，回調(diào)或者序列化的屬性名，不僅讓你的 API 更干凈，而且使用起來更舒服、高效。
jQuery 的 css() 方法可以給 DOM 元素設(shè)置樣式：
- jQuery("#some-selector")
- .css("background", "red")
- .css("color", "white")
- .css("font-weight", "bold")
- .css("padding", 10);
這個(gè)方法可以接受一個(gè) JSON 對(duì)象：
- jQuery("#some-selector").css({
- "background" : "red",
- "color" : "white",
- "font-weight" : "bold",
- "padding" : 10
- });
- //通過傳一個(gè) map 映射綁定事件
- jQuery("#some-selector").on({
- "click" : myClickHandler,
- "keyup" : myKeyupHandler,
- "change" : myChangeHandler
- });
- //為多個(gè)事件綁定同一個(gè)處理函數(shù)
- jQuery("#some-selector").on("click keyup change", myEventHandler);
處理類型
定義方法的時(shí)候，需要決定它可以接收什么樣的參數(shù)。我們不清楚人們?nèi)绾问褂梦覀兊拇a，但可以更有遠(yuǎn)見，考慮支持哪些參數(shù)類型。
- //原來的代碼
- 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行代碼，我們的方法強(qiáng)大到可以接收 Date 對(duì)象，數(shù)字的時(shí)間戳，甚至像 Sat Sep 08 2012 15:34:35 GMT+0200 (CEST) 這樣的字符串
如果你需要確保傳入的參數(shù)類型（字符串，數(shù)字，布爾），可以這樣轉(zhuǎn)換：
- function castaway(some_string, some_integer, some_boolean) {
- some_string += "";
- some_integer += 0; // parseInt(some_integer, 10) 更安全些
- some_boolean = !!some_boolean;
- }
處理 undefined
為了使你的 API 更健壯，需要鑒別是否真正的 undefined 值被傳遞進(jìn)來，可以檢查 arguments 對(duì)象：
- function testUndefined(expecting, someArgument) {
- if (someArgument === undefined) {
- console.log("someArgument 是 undefined");
- }
- if (arguments.length > 1) {
- console.log("然而它實(shí)際是傳進(jìn)來的");
- }
- }
- testUndefined("foo");
- // 結(jié)果: someArgument 是 undefined
- testUndefined("foo", undefined);
- // 結(jié)果: someArgument 是 undefined , 然而它實(shí)際是傳進(jìn)來的
給參數(shù)命名
- event.initMouseEvent(
- "click", true, true, window,
- 123, 101, 202, 101, 202,
- true, false, false, false,
- 1, null);
Event.initMouseEvent 這個(gè)方法簡(jiǎn)直喪心病狂，不看文檔的話，誰能說出每個(gè)參數(shù)是什么意思？
給每個(gè)參數(shù)起個(gè)名字，賦個(gè)默認(rèn)值，可好
- 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 就有 默認(rèn)參數(shù)值 和 rest 參數(shù) 了。
參數(shù)接收 JSON 對(duì)象
與其接收一堆參數(shù)，不如接收一個(gè) JSON 對(duì)象：
- function nightmare(accepts, async, beforeSend, cache, complete, /* 等28個(gè)參數(shù) */) {
- if (accepts === "text") {
- // 準(zhǔn)備接收純文本
- }
- }
- function dream(options) {
- options = options || {};
- if (options.accepts === "text") {
- // 準(zhǔn)備接收純文本
- }
- }
調(diào)用起來也更簡(jiǎn)單了：
- nightmare("text", true, undefined, false, undefined, /* 等28個(gè)參數(shù) */);
- dream({
- accepts: "text",
- async: true,
- cache: false
- });
參數(shù)默認(rèn)值
參數(shù)***有默認(rèn)值，通過 jQuery.extend() http://underscorejs.org/#extend) 和 Protoype 的 Object.extend ，可以覆蓋預(yù)設(shè)的默認(rèn)值。
- 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"
擴(kuò)展性
回調(diào)（callbacks）
通過回調(diào)， API 用戶可以覆蓋你的某一部分代碼。把一些需要自定義的功能開放成可配置的回調(diào)函數(shù)，允許 API 用戶輕松覆蓋你的默認(rèn)代碼。
API 接口一旦接收回調(diào)，確保在文檔中加以說明，并提供代碼示例。
事件（events）
事件接口***見名知意，可以自由選擇事件名字，避免與原生事件 重名。
處理錯(cuò)誤
不是所有的錯(cuò)誤都對(duì)開發(fā)者調(diào)試代碼有用：
- // jQuery 允許這么寫
- $(document.body).on('click', {});
- // 點(diǎn)擊時(shí)報(bào)錯(cuò)
- // TypeError: ((p.event.special[l.origType] || {}).handle || l.handler).apply is not a function
- // in jQuery.min.js on Line 3
這樣的錯(cuò)誤調(diào)試起來很痛苦，不要浪費(fèi)開發(fā)者的時(shí)間，直接告訴他們犯了什么錯(cuò)：
- if (Object.prototype.toString.call(callback) !== '[object Function]') { // 看備注
- throw new TypeError("callback is not a function!");
- }
- 備注：typeof callback === "function" 在老的瀏覽器上會(huì)有問題，object 會(huì)當(dāng)成個(gè) function 。
可預(yù)測(cè)性
好的 API 具有可預(yù)測(cè)性，開發(fā)者可以根據(jù)例子推斷它的用法。
Modernizr’s 特性檢測(cè) 是個(gè)例子：
a) 它使用的屬性名完全與 HTML5、CSS 概念和 API 相匹配
b) 每一個(gè)單獨(dú)的檢測(cè)一致地返回 true 或 false 值
- // 所有這些屬性都返回 'true' 或 'false'
- Modernizr.geolocation
- Modernizr.localstorage
- Modernizr.webworkers
- Modernizr.canvas
- Modernizr.borderradius
- Modernizr.boxshadow
- Modernizr.flexbox
依賴于開發(fā)者已熟悉的概念也可以達(dá)到可預(yù)測(cè)的目的。
jQuery’s 選擇器語法 就是一個(gè)顯著的例子，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
比例協(xié)調(diào)
好的 API 并不一定是小的 API，API 的體積大小要跟它的功能相稱。
比如 Moment.js ，著名的日期解析和格式化的庫，可以稱之為均衡，它的 API 既簡(jiǎn)潔又功能明確。
像 Moment.js 這樣特定功能的庫，確保 API 的專注和小巧非常重要。
編寫 API 文檔
軟件開發(fā)最艱難的任務(wù)之一是寫文檔，實(shí)際上每個(gè)人都恨寫文檔，怨聲載道的是沒有一個(gè)好用的文檔工具。
以下是一些文檔自動(dòng)生成工具：
-
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)
最重要的是：確保文檔跟代碼同步更新。
參考資料：
