深入淺析JavaScript的API設計原則
一、接口的流暢性
好的接口是流暢易懂的,他主要體現(xiàn)如下幾個方面:
1.簡單
操作某個元素的css屬性,下面是原生的方法:
document.querySelectorAll('#id').style.color = 'red';
封裝之后
function a(selector, color) { document.querySelectorAll(selector)[].style.color = color } a('#a', 'red');
從幾十個字母長長的一行到簡簡單單的一個函數(shù)調(diào)用,體現(xiàn)了api簡單易用
2.可閱讀性
a('#a', 'red')是個好函數(shù),幫助我們簡單實用地改變某個元素,但問題來了,如果第一次使用改函數(shù)的人來說會比較困惑,a函數(shù)是啥函數(shù),沒有人告訴他。開發(fā)接口有必要知道一點,人都是懶惰的,從顏色賦值這個函數(shù)來說,雖然少寫了代碼,但是增加了記憶成本。每次做這件事情的時候都需要有映射關系。 a---->color. 如果是簡單的幾個無所謂,但是通常一套框架都有幾十甚至上百的api,映射成本增加會使得程序員哥哥崩潰。 我們需要的就是使得接口有意義,下面我們改寫一下a函數(shù):
function letSomeElementChangeColor(selector, color) { document.querySelectorAll(selector, color); }
letSomeElementChangeColor相對于a來說被賦予了語言意義,任何人都會知道它的意義
3.減少記憶成本
我們剛剛的函數(shù)也是這樣的它太長了letSomeElementChangeColor雖然減少了映射成本,但是增加了記憶成本。要知道,包括學霸在內(nèi),任何人都不喜歡被單詞。原生獲取dom的api也同樣有這個問題 document.getElementsByClassName; document.getElementsByName; document.querySelectorAll;這些api給人的感覺就是單詞太長了,雖然他給出的意義是很清晰,然而這種做法是建立在犧牲簡易性的基礎上進行的。于是我們又再次改寫這個之前函數(shù)
function setColor(selector, color) { xxxxxxxxxxxx }
在意義不做大的變化前提下,縮減函數(shù)名稱。使得它易讀易記易用;
4.可延伸
所謂延伸就是指函數(shù)的使用像流水一樣按照書寫的順序執(zhí)行形成執(zhí)行鏈條:
document.getElementById('id').style.color = 'red'; document.getElementById('id').style.fontSize = 'px'; document.getElementById('id').style.backgourdColor = 'pink';
用我們之前的之前的方法是再次封裝兩個函數(shù) setFontSize, setbackgroundColor; 然后執(zhí)行它們 setColor('id', 'red');setFontSiez('id', '12px'); setbackgroundColor('id', 'pink'); 顯然,這樣的做法沒有懶出境界來;id元素每次都需要重新獲取,影響性能,失??;每次都需要添加新的方法 失敗 每次還要調(diào)用這些方法,還是失敗。下面我們將其改寫為可以延伸的函數(shù) 首先將獲取id方法封裝成對象,然后再對象的每個方法中返回這個對象:
function getElement(selector) { this.style = document.querySelecotrAll(selector).style; } getElement.prototype.color = function(color) { this.style.color = color; return this; } getElement.prototype.background = function(bg) { this.style.backgroundColor = color; return this; } getElement.prototype.fontSize = function(size) { this.style.fontSize = size; return this; } //調(diào)用 var el = new getElement('#id') el.color('red').background('pink').fontSize('px');
簡單、流暢、易讀后面我們會在參數(shù)里面講到如何繼續(xù)優(yōu)化。所以,大家都比較喜歡用jquery的api,雖然一個$符號并不代表任何現(xiàn)實意義,但簡單的符號有利于我們的使用。它體現(xiàn)了以上的多種原則,簡單,易讀,易記,鏈式寫法,多參處理。
nightware:
document.getElementById('id').style.color = 'red'; document.getElementById('id').style.fontSize = 'px'; document.getElementById('id').style.backgourdColor = 'pink';
dream:
$('id').css({color:'red', fontSize:'12px', backgroundColor:'pink'})
二、一致性
1.接口的一致性
相關的接口保持一致的風格,一整套 API 如果傳遞一種熟悉和舒適的感覺,會大大減輕開發(fā)者對新工具的適應性。 命名這點事:既要短,又要自描述,最重要的是保持一致性 “在計算機科學界只有兩件頭疼的事:緩存失效和命名問題” — Phil Karlton 選擇一個你喜歡的措辭,然后持續(xù)使用。選擇一種風格,然后保持這種風格。
Nightware:
setColor,
letBackGround
changefontSize
makedisplay
dream:
setColor;
setBackground;
setFontSize
set.........
盡量地保持代碼風格和命名風格,使人讀你的代碼像是閱讀同一個人寫的文章一樣。
三、參數(shù)的處理
1.參數(shù)的類型
判斷參數(shù)的類型為你的程序提供穩(wěn)定的保障
//我們規(guī)定,color接受字符串類型 function setColor(color) { if(typeof color !== 'string') return; dosomething }
2.使用json方式傳參
使用json的方式傳值很多好處,它可以給參數(shù)命名,可以忽略參數(shù)的具體位置,可以給參數(shù)默認值等等 比如下面這種糟糕的情況:
function fn(param1, param2...............paramN)
你必須對應地把每一個參數(shù)按照順序傳入,否則你的方法就會偏離你預期去執(zhí)行,正確的方法是下面的做法。
function fn(json) { //為必須的參數(shù)設置默認值 var default = extend({ param: 'default', param: 'default' ...... },json) }
這段函數(shù)代碼,即便你不傳任何參數(shù)進來,他也會預期運行。因為在聲明的時候,你會根據(jù)具體的業(yè)務決定參數(shù)的缺省值。
四、可擴展性
軟件設計最重要的原則之一:永遠不修改接口,指擴展它!可擴展性同時會要求接口的職責單一,多職責的接口很難擴展。 舉個栗子:
//需要同時改變某個元素的字體和背景 // Nightware: function set(selector, color) { document.querySelectroAll(selector).style.color = color; document.querySelectroAll(selector).style.backgroundColor = color; } //無法擴展改函數(shù),如果需要再次改變字體的大小的話,只能修改此函數(shù),在函數(shù)后面填加改變字體大小的代碼 //Dream function set(selector, color) { var el = document.querySelectroAll(selector); 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; }
以上只是簡單的添加顏色,業(yè)務復雜而代碼又不是你寫的時候,你就必須去閱讀之前的代碼再修改它,顯然是不符合開放-封閉原則的。修改后的function是返回了元素對象,使得下次需要改變時再次得到返回值做處理。
2.this的運用
可擴展性還包括對this的以及call和apply方法的靈活運用:
function sayBonjour() { alert(this.a) } obj.a = ; obj.say = sayBonjour; obj.say();// //or sayBonjour.call||apply(obj);//
五、對錯誤的處理
1.預見錯誤
可以用 類型檢測 typeof 或者try...catch。 typeof 會強制檢測對象不拋出錯誤,對于未定義的變量尤其有用。
2.拋出錯誤
大多數(shù)開發(fā)者不希望出錯了還需要自己去找?guī)么a,最好方式是直接在console中輸出,告訴用戶發(fā)生了什么事情。我們可以用到瀏覽器的輸出api:console.log/warn/error。你還可以為自己的程序留些后路: try...catch。
function error (a) { if(typeof a !== 'string') { console.error('param a must be type of string') } } function error() { try { // some code excucete here maybe throw wrong }catch(ex) { console.wran(ex); } }
六、可預見性
可預見性味程序接口提供健壯性,為保證你的代碼順利執(zhí)行,必須為它考慮到非正常預期的情況。我們看下不可以預見的代碼和可預見的代碼的區(qū)別用之前的setColor
//nighware function set(selector, color) { document.getElementById(selector).style.color = color; } //dream zepto.init = function(selector, context) { var dom // If nothing given, return an empty Zepto collection if (!selector) return zepto.Z() // Optimize for string selectors else if (typeof selector == 'string') { selector = selector.trim() // If it's a html fragment, create nodes from it // Note: In both Chrome and Firefox , DOM error // is thrown if the fragment doesn't begin with < if (selector[] == '<' && fragmentRE.test(selector)) dom = zepto.fragment(selector, RegExp.$, context), selector = null // If there's a context, create a collection on that context first, and select // nodes from there else if (context !== undefined) return $(context).find(selector) // If it's a CSS selector, use it to select nodes. else dom = zepto.qsa(document, selector) } // If a function is given, call it when the DOM is ready else if (isFunction(selector)) return $(document).ready(selector) // If a Zepto collection is given, just return it else if (zepto.isZ(selector)) return selector else { // normalize array if an array of nodes is given if (isArray(selector)) dom = compact(selector) // Wrap DOM nodes. else if (isObject(selector)) dom = [selector], selector = null // If it's a html fragment, create nodes from it else if (fragmentRE.test(selector)) dom = zepto.fragment(selector.trim(), RegExp.$, context), selector = null // If there's a context, create a collection on that context first, and select // nodes from there else if (context !== undefined) return $(context).find(selector) // And last but no least, if it's a CSS selector, use it to select nodes. else dom = zepto.qsa(document, selector) } // create a new Zepto collection from the nodes found return zepto.Z(dom, selector) }
以上是zepto的源碼,可以看見,作者在預見傳入的參數(shù)時做了很多的處理。其實可預見性是為程序提供了若干的入口,無非是一些邏輯判斷而已。zepto在這里使用了很多的是非判斷,同時導致了代碼的冗長,不適合閱讀??傊?,可預見性真正需要你做的事多寫一些對位置實物的參數(shù)。把外部的檢測改為內(nèi)部檢測。是的使用的人用起來舒心放心開心。吶!做人嘛最重要的就是海森啦。
七、注釋和文檔的可讀性
一個最好的接口是不需要文檔我們也會使用它,但是往往接口量一多和業(yè)務增加,接口使用起來也會有些費勁。所以接口文檔和注釋是需要認真書寫的。注釋遵循簡單扼要地原則,給多年后的自己也給后來者看:
//注釋接口,為了演示PPT用 function commentary() { //如果你定義一個沒有字面意義的變量時,最好為它寫上注釋:a:沒用的變量,可以刪除 var a; //在關鍵和有歧義的地方寫上注釋,猶如畫龍點睛:路由到hash界面后將所有的數(shù)據(jù)清空結(jié)束函數(shù) return go.Navigate('hash', function(){ data.clear(); }); }
最后
推薦markdown語法書寫API文檔,github御用文檔編寫語法。簡單、快速,代碼高亮、話不多說上圖
以上所述是小編給大家介紹的JavaScript的API設計原則的全部敘述,希望對大家有所幫助,如果大家有任何疑問請給我留言,小編會及時回復大家的。在此也非常感謝大家對腳本之家網(wǎng)站的支持!
- 深入理解JavaScript系列(6):S.O.L.I.D五大原則之單一職責SRP
- JavaScript最少知識原則介紹與體現(xiàn)
- JavaScript面向?qū)ο笾叽蠡驹瓌t實例詳解
- JavaScript的數(shù)據(jù)類型轉(zhuǎn)換原則(干貨)
- 深入理解JavaScript系列(22):S.O.L.I.D五大原則之依賴倒置原則DIP詳解
- 深入理解JavaScript系列(21):S.O.L.I.D五大原則之接口隔離原則ISP詳解
- 深入理解JavaScript系列(8) S.O.L.I.D五大原則之里氏替換原則LSP
- 深入理解JavaScript系列(7) S.O.L.I.D五大原則之開閉原則OCP
- JavaScript單一職責原則深入分析
相關文章
微信小程序使用map組件實現(xiàn)獲取定位城市天氣或者指定城市天氣數(shù)據(jù)功能
這篇文章主要介紹了微信小程序使用map組件實現(xiàn)獲取定位城市天氣或者指定城市天氣數(shù)據(jù)功能,涉及微信小程序map組件結(jié)合微信API獲取天氣信息相關操作技巧,需要的朋友可以參考下2019-01-01javascript創(chuàng)建createXmlHttpRequest對象示例代碼
這篇文章主要介紹了javascript創(chuàng)建createXmlHttpRequest對象的示例代碼。需要的朋友可以過來參考下,希望對大家有所幫助2014-02-02解析John Resig Simple JavaScript Inheritance代碼
上網(wǎng)也查了一下對些的理解說的都不是很清楚. 在翻閱的同時找到了一篇 分析這篇文章的文章 哈哈 分析的很詳細. (Join Resig 大師的 "Simple Inheritance" 使用了很多有意思的技巧) 如果你有時間, 并對此感興趣不訪好好看看. 我相信多少會有所收益的.2012-12-12JavaScript DSL 流暢接口(使用鏈式調(diào)用)實例
這篇文章主要介紹了JavaScript DSL 流暢接口(使用鏈式調(diào)用)實例,本文講解了DSL 流暢接口、DSL 表達式生成器等內(nèi)容,需要的朋友可以參考下2015-03-03js使用數(shù)組判斷提交數(shù)據(jù)是否存在相同數(shù)據(jù)
判斷提交數(shù)據(jù)是否存在相同數(shù)據(jù),在本文將為大家介紹使用數(shù)組做到這一點,感興趣的朋友可以參考下2013-11-11