這個(gè)應(yīng)該說(shuō)是一個(gè)習(xí)慣吧，不要直接改變?nèi)雲(yún)⒌闹怠＿@個(gè)規(guī)則的初衷是解決函數(shù)副作用問(wèn)題。如果參數(shù)是一個(gè)引用類型的數(shù)據(jù)，如果在函數(shù)內(nèi)修改了參數(shù)，到時(shí)候?qū)?huì)使得原本的數(shù)據(jù)發(fā)生改變，往往會(huì)發(fā)生難以追蹤的問(wèn)題。

參數(shù)的數(shù)量，個(gè)人建議就是，超過(guò)3個(gè)，使用對(duì)象進(jìn)行封裝。因?yàn)槿绻鸄PI參數(shù)越多，那么使用對(duì)于這個(gè)API的記憶成本就越大，易用性也很受影響。

比如下面的例子：

encryptStr: function (str, regArr, type, replacement) {
    var regtext = "",
        Reg = null,
        _type=type||0,
        replaceText = replacement || "*";
    //ecDo.encryptStr("18819322663",[3,5,3],0)
    //result：188*****663
    //repeatStr是在上面定義過(guò)的（字符串循環(huán)復(fù)制），大家注意哦
    if (regArr.length === 3 && type === 0) {
        regtext = "(w{" + regArr[0] + "})w{" + regArr[1] + "}(w{" + regArr[2] + "})"
        Reg = new RegExp(regtext);
        var replaceCount = this.repeatStr(replaceText, regArr[1]);
        return str.replace(Reg, "$1" + replaceCount + "$2")
    }
    //ecDo.encryptStr("asdasdasdaa",[3,5,3],1)
    //result：***asdas***
    else if (regArr.length === 3 && type === 1) {
        regtext = "w{" + regArr[0] + "}(w{" + regArr[1] + "})w{" + regArr[2] + "}"
        Reg = new RegExp(regtext);
        var replaceCount1 = this.repeatStr(replaceText, regArr[0]);
        var replaceCount2 = this.repeatStr(replaceText, regArr[2]);
        return str.replace(Reg, replaceCount1 + "$1" + replaceCount2)
    }
    //ecDo.encryptStr("1asd88465asdwqe3",[5],0)
    //result：*****8465asdwqe3
    else if (regArr.length === 1 && type === 0) {
        regtext = "(^w{" + regArr[0] + "})"
        Reg = new RegExp(regtext);
        var replaceCount = this.repeatStr(replaceText, regArr[0]);
        return str.replace(Reg, replaceCount)
    }
    //ecDo.encryptStr("1asd88465asdwqe3",[5],1,"+")
    //result："1asd88465as+++++"
    else if (regArr.length === 1 && type === 1) {
        regtext = "(w{" + regArr[0] + "}$)"
        Reg = new RegExp(regtext);
        var replaceCount = this.repeatStr(replaceText, regArr[0]);
        return str.replace(Reg, replaceCount)
    }
}

大家可以看上面的注釋，就知道這段代碼的具體作用了，如果想想就找個(gè)參數(shù)，我必須要除了記得4個(gè)參數(shù)的作用，還要記得參數(shù)的順序。

如果使用對(duì)象記錄參數(shù)，用戶只需要記得4個(gè)參數(shù)的作用，不需要記參數(shù)的順序。

encryptStr: function (obj) {
        var _default={
            type:0,
            replacement:"*"
        };
        for(var key in obj){
            _default[key]=obj[key];
        }
},

//調(diào)用方式
ecDo.encryptStr({str:"18819266335",regArr:[5],type:0,replacement:"-"});

這樣還有一個(gè)好處就是，比如像剛才的函數(shù)，type這個(gè)參數(shù)，我想保留默認(rèn)值，偷懶不傳。原來(lái)的方案，就得這樣傳。

ecDo.encryptStr("1asd88465asdwqe3",[5],"","+");

這樣肯定是會(huì)激起不少有代碼潔癖的開(kāi)發(fā)者，比如我。如果使用對(duì)象，就很好避免了。

ecDo.encryptStr({str:"18819266335",regArr:[5],replacement:"-"});

這個(gè)應(yīng)該沒(méi)什么可能，就一個(gè)意思：必填重要的參數(shù)前置，可省略的參數(shù)后置。

比如下面的例子

/格式化處理字符串
//ecDo.formatText("1234asda567asd890")
//result："12,34a,sda,567,asd,890"
//ecDo.formatText("1234asda567asd890",4," ")
//result："1 234a sda5 67as d890"
//ecDo.formatText("1234asda567asd890",4,"-")
//result："1-234a-sda5-67as-d890"
formatText: function (str, size, delimiter) {
    var _size = size || 3, _delimiter = delimiter || ",";
    var regText = "B(?=(w{" + _size + "})+(?!w))";
    var reg = new RegExp(regText, "g");
    return str.replace(reg, _delimiter);
},

調(diào)用大家都看得出來(lái)。如果API這樣設(shè)計(jì)

formatText: function (size, delimiter, str) {
    var _size = size || 3, _delimiter = delimiter || ",";
    var regText = "B(?=(w{" + _size + "})+(?!w))";
    var reg = new RegExp(regText, "g");
    return str.replace(reg, _delimiter);
},

就得這樣調(diào)用，如果這樣寫(xiě)API，被批斗的可能性很大！

ecDo.formatText("","","1234asda567asd890")

比如這個(gè)例子，頁(yè)面有這樣的元素

有一個(gè)類似jQuery的css這個(gè)API的API。

css: function (dom, json) {
    for (var attr in json) {
        dom.style[attr] = json[attr];
    }
}

然后給這些div設(shè)置樣式的時(shí)候，代碼如下

var oDiv1 =document.querySelectorAll(".div1");
var oDiv2=document.querySelector("#div1");
ecDo.css(oDiv2,{"height":"100px","width":"100px","background":"#333"});
ecDo.css(oDiv1,{"height":"100px","width":"100px","background":"#09f"});

當(dāng)運(yùn)行到ecDo.css(oDiv1,{"height":"100px","width":"100px","background":"#09f"});會(huì)提示報(bào)錯(cuò)，原因大家也知道。css這個(gè)API里面，只處理了單個(gè)元素，并沒(méi)有處理元素的集合。

建議的方式是把 css 這個(gè)API改成可批量處理元素集合的。

css: function (dom, json) {
    if (dom.length) {
        for (var i = 0; i < dom.length; i++) {
            for (var attr in json) {
                dom[i].style[attr] = json[attr];
            }
        }
    }
    else {
        for (var attr in json) {
            dom.style[attr] = json[attr];
        }
    }
},    
   

一個(gè)類似jQuery的html這個(gè)API的API-html

之前遇到一個(gè)開(kāi)發(fā)者的處理方式是：獲取元素的innerHTML和設(shè)置元素innerHTML分開(kāi)為兩個(gè)方法-getHtml，setHtml。這樣的問(wèn)題又在于記憶的成本比原生的 innerHTML 還要高。建議的姿勢(shì)就是，獲取和設(shè)置用同一個(gè)API。

html: function (dom) {
    if (arguments.length === 1) {
        return dom.innerHTML;
    } else if (arguments.length === 2) {
        dom.innerHTML = arguments[1];
    }
}

ecDo.html(oDiv);//獲取
ecDo.html(oDiv,"守候");//設(shè)置

可擴(kuò)展性，就是建議遵守開(kāi)放-封閉原則。對(duì)擴(kuò)展開(kāi)放，對(duì)修改關(guān)閉。比如jQuery的$.fn和$.fn.extend()。

說(shuō)一個(gè)簡(jiǎn)單的例子-計(jì)算加薪額度

var addMoney = (function () {
    //定義策略類
    var strategies = {
        A:function(money){
            return money + 2000;
        },
        B:function(money){
            return money + 1000;
        }
    };
    //暴露接口
    return {
        //根據(jù)等級(jí)和現(xiàn)工資，輸入加薪后的工資
        compute:function(lv,money){
            return strategies[lv](money)
        }
    };
})();

//比如：等級(jí)為A，5000+2000
console.log(addMoney.compute("A",5000))//7000
//比如：等級(jí)為B，20000+1000
console.log(addMoney.compute("B",20000))//21000

代碼看著沒(méi)有問(wèn)題，但是如果以后需求要增加C等級(jí)呢？這就不得不修改strategies。在里面增加方法。
如下

var strategies = {
    A:function(money){
        return money + 2000;
    },
    B:function(money){
        return money + 1000;
    },
    C:function(money){
        return money + 500;
    }
};

這樣實(shí)現(xiàn)也簡(jiǎn)單，如果以后要增加S等級(jí)呢？又得改strategies。這里還有一個(gè)問(wèn)題就是，如果增加的C等級(jí)只有在A模塊需要用到，在B模塊不會(huì)出現(xiàn)，那么在B模塊引用addMoney的時(shí)候，又會(huì)把C等級(jí)的計(jì)算方式也引入進(jìn)去，造成不必要的資源浪費(fèi)。
建議的方式是，設(shè)置一個(gè)接口，擴(kuò)展strategies。

var addMoney = (function () {
    //定義策略類
    let strategies = {
        A:function(money){
            return money + 2000;
        },
        B:function(money){
            return money + 1000;
        }
    };
    //暴露接口
    return {
        //根據(jù)等級(jí)和現(xiàn)工資，輸入加薪后的工資
        compute:function(lv,money){
            return strategies[lv](money)
        },
        //擴(kuò)展等級(jí)
        addRule:function(lv,fn){
            strategies[lv]=fn;
        }
    };
})();
//增加C等級(jí)的調(diào)用
addMoney.addRule("C",function(money){
    return money + 500;
});
console.log(addMoney.compute("C",20000))//20500    

函數(shù)的副作用，相信很多人都會(huì)遇到過(guò)，比如在一個(gè)函數(shù)體內(nèi)修改一個(gè)外部作用域的變量，或者全局變量，在函數(shù)體內(nèi)修改引用類型的參數(shù)，這些情況多少都會(huì)遇到過(guò)。

如何避免呢？主要是以下兩個(gè)寫(xiě)代碼習(xí)慣。

1.函數(shù)體內(nèi)可以使用參數(shù)，進(jìn)行操作，但是不能修改。如果修改，用一個(gè)臨時(shí)變量記錄參數(shù)（如果是引用類型，需要用深拷貝記錄）。這樣可以避免直接修改參數(shù)。

2.對(duì)于函數(shù)外的變量，如全局變量。函數(shù)體內(nèi)可以訪問(wèn)，但是不能修改。

3.如果需要給函數(shù)外的變量賦值，不能在函數(shù)體內(nèi)操作，把值返回到外部，在外部進(jìn)行賦值。（感覺(jué)這里有點(diǎn)啰嗦，因?yàn)橘x值了，就是修改了外部變量，就違反了第二點(diǎn)）。

//不好做法
var myName="";
function setName(firstName,lastName){
    myName=firstName+lastName;
}
setName("守","侯");
//推薦做法
var myName="";
function setName(firstName,lastName){
    return firstName+lastName;
}
myName=setName("守","侯");

這個(gè)建議主要就是為了兼顧以前的寫(xiě)法。還是拿上面的那個(gè)例子吧！
原本傳參方式是這樣

encryptStr: function (str, regArr, type, replacement) {};

后來(lái)升級(jí)改成這樣

encryptStr: function (obj){}

這樣問(wèn)題就來(lái)了，一個(gè)項(xiàng)目里面，因?yàn)闅v史的原因難免會(huì)使用這個(gè)API，并且使用了第一種方式傳參。現(xiàn)在API改了，解決的方案有兩個(gè)，要么把整個(gè)項(xiàng)目使用的這個(gè)API的方式，都改成第二種的傳參方式，要么就是對(duì)接口進(jìn)行向下兼容，兼容以前的方案。

encryptStr: function (obj) {
    var _default={
        type:0,
        replacement:"*"
    };
    //如果還是以之前的方式調(diào)用函數(shù)，兼容性判斷
    if(arguments.length>1){
        _default.str=arguments[0];
        _default.regArr=arguments[1];
        _default.type=arguments[2]||0;
        _default.replacement=arguments[3]||"*";
    }
    else{
        for(var key in obj){
            _default[key]=obj[key];
        }
    }
    //下面代碼略
},

如果API已經(jīng)準(zhǔn)備來(lái)一個(gè)大版本的更新，（比如從1.0.0升級(jí)到2.0.0，不是1.0.0升級(jí)到1.0.1，或者1.0.0升級(jí)到1.1.0）。不打算兼容以前的版本了。可以忽略這一步，畢竟兼容性的代碼可能也很多。

這一步可以說(shuō)是API設(shè)計(jì)最高級(jí)的一步，也是最難開(kāi)發(fā)的一步，這就是為什么這篇文章會(huì)帶有‘大道至簡(jiǎn)’的字樣，即使API的實(shí)現(xiàn)很難，但使用起來(lái)簡(jiǎn)單感覺(jué)就是高級(jí)的API。這一步也直接影響API的好用與否。簡(jiǎn)單的API不但是用起來(lái)簡(jiǎn)單，試試可以一看就懂的API。這樣的API更易理解、記憶、調(diào)試和變更使用方式。

原生的API，比如Date，some、map、find等所有數(shù)組遍歷操作函數(shù)，es6提供的Object.assign，Object.keys，Object.values等。

曾經(jīng)的霸主jQuery，現(xiàn)在的王者react，黑馬vue。這些項(xiàng)目讓人拍手稱贊的原因雖然有很多，但也不可否認(rèn)的，那便是它們的API設(shè)計(jì)非常的巧妙。如：jQuery的$,siblings,toogleClass,animate等，react的cloneElement,replaceProps等，vue的nextTick,set等。

jQuery對(duì)于現(xiàn)在而言，雖然是過(guò)時(shí)了，但里面的知識(shí)還是值得學(xué)習(xí)，比如使用的淋漓盡致的 js 寫(xiě)作技巧，設(shè)計(jì)模式，以及 API 設(shè)計(jì)等。

自己寫(xiě)的API，我也是把API寫(xiě)得盡量的簡(jiǎn)單，最高境界就是讓別人掃一眼文檔，就知道記牢了API的使用方式。這個(gè)是我追求的目標(biāo)，只是現(xiàn)在距離還是有點(diǎn)遠(yuǎn)。大家看我encryptStr這個(gè)API就知道（此處尷尬一天）。

在我的眼里，一個(gè)好的API，會(huì)有一個(gè)一看就懂的名字，一個(gè)強(qiáng)大的功能，一個(gè)簡(jiǎn)單的調(diào)用方式。雖然只有三個(gè)條件，但是這三個(gè)條件結(jié)合起來(lái)，可不是那么容易做到的。一個(gè)好的API，無(wú)論是對(duì)自己，對(duì)團(tuán)隊(duì)，對(duì)項(xiàng)目開(kāi)發(fā)都是一個(gè)很好的幫助。

對(duì)于設(shè)計(jì)API的一些個(gè)人建議，就到這里了，如果以后有更好的想法，會(huì)第一時(shí)間分享，和大家交流意見(jiàn)。如果大家有什么想法，歡迎指點(diǎn)迷津。

---------------------------華麗的分割線--------------------------------

想了解更多，關(guān)注我的微信公眾號(hào)-守候書(shū)閣