最近搞了兩天的web
service測試，對于這些web service接口感覺實在是XX，加上經常在網上看見兄弟們討論web
service相關的一些問題，覺得十分有必要對什么是比較好的web
service接口有個統一的認識。今天這篇B文就來說說我眼中定義良好的web service接口是個什么鳥樣子。
接口是自說明的。也
就是說，接口的名字、參數和返回值在一看之下就知道這接口大概是干什么用的。當然接口描述文檔肯定是必須的，但這些描述文檔的質量誰知道怎么樣呢，誰有空
天天翻著文檔寫東西呢，又有誰會背下來呢？所以讓人眼前一亮的接口命名絕對值得，這也是所有代碼書會告訴你應該遵守的一條。想想看見個叫add的方法卻做
multiply的悲慘生活吧，即使文檔明確說了add是做multiply，是不是每次見了也都想罵人呢。
服務接口粒度要合適。web
service服務接口粒度太小了，那純粹是不考慮xml解析性能了。一般新手容易犯這毛病，簡單的把類的方法暴露出來做服務接口，這樣其實是把原來在
locale的調用放到了remote，除此之外幾乎沒有任何好處。粒度太大，會給使用著帶來很多麻煩，因為在web
service中，粒度很大的服務一般都需要很多參數來映射該服務各種各樣的情況。
接口參數要盡量簡單。那
位說了，web
service是服務啊大哥，你讓我就一個參數，怎么提供服務啊，你以為服務都跟查詢天氣預報一樣簡單啊，給個城市名子，回頭告訴你天氣情況。說實話，要
用一個接口提供一個完善的服務確實不容易。有個名詞叫服務的粒度，這個粒度確實不好掌握，服務名定了之后要想讓這個服務更豐滿只能靠更多的參數來搞定。對
于需要數十個參數的服務接口來說，首先要想的應該是，我KAO，這個服務定義的有問題吧？讓我們再來分析分析它，給它一個合適定位，給他瘦身。要是你非不
信邪發布個有三十多個參數的接口，嚴重建議你在發布接口之前自己拿來測試一下先。
接口參數不應該增加客戶端和服務端的耦合性。兄
弟們肯定在很多地方看見過，不應該在方法參數上增加額外的耦合性這條原則。這個在web
service中同樣適用，甚至可以著重強調一下這一條，因為在web
service中把字符串進行特別處理實在太容易了。比如作為參數的字符串對應特殊的業務規則，這么做會導致增加額外的說明文檔，增加client和
server編程的負擔。又或者傳入sql語句，嗯，這個作為反面教材到處都在罵，我就簡單點個名就好了。
要提供對接口參數和返回值的校驗。嚴
格的來說，對接口參數和返回值的驗證也應該算是web
service接口聲明的一部分。尤其是對document/literal的情況，要提供相應的schema以供校驗之用（dtd應該處在逐漸淘汰中
了）。增加對參數和返回值的校驗，有利于減少調用者的疑惑，系統接受什么樣的參數，返回值什么格式都一目了然。但是這需要一個很好的權衡，否則調用者會覺
得你暴露的方法很難用，因為限制太多了。比較理想的系統應該是
寬進嚴出的，目標用戶越多越應該注意這一點。要在寬進嚴出和全面校驗之間做好平衡確實挺難的。我的建議是，對要暴露的接口自己做測試，在測試的過程中體會這個度。一般來說如果自己感覺都不爽，那別人是絕對不會用的。
接口的返回值應該是簡單的語言無關的。 看
見過很多人問如何返回ResultSet/DataSet之類的復雜類型，尤其是玩.net的人，也許是vs.net對封裝DataSet提供了過于完美
的支持吧。但對于XML來說，把任何復雜對象映射到xml文檔都是困難的。就好比把三維向二維投影一樣，復雜性增加了可不是一點半點。在XML中說到底所
有的類型都是字符串，要想表達其他類型，就要加額外的說明。可以看看rpc/encode方式WSDL文檔的
complexType部分，體會下心情。
謹慎的拋出異常。可
以把web service中的異常（SOAP FAULT）對比Java的runtime
exception。任何異常都應該對應系統意外，而不是業務例外。對于這點其實要具體情況具體分析。簡單的可以歸納為三種情況。第一種情況是接口返回值
是簡單類型，比如boolean型，就true和false兩種情況，不拋出異常怎么辦？選擇有兩種，一是拋出異常（廢話！臺下別扔雞蛋，西紅柿我喜歡
吃），二是改變接口，返回int用1和0對應true和false，用-1對應系統異常。第二種情況是接口返回值是復雜對象（RPC），這種情況下其實沒
辦法改變什么，忍一忍，拋出個簡單的異常得了。注意這時候可別把異常對象再套個七八層，你不累用你接口的人也累。第三種情況是返回值是xml文檔對象，這
種情況可以把xml文檔定義的靈活一些，讓它能夠兼容正常和異常的情況。
接口要盡量采用更新的標準。如何讓一次定義的接口能服務更好一點更久一點？在技術規
范上簡單就兩點：不超前，不落伍。超前，支持它的工具集不會太豐富，估計誰也不想弄出個看起來很美就是誰都用不了的東東；落伍，眼前所有的工具大概都支
持，不過明天就不一定了，技術發展這么快，不能把自己累死吧。盡量采用更新的標準的意思是在不落伍的基礎上要有前瞻性。舉個簡單的例子來說，今天再采用
rpc/encode方式顯得就不合時宜了，雖然它在前兩年很流行，可今天都已經不提倡用了，明天說不定大家就都忘了都不用了。就算你及時更新了你的接
口，客戶呢？他們一定比你更懶。嗯，說不定正好趁機換家供應商。兄弟，你就連粥都沒得喝了。
要注意標準的通用性。雖
然都是一樣的標準，但標準有不同的版本，而且即使對同一個版本的標準，不同的工具實現起來也還是有細微差別的。如果用戶是特定的還好說，采用些工具綁定的
特性也沒什么。但如果接口用戶不是特定的人群，那就要注意了，在采用某一規范標準時一定要注意，不要用實現工具所特有的東西，否則很有可能造成客戶的麻
煩，導致只有很少一部分客戶能使用你提供的接口。多一個客戶就多一分錢啊，兄弟，干嘛跟錢過不去？
接口要測試方便。測
試驅動倒不至于還，那是牛人們干得事，不過在正是發布之前測試測試自己也放心不是？方便測試的接口意味著自己麻煩少，測起來方便嘛（循環論證?）。同時這
點如果做的好，還會帶來額外的好處－－客戶用起來也方便。為什么？測試代碼也是對接口的使用，測試方便不正說明的接口應用性強嘛。自己測試自己接口帶來的
好處大概有N個，具體可以參考TDD的相關資料。
btw：寫完回頭一看，KAO，居然有十條，這絕不是我的本意，兄弟們自己看著取舍。
感謝
jackyrong同學的意見。
本文同時發布在
http://osteching.com/node/1。