從零到一: 后端接口文檔


在需求文檔完成后,測試人員以及開發人員應該分別開始了自己的工作。測試人員開始按照需求文檔編寫修改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)要想寫出合適的接口,必須對業務邏輯以及數據結構有很深的認識。


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM