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

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

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

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

接口參數(shù)不應(yīng)該增加客戶端和服務(wù)端的耦合性。兄 弟們肯定在很多地方看見過，不應(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)致增加額外的說明文檔，增加client和 server編程的負(fù)擔(dān)。又或者傳入sql語句，嗯，這個(gè)作為反面教材到處都在罵，我就簡單點(diǎn)個(gè)名就好了。

要提供對(duì)接口參數(shù)和返回值的校驗(yàn)。嚴(yán) 格的來說，對(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ì)覺 得你暴露的方法很難用，因?yàn)橄拗铺嗔恕１容^理想的系統(tǒng)應(yīng)該是寬進(jìn)嚴(yán)出的，目標(biāo)用戶越多越應(yīng)該注意這一點(diǎn)。要在寬進(jìn)嚴(yán)出和全面校驗(yàn)之間做好平衡確實(shí)挺難的。我的建議是，對(duì)要暴露的接口自己做測試，在測試的過程中體會(huì)這個(gè)度。一般來說如果自己感覺都不爽，那別人是絕對(duì)不會(huì)用的。

接口的返回值應(yīng)該是簡單的語言無關(guān)的。 看 見過很多人問如何返回ResultSet/DataSet之類的復(fù)雜類型，尤其是玩.net的人，也許是vs.net對(duì)封裝DataSet提供了過于完美 的支持吧。但對(duì)于XML來說，把任何復(fù)雜對(duì)象映射到xml文檔都是困難的。就好比把三維向二維投影一樣，復(fù)雜性增加了可不是一點(diǎn)半點(diǎn)。在XML中說到底所 有的類型都是字符串，要想表達(dá)其他類型，就要加額外的說明。可以看看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í)要具體情況具體分析。簡單的可以歸納為三種情況。第一種情況是接口返回值 是簡單類型，比如boolean型，就true和false兩種情況，不拋出異常怎么辦？選擇有兩種，一是拋出異常（廢話！臺(tái)下別扔雞蛋，西紅柿我喜歡 吃），二是改變接口，返回int用1和0對(duì)應(yīng)true和false，用-1對(duì)應(yīng)系統(tǒng)異常。第二種情況是接口返回值是復(fù)雜對(duì)象（RPC），這種情況下其實(shí)沒 辦法改變什么，忍一忍，拋出個(gè)簡單的異常得了。注意這時(shí)候可別把異常對(duì)象再套個(gè)七八層，你不累用你接口的人也累。第三種情況是返回值是xml文檔對(duì)象，這 種情況可以把xml文檔定義的靈活一些，讓它能夠兼容正常和異常的情況。

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

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

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

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

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

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