吐槽介面文件(二)——什麼是優秀的介面文件

語言: CN / TW / HK

昨天說了合格的介面文件,今天繼續嘮一嘮,什麼是我覺得優秀的介面文件。

專案部分

首先,優秀的介面文件在合格的介面文件上最顯著的一個特徵,就是在描述幾種專案必須要素基礎上,要給出更加詳細的說明以及所涉及到的技術細節,甚至要給出關鍵程式碼邏輯的demo。例如,除了文字版敘述加密、解密和驗證演算法以外,要給出測試語言所能夠時直接抄用的程式碼demo。 其次,在專案所涉及到的請求方法這個要素上,要給出更加詳細的方法使用規範;在傳參格式這個要素上,要給出傳參的具體請求和響應內容的Demo。雖然專案中總有一些特殊的介面會違反這些規範,有的時候也是不可避免的,特別是在跟其他系統對接的時候,很難做到全部統一。但是還是需要開發。在編寫文件的時候,給出一個統一的格式,這樣能夠極大的減少測試人員的工時消耗。 一個優秀的介面文件。最直觀的就是它的目錄部分。這部分包含著整個專案結構文件的功能模組集合,因此要讓人看了介面文件,對整個專案的業務功能有一目瞭然之感。而且介面文件模組要有足夠的文字說明,模組的劃分要與模組下面的介面有很強的關聯性,特別是在url的劃分上。我認為優秀的介面文件的一個重要體現就是測試人員拿到一個介面的地址,然後能在這個介面文件的成績目錄中找到這個介面準確的位置,而不用通過全域性搜尋。

介面部分

對於優秀的介面文件來說,介面部分除了以上的幾個要素以外,還需要對介面請求引數的引數名進行文字說明,因為有時候如果引數特別複雜的話,會不太能夠看清楚引數名、得到引數業務的相關情況。這裡我覺得好的方法有最兩種,一種是在定義引數名稱的時候有一定的統一規範,且全域性對於同一業務使用統一的英文單詞,對於相同業務的行為進行統一的命名規範。例如新增使用者這個介面可以用adduser,而不是使用at customer或者insertuser這樣的詞彙,以免造成同一業務邏輯在不同的介面有不同的名字。 優秀的介面文件,另外一個直觀的體現就是讓測試人員在簡單閱讀介面文件之後,能夠迅速的調通這個介面,這依賴於介面文件中給出的請求引數的demo。這個對測試人員來說非常重要,因為如果一個介面請求不通的話,原因可能是多個因素疊加在一起的。測試人員很難在接手一個新介面的時候,就把這些因素區分開,所以就需要一個正確的請求引數組合來幫助測試人員迅速的除錯通過介面。 除了以上幾個方面以外,我覺得還有一個對我來說非常重要的介面測試文件內容就是引數來源。因為在我實際做測試的過程當中,大多數的介面引數都是從另外的介面響應中獲取的。一般規定的介面的範圍可能是1~1萬這樣子,但是對於我要測的業務來講,只可能就是幾個。正常,我們會對介面先進行介面引數驗證的驗證,也就是冒煙測試。但是越過這個階段之後,我們需要進行更多的是業務相關的一個介面,測試文件引數以及響應資料來源,一般都是需要跟其他業務相關的介面有關聯性的。介面測試不像ui測試,可以通過頁面去檢視相關的內容,介面測試面對的就是一堆json資料。如果介面的引數命名不夠統一,不夠規範的話,介面測試人員很難去找到業務測試中介面資料的驗證值。所以我認為介面測試引數來源非常重要。

維護

對於優秀的介面文件而言,介面文件的實時性和準確性已經得到了保證,需要提高的就是文件變更的次數減少以及變更時的人員通知。如果是新介面的話。第一次提測過程當中,介面文件的變更是非常難以避免的,這裡測試人員要有心理準備。但是對於舊介面,維護和更新是低頻率發生的事情,但是一旦發生處理不及時,就會導致一些故障。 最好的介面文件就是一次編寫,永不維護的。當然這是不太可能的。優秀的介面文件,不止在於文件本身,還在於開發、測試相互的溝通效率。 最後,工欲善其事,必先利其器,這裡推薦一個介面文件工具:Eolinker,給我省下了很多功夫。 使用地址:www.eolinker.com