javascript的api設計原則

時間 2019-11-14

原文原文鏈接

摘自：http://www.cnblogs.com/constantince/p/5580003.html

前言

本篇博文來自一次公司內部的前端分享，從多個方面討論了在設計接口時遵循的原則，總共包含了七個大塊。系滷煮本身總結的一些經驗和教訓。本篇博文同時也參考了其餘一些文章，相關地址會在後面貼出來。很難作到詳盡充實，若是有好的建議或者不對的地方，還望不吝賜教斧正。javascript

1、接口的流暢性

好的接口是流暢易懂的，他主要體現以下幾個方面：css

1.簡單html

操做某個元素的css屬性，下面是原生的方法:前端

 
        document.querySelector( 
        '#id' 
        ).style.color =  
        'red' 
        ;

封裝以後java

 
        function  
        a(selector, color) { 
       
        document.querySelector(selector).style.color = color 
       
        } 
       
        a( 
        '#a' 
        ,  
        'red' 
        );

從幾十個字母長長的一行到簡簡單單的一個函數調用，體現了api設計原則之一：簡單易用。node

2.可閱讀性jquery

a('#a', 'red')是個好函數，幫助咱們簡單實用地改變某個元素，但問題來了，若是第一次使用該函數的人來講會比較困惑，a函數是啥函數，沒有人告訴他。開發接口有必要知道一點，大多數人都是懶惰的（包括滷煮本身），從顏色賦值這個函數來講，雖然少寫了代碼，可是增長了單詞字母的個數，使得它再也不好記。每次作這件事情的時候都須要有映射關係： a---->color. 若是是簡單的幾個api卻是無所謂，可是一般一套框架都有幾十甚至上百的api，映射成本增長會使得程序員哥哥崩潰。咱們須要的就是使得接口名稱有意義，下面咱們改寫一下a函數：git

 
        function  
        letSomeElementChangeColor(selector, color) { 
       
        document.querySelectorAll(selector, color).style.color = color; }

letSomeElementChangeColor相對於a來講被賦予了現實語言上的意義，任何人都不須要看說明也能知道它的功能。程序員

3.減小記憶成本github

咱們剛剛的函數太長了，letSomeElementChangeColor雖然減小了映射成本，有了語言上的意義，可是毫無疑問增長了記憶成本。要知道，包括學霸在內，任何人都不喜歡背單詞。不只僅在此處，原生獲取dom的api也一樣有這個問題： document.getElementsByClassName； document.getElementsByName; document.querySelectorAll;這些api給人的感受就是單詞太長了，雖然他給出的意義是很清晰，然而這種作法是創建在犧牲簡易性和簡憶性的基礎上進行的。因而咱們又再次改寫這個以前函數

 
        function  
        setColor(selector, color) { 
       
        xxxxxxxxxxxx 
       
        }

在語言意義不作大的變化前提下，縮減函數名稱。使得它易讀易記易用。

4.可延伸

所謂延伸就是指函數的使用像流水同樣按照書寫的順序執行造成執行鏈條:

 
        document.getElementById( 
        'id' 
        ).style.color =  
        'red' 
        ; 
       
        document.getElementById( 
        'id' 
        ).style.fontSize =  
        '12px' 
        ; 
       
        document.getElementById( 
        'id' 
        ).style.backgourdColor =  
        'pink' 
        ;

若是咱們須要實現像以上有強關聯性的業務時，用咱們以前的以前的方法是再次封裝兩個函數 setFontSize, setbackgroundColor; 而後執行它們 setColor('id', 'red');setFontSiez('id', '12px');setbackgroundColor('id', 'pink'); 顯然，這樣的作法沒有懶出境界來；id元素每次都須要從新獲取，影響性能，失敗；每次都須要添加新的方法，失敗；每次還要調用這些方法，仍是失敗。下面咱們將其改寫爲能夠延伸的函數首先將獲取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 = 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，雖然一個$符號並不表明任何現實意義，但簡單的符號有利於咱們的使用。它體現了以上的多種原則，簡單，易讀，易記，鏈式寫法，多參處理。

nightmare:

 
        document.getElementById( 
        'id' 
        ).style.color =  
        'red' 
        ; 
       
        document.getElementById( 
        'id' 
        ).style.fontSize =  
        '12px' 
        ; 
       
        document.getElementById( 
        'id' 
        ).style.backgourdColor =  
        'pink' 
        ;

dream:

 
        $( 
        'id' 
        ).css({color: 
        'red' 
        , fontSize: 
        '12px' 
        , backgroundColor: 
        'pink' 
        })

2、一致性

1.接口的一致性

相關的接口保持一致的風格，一整套 API 若是傳遞一種熟悉和溫馨的感受，會大大減輕開發者對新工具的適應性。命名這點事：既要短，又要自描述，最重要的是保持一致性「在計算機科學界只有兩件頭疼的事：緩存失效和命名問題」 — Phil Karlton 選擇一個你喜歡的措辭，而後持續使用。選擇一種風格，而後保持這種風格。

Nightmare:

 
        setColor, 
       
        letBackGround 
       
        changefontSize 
       
        makedisplay

dream:

 
        setColor; 
       
        setBackground; 
       
        setFontSize 
       
        set.........

儘可能地保持代碼風格和命名風格，使別人讀你的代碼像是閱讀同一我的寫的文章同樣。

3、參數的處理

1.參數的類型

判斷參數的類型爲你的程序提供穩定的保障

 
        //咱們規定，color接受字符串類型 
       
        function  
        setColor(color) { 
       
        if 
        ( 
        typeof  
        color !==  
        'string' 
        )  
        return 
        ; 
       
        dosomething 
       
        }

2.使用json方式傳參

使用json的方式傳值不少好處，它能夠給參數命名，能夠忽略參數的具體位置，能夠給參數默認值等等好比下面這種糟糕的狀況:

 
        function  
        fn(param1, param2...............paramN)

你必須對應地把每個參數按照順序傳入，不然你的方法就會偏離你預期去執行，正確的方法是下面的作法。

 
        function  
        fn(json) { 
       
        //爲必須的參數設置默認值 
       
        var  
        default  
        = extend({ 
       
        param:  
        'default' 
        , 
       
        param1:  
        'default' 
       
        ...... 
       
        },json) 
       
        }

這段函數代碼，即使你不傳任何參數進來，他也會預期運行。由於在聲明的時候，你會根據具體的業務預先決定參數的缺省值。

4、可擴展性

軟件設計最重要的原則之一：永遠不修改接口，而是去擴展它！可擴展性同時會要求接口的職責單一，多職責的接口很難擴展。舉個栗子：

 
        //須要同時改變某個元素的字體和背景 
       
        // Nightmare: 
       
        function  
        set(selector, color) { 
       
        document.querySelectroAll(selector).style.color = color; 
       
        document.querySelectroAll(selector).style.backgroundColor = color; 
       
        } 
       
        //沒法擴展改函數，若是須要再次改變字體的大小的話，只能修改此函數，在函數後面填加改變字體大小的代碼 
       
        //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; 
       
        }

以上只是簡單的添加顏色，業務複雜而代碼又不是你寫的時候，你就必須去閱讀以前的代碼再修改它，顯然是不符合開放-封閉原則的。修改後的function是返回了元素對象，使得下次須要改變時再次獲得返回值作處理。

2.this的運用

可擴展性還包括對this的以及call和apply方法的靈活運用：

 
        function  
        sayBonjour() { 
       
        alert( 
        this 
        .a) 
       
        } 
       
        obj.a = 1; 
       
        obj.say = sayBonjour; 
       
        obj.say(); 
        //1 
       
        //or 
       
        sayBonjour.call||apply(obj); 
        //1

5、對錯誤的處理

1.預見錯誤

能夠用類型檢測 typeof 或者try...catch。 typeof 會強制檢測對象不拋出錯誤，對於未定義的變量尤爲有用。

2.拋出錯誤

大多數開發者不但願出錯了還須要本身去找帶對應得代碼，最好方式是直接在console中輸出，告訴用戶發生了什麼事情。咱們能夠用到瀏覽器爲咱們提供的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); 
       
        } 
       
        }

6、可預見性

可預見性味程序接口提供健壯性，爲保證你的代碼順利執行，必須爲它考慮到非正常預期的狀況。咱們看下不能夠預見的代碼和可預見的代碼的區別用以前的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 21 and Firefox 15, DOM error 12 
       
        // is thrown if the fragment doesn't begin with < 
       
        if  
        (selector[0] ==  
        '<'  
        && fragmentRE.test(selector)) 
       
        dom = zepto.fragment(selector, RegExp.$1, 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.$1, 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的源碼，能夠看見，做者在預見傳入的參數時作了不少的處理。其實可預見性是爲程序提供了若干的入口，無非是一些邏輯判斷而已。zepto在這裏使用了不少的是非判斷，這樣作的好處固然是代碼比以前更健壯，但同時致使了代碼的冗長，不適合閱讀。總之，可預見性真正須要你作的事多寫一些對位置實物的參數。把外部的檢測改成內部檢測。是的使用的人用起來舒心放心開心。吶！作人嘛最重要的就是海森啦。

7、註釋和文檔的可讀性

一個最好的接口是不須要文檔咱們也會使用它，可是每每接口量一多和業務增長，接口使用起來也會有些費勁。因此接口文檔和註釋是須要認真書寫的。註釋遵循簡單扼要地原則，給多年後的本身也給後來者看：

 
        //註釋接口，爲了演示PPT用 
       
        function  
        commentary() { 
       
        //若是你定義一個沒有字面意義的變量時，最好爲它寫上註釋：a：沒用的變量，能夠刪除 
       
        var  
        a; 
       
        //在關鍵和有歧義的地方寫上註釋，猶如畫龍點睛：路由到hash界面後將全部的數據清空結束函數 
       
        return  
        go.Navigate( 
        'hash' 
        ,  
        function 
        (){ 
       
        data.clear(); 
       
        }); 
       
        }