定義web service接口的十點注意事項(轉)

文/juleven  出處/blogjava

一、接口是自說明的。
也就是說，接口的名字、參數和返回值在一看之下就知道這接口大概是幹什麼用的。當然接口描述文檔肯定是必須的，但這些描述文檔的質量誰知道怎麼樣呢，誰有空天天翻着文檔寫東西呢，又有誰會背下來呢？所以讓人眼前一亮的接口命名絕對值得，這也是所有代碼書會告訴你應該遵守的一條。想想看見個叫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的相關資料。