《移動開發介面及文件編寫規範》V1.0文件說明

編寫整理：童正剛 2015-05

一、概述

ü      有關介面

1、介面是純資料的互動

APP介面是移動裝置和業務之間進行通訊的途徑。實質就是以特定的規則通過介面直接操作資料庫的增刪改查。

ü      介面分類

1、查詢類介面

查詢類介面是指客戶端傳遞一些引數，服務端根據引數依據需求，前往資料庫查詢需要的結果返回資料的一類介面。

返回型別一般有兩種。第一種是返回一個物件，第二種是返回一個數組物件。

第一種比如登陸，客戶端把使用者名稱密碼上傳到介面，伺服器返回使用者的個人資訊。

第二種比如獲取客戶，客戶端把使用者的身份資訊上傳到介面，伺服器返回此身份下的所有客戶陣列集合。

2、操作類介面

操作類介面是指，客戶端通過介面進行一些增刪改的操作。比如新增一個客戶，修改客戶資訊，或者刪除一個客戶。伺服器一般返回執行的狀態，有的需要返回執行結果的一些資訊，比如新增客戶後，返回客戶的ID。

3、上傳下載類介面

上傳下載類介面是涉及到檔案傳輸的介面。比如上傳頭像，需要上傳圖片到伺服器，服務端根據需求響應儲存並返回結果。比如客戶端需要顯示使用者頭像，需要讀取網路圖片檔案，在手機上進行顯示。

4、推送類介面

除了客戶端主動去請求服務端，獲取需要資訊之外。有時候，也存在服務端有訊息需要通知客戶端的情況，這時候就是服務端向客戶端傳送訊息。這類需求可以通過客戶端短時間類迴圈請求解決，也可以通過第三方專業推送解決。也可以通過自己使用socket或者xmpp等協議進行開發。

二、介面編寫原則

ü      實用性

編寫介面API應遵從實用性原則。

1、資料格式：推薦使用JSON格式資料，因為JSON有較好的跨平臺性，以及資料格式佔用位元組數較少，當然也可採用XML、TEXT作為程式開發輔助。

2、介面執行效率（介面訪問速度）：APP有別於WEB服務，對伺服器端要求是比較嚴格的，在移動端有限的頻寬條件下，要求介面響應速度要快，所有在開發過程中儘量選擇效率高的框架，PHP推薦使用YAF框架，.NET推薦使用Newtonsoft

3、資料量：按需分配，APP客戶端需要什麼資料就返回什麼資料，過多的資料量影響處理速度，最重要的是影響傳輸效率和浪費使用者流量。

4、API

ü      易用性

1、介面、引數命名準確：無論是介面還是引數，命名都應該有意義，讓人一目瞭然。（介面推薦根據APP效果圖欄目進行命名）

2、一個頁面儘可能就用一個介面：現在很多的APP頁面都有廣告、焦點圖、文章列表等，對於這些不同格式的資料，不可能都分配一個介面，這樣加大了APP請求介面數，影響響應速度。建議伺服器端儘可能處理好資料後通過一個介面返回給APP客戶端。

3、介面資料、狀態：介面必須提供明確的資料狀態資訊，不管是成功的，還是失敗的，都必須返回給APP客戶端。

4、介面要有可擴充套件性：方便後期功能性調整，介面應具備可擴充套件性。

ü      安全性

1、介面安全：目前一般都是在APP客戶端和伺服器通過約定的演算法，對傳遞的引數值進行驗證匹配。但是如果APP程式被反編譯，這些約定的演算法就會暴露，特別是在安卓APP中，有了演算法，完全就可以通過驗證模擬介面請求。

2、加密規範：在傳遞使用者名稱密碼時，應採用規範的加密演算法如MD5、RSA、DES，進行資料通訊請求。

3、介面版本控制：對於介面版本控制，需要應對不斷的APP版本升級，新、舊介面的處理，因而需要關注介面版本控制。

二、介面設計原則

1、儘量減少引數傳遞：在客戶端發起HTTP請求介面操作時，應減少引數傳遞，如某些操作只需要ID不需要其他引數，這時候就應該只傳遞ID這個引數。

2、儘量避免介面重複性：在客戶端APP呼叫介面時，儘量提高介面複用性，減少HTTP請求，提高程式穩定性。

3、資料型別規範：客戶端APP呼叫介面時，應標註引數資料型別，以及是否可為空或者預設欄位，如標註了Int型欄位，就不能返回“null”的String型別欄位，否則容易造成程式APP出現數據型別解析異常。

4、設定呼叫html頁面單獨列表：呼叫html頁面應標明是否傳遞安全校驗引數，建議表格中採用是或者否單獨欄位標識。

5、編碼規範：整個API介面開發過程中，應標註介面編碼方式，目前建議採用UTF-8編碼，UTF-8通用性以及URL請求方面都較規範。

6、請求方式：編寫API介面應該標註請求方式，請求方式一般有GET和POST方式

7、GET和POST方式：在數量較小情況下可以使用GET方式，但資料量超過1024位元組就應該採用POST方式，避免出現請求失敗或者請求異常的問題。

8、返回介面呼叫狀態：所有API介面都應該統一標識呼叫的成功失敗資訊和規範錯誤編碼資訊，以及必要的提示欄位資訊。

9、安全機制：介面應規範驗證簽名機制，使用者登入後統一呼叫KEY對介面安全驗證。（關於KEY機制需由介面開發人員定義）

10、引數說明：應標註引數名稱、是否必選、資料型別及範圍、說明以及“否（必選）”傳遞預設的引數。

三、說明文件編寫

ü      標註介面呼叫的統一域名或IP，如：

域名：http://www.XXX.com/

或者IP：http://ip:埠/

ü      介面文件目錄：目錄的編寫是為了APP開發人員快速定位需要的介面資訊，使開發人員在最短的時間內找到需要的介面，同時也會對編寫API介面人員後期的維護修改提高效率。

ü      介面說明，對介面的說明資訊，如：

說明：使用者登入，獲得返回的使用者資訊。

ü      連結，應採用簡寫方式，如：

連結：login（這裡用的是簡寫，全部內容是域名加連結，如：http://www.XXX.com/login）

ü      請求方式，應標註GET或POST請求方式。

ü      傳遞引數，應採用表格形式規範引數說明，如：

引數：

ü      返回結果，應採用表格形式規範返回引數說明，如

正常返回結果：

錯誤返回結果