寫在前面：這是我最近整理的介面規範文件，無規矩不成方圓，為了app開發人員與後臺介面開發人員更好的配合，我特意整理了這麼一篇文件供大家參考學習，如有意見請在評論區留言謝謝。因部分內容涉及公司程式碼，我對本文件略有刪減。

介面規範說起來大，其實也就那麼幾個部分，介面規範、介面管理工具、介面文件編寫、開發文件編寫。以下將詳細介紹，下面進入正文：

介面規範文件具體內容如下：一：協議規範二：域名規範三：版本控制規範四：API路徑規範五：API命名規範六：請求引數規範七：列表請求特殊規範八：返回資料規範九：介面文件規範十：介面管理工具使用教程

參與編寫	更新日期	版本	備註
AbyssKitty	2018/04/06	V1.1.0	無

V1.1.0更新日誌：1. 新增協議規範、域名規範、版本控制規範、列表特殊規範。2. 更新介面管理工具使用教程。3. 美化排版。正文：一：協議規範為進一步確保資料互動安全。正式地址（生產地址）必須遵循HTTPS協議。二：域名規範每個專案要有且僅有一個自己唯一的域名+埠。在專案配置檔案中要新增靜態變數專門進行儲存。如果一個域名滿足不了要求，那麼就需要再新增一個。格式規範如下：（java）public static final String URL_BASE = “https://127.0.0.1:8080/”;（java）public static final String URL_BASE_SUB = “https://192.168.0.1:8080/”;必須以https開頭，並以“/”結尾。三：API路徑規範作為介面路徑，為了和其他路徑完美區分，必須在路徑中新增api目錄格式規範如下：（java）public static final String URL_API = “api/”;（PHP）php目錄是加index.php/api/必須以字母開頭，並以“/”結尾。四：版本控制規範專案正式上線後，正式版本要確定介面版本、並備份介面程式碼。為方便管理，需要在介面路徑中加入版本號資訊。格式規範如下：（java）public static final String URL_VERSION =”v1/”;必須以字母開頭，並以“/”結尾。更新版本後可以使用v2 v3等、依次遞加。五：

API命名規範根據二：域名規範、三：API路徑規範、四：版本控制規範。專案中必須在配置檔案中增加BaseUrl靜態常量。值=三個相加。格式規範如下：（java）public static final String BASEURL=URL_BASE+URL_API+URL_VERSION;具體程式碼如下：BASEURL = [“https://127.0.0.1:8080/api/v1/”]BASEURL = [“https://127.0.0.1:8080/api/v1/”]BASEURL = [“https://127.0.0.1:8080/api/v1/”]重要的事情說三遍。根據業務需求，可以在v1版本資料夾裡建立，一個或者多個介面檔案。一個的規範：這就是一個獲取banner的介面。多個的規範是根據業務需求來區分：新建user檔案，裡面存放使用者級別的操作：如登陸、註冊、修改密碼等等。新建sms檔案，裡面存放對簡訊的介面操作：如傳送驗證碼、驗證手機號等等。所以，介面方法檔案必須要有自己的規範，命名必須統一使用駝峰命名法或者下劃線拼接命名法。舉個栗子：（upperCamelCase）（upper_camel_case）。所有介面命名方式，必須遵循如下規範。（1）新增方法：如新增一個地址、新增一個聯絡人。命名規範：必須以“add”為字首。例如addAddress（2）刪除方法：如刪除一個地址。命名規範：必須以“delete”為字首。例如deleteAddress（3）修改方法：如修改一個地址。命名規範：必須以“updata”為字首。例如updataAddress（4）獲取方法：如獲取一個地址。命名規範：必須以“get”為字首。例如getAddress（5）獲取列表方法：如獲取一個地址列表。命名規範：必須以“get”為字首、“List”為字尾。例如getAddressList其他規範：傳送驗證碼使用‘send’為字首、儲存一個數據以‘save’為字首、上傳圖片以‘uploadImage’為名稱等等。具體地址就等於（BASEURL+“address/getAddressList”）目的：一目瞭然、降低維護成本。六：請求引數規範請求方式：公共資料使用get方式請求，私有資料使用post方式請求。儘量全部是用post。請求頭：請求頭根據專案需求新增配置引數。如：accept=‘application/json’等。請求頭根據專案需求可以要求傳入使用者token、app名稱版本、唯一驗籤碼等加密資料。請求引數：根據資料庫欄位進行命名、保持一致最省事。七：列表請求特殊規範列表請求，請求引數規範，必須傳參：頁數和每頁個數的欄位。並可包含查詢等資訊。1. 列表介面必傳欄位（分頁、使用小寫字母）。page ：頁數，從1開始。例如：{ “page”: 1  }subnumber : 每頁數量。2. 列表介面選傳欄位。只要是列表介面、一般情況下都會存在檢索條件，例如淘寶商品檢索。檢索條件為選填。後臺需進行非空非null判斷，選傳欄位為空為null預設查詢全部。有值則需要接收，並進行sql查詢。規範事例：（不傳page、後臺預設返回全部資料）（banner介面不需要使用檢索條件）（不傳page、後臺預設返回全部資料）（Order訂單介面需要檢索條件，不傳就不檢索，只進行分頁查詢）（如果有 time price等檢索條件，不傳就不檢索，傳了就進行條件查詢，並返回相應資料）八：返回資料規範注：列表資料返回，沒有特殊情況的條件下，必須最新資料在上面，依次排序。返回事例：{"list":[],"object":{}, //"object":"""status":"SUCCESS","message":"我是提示訊息", ..."page":1,"subnumber":10,}必選-命名規範：駝峰命名法。必選-新增鍵值規則：名字對應固定的格式（list就是陣列[]）。舉個栗子：比如一個"list":[]滿足不了需求，那麼可以新增一個"map":[]。比如一個"object":{"name":"小明"}滿足不了需求，那麼可以新增一個"details":{"name":"小紅"}。名字對應固定的格式，陣列就是陣列、實體類就是實體類、欄位就是欄位。不能data在這個介面返回的是實體類、另一個介面又返回陣列了。需要特別注意。必選-list：list列表（陣列）為空時顯示[]。必選-object：實體資料，json鍵值對。必選-status：狀態資訊=SUCCESS、ERROR等靜態變數。必選-message：提示訊息。（載入成功、）可選-page：頁數（分頁查新時使用、顯示第幾頁從一開始）。可選-subnumber：每頁的格式（分頁查詢時使用、顯示當前頁的個數）。九：介面文件規範介面文件需要包含以下部分：文件名稱。版本號。編寫人。編寫、修改日期。baseUrl地址。更新日誌。介面詳情。（詳情規範如下）介面詳情編輯規範：一個完整的介面需要由以下幾部分組成1.請求地址 例如：https://127.0.0.1:8080/xxx/xxx/xxx2.請求方式 例如：POST、GET等3.請求引數 例如：傳 id：“1”，name：“小明”4.返回引數 例如：{ json... } 【參考上面的介面規範】5.返回事例 例如：{ json... }十：介面管理工具使用教程介面管理工具有很多，例如RAP、eolinker等等。介面管理工具基本的作用都是用來管理介面的。這裡簡單介紹eolinker的使用方法。使用方法步驟：建立介面管理專案。邀請開發者同事加入。編寫介面（介面地址、請求引數及備註、請求方式、返回引數及備註、返回事例、線上測試介面）。開發者使用介面。過程中靈活配合，介面可以靈活更新。完成專案後可以匯出介面文件。RAP的特色：RAP是一個GUI的WEB介面管理工具。在RAP中，您可定義介面的URL、請求&響應細節格式等等。通過分析這些資料，RAP提供MOCK服務、測試服務等自動化工具。RAP同時提供大量企業級功能，幫助企業和團隊高效的工作。在前後端分離的開發模式下，我們通常需要定義一份介面文件來規範介面的具體資訊。如一個請求的地址、有幾個引數、引數名稱及型別含義等等。RAP 首先方便團隊錄入、檢視和管理這些介面文件，並通過分析結構化的文件資料，重複利用並生成自測資料、提供自測控制檯等等... 大幅度提升開發效率。強大的GUI工具 給力的使用者體驗，你將會愛上使用RAP來管理您的API文件。完善的MOCK服務 文件定義好的瞬間，所有介面已經準備就緒。有了MockJS，無論您的業務模型有多複雜，它都能很好的滿足。龐大的使用者群 RAP在阿里巴巴有200多個大型專案在使用，也有許多著名的公司、開源人士在使用。RAP跟隨這些業務的成行而成長，專注細節，把握質量，經得住考驗。免費 + 專業的技術支援 RAP是免費的，而且你的技術諮詢都將在24小時內得到答覆。大多數情況，在1小時內會得到答覆。RAP是一個視覺化介面管理工具 通過分析介面結構，動態生成模擬資料，校驗真實介面正確性， 圍繞介面定義，通過一系列自動化工具提升我們的協作效率。