從零到一： 後端接口文檔

在需求文檔完成後，測試人員以及開發人員應該分別開始了本身的工做。測試人員開始按照需求文檔編寫修改Case，並制定合適的測試計劃，評估自動化測試的可行性等。開發人員根據職位的不一樣開展各自的工做。

做爲普通程序員：

一.掌握核心業務流程：在前期項目中 編寫需求文檔 這段時間中，應該對項目有一個基本的瞭解，並對項目的核心業務有一個明確的認識。每每我對核心業務掌握的不夠全面，致使後期代碼編寫過程當中，會出現一些意想不到的意外，致使工做量增長。例如：業務功能不全，業務邏輯不清楚，最糟糕的是業務流程走不通，那纔是悲劇。

二. 深刻分析數據結構：數據庫中每一個字段都應該是有意義的，並且都應該會被使用到（除非是備用字段），因此要了解每一個字段的含義，是用來幹什麼的！其次，要時刻注意業務中須要的字段，必定不能缺乏，因爲數據庫設計不夠全面，到後期發現數據庫設計邏輯有缺陷，那真的會衍生出不少問題以及Bug，可是這也是最不容易被發現的地方，只有後期作到這一步纔會被發覺。

三. 編寫接口文檔：在充分了解業務流程，以及數據庫結構後，就開始編寫接口文檔了。對業務瞭解的越透徹，寫出的接口才會越合理。在寫接口文檔的時候，須要考慮的事情不少：

a.最基本的：前端須要傳來的參數，返回的數據格式

b.合適的名字：返回的數據要有合適的名字，清晰明瞭，能讓前端人員大體明白數據表明的含義

c.最小數據：不管前端數據渲染，後端數據操做，多餘的冗餘字段會影響項目的性能，因此應該儘可能保持數據的冗餘程度較低。

下面是一個接口文檔的示例：

---------------------------------------------------------------------------------------------------

水井水量

1)      URL地址：class/water.api

2)      請求方式：get/post

3)      請求參數：

參數名	參數類型	參數長度	參數說明	必填
group	字符串		水井編號	Y

4)      接口返回：

                 A:成功：

　　　　　　　　{

   　　　　　　　　　　 "resultCode": 1,

   　　　　　　　　　　 "success": true,

   　　　　　　　　　　　　 "data": {

　　　　　　　　　　　　　　　　　  "waterOne": {

                          　　　　　　　　　　　　　　 "waterName": "水一",

　　　　　　　　　　　　　　　　　 　　　　 "todayWater": {

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_01": "01點水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_02": "02點水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_03": "03點水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_04": "04點水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　　　........

　　　　　　　　　　　　　　　　　　　　　　　　　　}

　　　　　　　　　　　　　　　　　}

　　　　　　　　　　　　　　　　　"waterTwo":{

                          　　　　　　　　　　　　　　 "waterName": "水二",

　　　　　　　　　　　　　　　　　　　　　  "todayWater": {

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_01": "01點水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_02": "02點水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_03": "03點水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_04": "04點水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　........

　　　　　　　　　　　　　　　　　　　　　　}

　　　　　　　　　　　　　　　　　　}

　　　　　　　　　　　　　　}

　　　　　　　　　}

　　　　B:失敗

　　　　　　{"resultCode": "-1","resultMsg": "內部異常"}

--------------------------------------------------------------------------------------------------

這是一個簡單關於水井水量的api，除了一些基本的信息，例如 接口名，接口訪問路徑，請求方式，請求參數，返回數據等，還應該注意接口中應該簡化的地方，例如，用water_01表示一點時水井水量的字段，有大量重複數據，能夠直接改爲01，02，03，04.....這樣能節省一點就節省一點。固然還要考慮其餘的因素。

在前段時間我總以爲寫接口文檔沒有什麼用處，由於即便寫了，到後期，總會由於需求變動，或者由於之前沒考慮到的地方而從新設計接口文檔，每每到最後，最終接口與最初的接口文檔徹底不同，這樣寫接口文檔有什麼用處呢?而後，與前端人員聊天的時候，他們跟我說，寫接口文檔給他們前端人員是頗有用處的。而後本身仔細想了想，確實寫接口文檔是有益的。

1）能讓前端人員心中大體有數，這些數據的格式是怎麼樣的。並能夠製造相似的假數據直接進行前端開發

2）寫接口文檔，能讓本身對業務有一個更清晰的認識與總結，對之後的代碼編寫有必定規劃

3）要想寫出合適的接口，必須對業務邏輯以及數據結構有很深的認識。