最近搞了兩天的web service測(cè)試，對(duì)于這些web service接口感覺(jué)實(shí)在是XX，加上經(jīng)常在網(wǎng)上看見(jiàn)兄弟們討論web service相關(guān)的一些問(wèn)題，覺(jué)得十分有必要對(duì)什么是比較好的web service接口有個(gè)統(tǒng)一的認(rèn)識(shí)。今天這篇B文就來(lái)說(shuō)說(shuō)我眼中定義良好的web service接口是個(gè)什么鳥(niǎo)樣子。

接口是自說(shuō)明的。也 就是說(shuō)，接口的名字、參數(shù)和返回值在一看之下就知道這接口大概是干什么用的。當(dāng)然接口描述文檔肯定是必須的，但這些描述文檔的質(zhì)量誰(shuí)知道怎么樣呢，誰(shuí)有空 天天翻著文檔寫東西呢，又有誰(shuí)會(huì)背下來(lái)呢？所以讓人眼前一亮的接口命名絕對(duì)值得，這也是所有代碼書會(huì)告訴你應(yīng)該遵守的一條。想想看見(jiàn)個(gè)叫add的方法卻做 multiply的悲慘生活吧，即使文檔明確說(shuō)了add是做multiply，是不是每次見(jiàn)了也都想罵人呢。

服務(wù)接口粒度要合適。web service服務(wù)接口粒度太小了，那純粹是不考慮xml解析性能了。一般新手容易犯這毛病，簡(jiǎn)單的把類的方法暴露出來(lái)做服務(wù)接口，這樣其實(shí)是把原來(lái)在 locale的調(diào)用放到了remote，除此之外幾乎沒(méi)有任何好處。粒度太大，會(huì)給使用著帶來(lái)很多麻煩，因?yàn)樵趙eb service中，粒度很大的服務(wù)一般都需要很多參數(shù)來(lái)映射該服務(wù)各種各樣的情況。

接口參數(shù)要盡量簡(jiǎn)單。那 位說(shuō)了，web service是服務(wù)啊大哥，你讓我就一個(gè)參數(shù)，怎么提供服務(wù)啊，你以為服務(wù)都跟查詢天氣預(yù)報(bào)一樣簡(jiǎn)單啊，給個(gè)城市名子，回頭告訴你天氣情況。說(shuō)實(shí)話，要 用一個(gè)接口提供一個(gè)完善的服務(wù)確實(shí)不容易。有個(gè)名詞叫服務(wù)的粒度，這個(gè)粒度確實(shí)不好掌握，服務(wù)名定了之后要想讓這個(gè)服務(wù)更豐滿只能靠更多的參數(shù)來(lái)搞定。對(duì) 于需要數(shù)十個(gè)參數(shù)的服務(wù)接口來(lái)說(shuō)，首先要想的應(yīng)該是，我KAO，這個(gè)服務(wù)定義的有問(wèn)題吧？讓我們?cè)賮?lái)分析分析它，給它一個(gè)合適定位，給他瘦身。要是你非不 信邪發(fā)布個(gè)有三十多個(gè)參數(shù)的接口，嚴(yán)重建議你在發(fā)布接口之前自己拿來(lái)測(cè)試一下先。

接口參數(shù)不應(yīng)該增加客戶端和服務(wù)端的耦合性。兄 弟們肯定在很多地方看見(jiàn)過(guò)，不應(yīng)該在方法參數(shù)上增加額外的耦合性這條原則。這個(gè)在web service中同樣適用，甚至可以著重強(qiáng)調(diào)一下這一條，因?yàn)樵趙eb service中把字符串進(jìn)行特別處理實(shí)在太容易了。比如作為參數(shù)的字符串對(duì)應(yīng)特殊的業(yè)務(wù)規(guī)則，這么做會(huì)導(dǎo)致增加額外的說(shuō)明文檔，增加client和 server編程的負(fù)擔(dān)。又或者傳入sql語(yǔ)句，嗯，這個(gè)作為反面教材到處都在罵，我就簡(jiǎn)單點(diǎn)個(gè)名就好了。

要提供對(duì)接口參數(shù)和返回值的校驗(yàn)。嚴(yán) 格的來(lái)說(shuō)，對(duì)接口參數(shù)和返回值的驗(yàn)證也應(yīng)該算是web service接口聲明的一部分。尤其是對(duì)document/literal的情況，要提供相應(yīng)的schema以供校驗(yàn)之用（dtd應(yīng)該處在逐漸淘汰中 了）。增加對(duì)參數(shù)和返回值的校驗(yàn)，有利于減少調(diào)用者的疑惑，系統(tǒng)接受什么樣的參數(shù)，返回值什么格式都一目了然。但是這需要一個(gè)很好的權(quán)衡，否則調(diào)用者會(huì)覺(jué) 得你暴露的方法很難用，因?yàn)橄拗铺嗔恕１容^理想的系統(tǒng)應(yīng)該是寬進(jìn)嚴(yán)出的，目標(biāo)用戶越多越應(yīng)該注意這一點(diǎn)。要在寬進(jìn)嚴(yán)出和全面校驗(yàn)之間做好平衡確實(shí)挺難的。我的建議是，對(duì)要暴露的接口自己做測(cè)試，在測(cè)試的過(guò)程中體會(huì)這個(gè)度。一般來(lái)說(shuō)如果自己感覺(jué)都不爽，那別人是絕對(duì)不會(huì)用的。

接口的返回值應(yīng)該是簡(jiǎn)單的語(yǔ)言無(wú)關(guān)的。 看 見(jiàn)過(guò)很多人問(wèn)如何返回ResultSet/DataSet之類的復(fù)雜類型，尤其是玩.net的人，也許是vs.net對(duì)封裝DataSet提供了過(guò)于完美 的支持吧。但對(duì)于XML來(lái)說(shuō)，把任何復(fù)雜對(duì)象映射到xml文檔都是困難的。就好比把三維向二維投影一樣，復(fù)雜性增加了可不是一點(diǎn)半點(diǎn)。在XML中說(shuō)到底所 有的類型都是字符串，要想表達(dá)其他類型，就要加額外的說(shuō)明。可以看看rpc/encode方式WSDL文檔的complexType部分，體會(huì)下心情。

謹(jǐn)慎的拋出異常。可 以把web service中的異常（SOAP FAULT）對(duì)比Java的runtime exception。任何異常都應(yīng)該對(duì)應(yīng)系統(tǒng)意外，而不是業(yè)務(wù)例外。對(duì)于這點(diǎn)其實(shí)要具體情況具體分析。簡(jiǎn)單的可以歸納為三種情況。第一種情況是接口返回值 是簡(jiǎn)單類型，比如boolean型，就true和false兩種情況，不拋出異常怎么辦？選擇有兩種，一是拋出異常（廢話！臺(tái)下別扔雞蛋，西紅柿我喜歡 吃），二是改變接口，返回int用1和0對(duì)應(yīng)true和false，用-1對(duì)應(yīng)系統(tǒng)異常。第二種情況是接口返回值是復(fù)雜對(duì)象（RPC），這種情況下其實(shí)沒(méi) 辦法改變什么，忍一忍，拋出個(gè)簡(jiǎn)單的異常得了。注意這時(shí)候可別把異常對(duì)象再套個(gè)七八層，你不累用你接口的人也累。第三種情況是返回值是xml文檔對(duì)象，這 種情況可以把xml文檔定義的靈活一些，讓它能夠兼容正常和異常的情況。

接口要盡量采用更新的標(biāo)準(zhǔn)。如何讓一次定義的接口能服務(wù)更好一點(diǎn)更久一點(diǎn)？在技術(shù)規(guī) 范上簡(jiǎn)單就兩點(diǎn)：不超前，不落伍。超前，支持它的工具集不會(huì)太豐富，估計(jì)誰(shuí)也不想弄出個(gè)看起來(lái)很美就是誰(shuí)都用不了的東東；落伍，眼前所有的工具大概都支 持，不過(guò)明天就不一定了，技術(shù)發(fā)展這么快，不能把自己累死吧。盡量采用更新的標(biāo)準(zhǔn)的意思是在不落伍的基礎(chǔ)上要有前瞻性。舉個(gè)簡(jiǎn)單的例子來(lái)說(shuō)，今天再采用 rpc/encode方式顯得就不合時(shí)宜了，雖然它在前兩年很流行，可今天都已經(jīng)不提倡用了，明天說(shuō)不定大家就都忘了都不用了。就算你及時(shí)更新了你的接 口，客戶呢？他們一定比你更懶。嗯，說(shuō)不定正好趁機(jī)換家供應(yīng)商。兄弟，你就連粥都沒(méi)得喝了。

要注意標(biāo)準(zhǔn)的通用性。雖 然都是一樣的標(biāo)準(zhǔn)，但標(biāo)準(zhǔn)有不同的版本，而且即使對(duì)同一個(gè)版本的標(biāo)準(zhǔn)，不同的工具實(shí)現(xiàn)起來(lái)也還是有細(xì)微差別的。如果用戶是特定的還好說(shuō)，采用些工具綁定的 特性也沒(méi)什么。但如果接口用戶不是特定的人群，那就要注意了，在采用某一規(guī)范標(biāo)準(zhǔn)時(shí)一定要注意，不要用實(shí)現(xiàn)工具所特有的東西，否則很有可能造成客戶的麻 煩，導(dǎo)致只有很少一部分客戶能使用你提供的接口。多一個(gè)客戶就多一分錢啊，兄弟，干嘛跟錢過(guò)不去？

接口要測(cè)試方便。測(cè) 試驅(qū)動(dòng)倒不至于還，那是牛人們干得事，不過(guò)在正是發(fā)布之前測(cè)試測(cè)試自己也放心不是？方便測(cè)試的接口意味著自己麻煩少，測(cè)起來(lái)方便嘛（循環(huán)論證?）。同時(shí)這 點(diǎn)如果做的好，還會(huì)帶來(lái)額外的好處－－客戶用起來(lái)也方便。為什么？測(cè)試代碼也是對(duì)接口的使用，測(cè)試方便不正說(shuō)明的接口應(yīng)用性強(qiáng)嘛。自己測(cè)試自己接口帶來(lái)的 好處大概有N個(gè)，具體可以參考TDD的相關(guān)資料。

btw：寫完回頭一看，KAO，居然有十條，這絕不是我的本意，兄弟們自己看著取舍。

感謝jackyrong同學(xué)的意見(jiàn)。

本文同時(shí)發(fā)布在 http://osteching.com/node/1。