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

介面規範文件 具體內容如下： 一：協議規範 二：域名規範 三：版本控制規範 四：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版本資料夾裡建立，一個或者多個介面檔案。 一個的規範：

https://127.0.0.1:8080/api/v1/getBanner 這就是一個獲取banner的介面。 多個的規範是根據業務需求來區分： https://127.0.0.1:8080/api/v1/home/getBanner https://127.0.0.1:8080/api/v1/user/userLogin 新建user檔案，裡面存放使用者級別的操作：如登陸、註冊、修改密碼等等。 新建sms檔案，裡面存放對簡訊的介面操作：如傳送驗證碼、驗證手機號等等。   所以，介面方法檔案必須要有自己的規範，命名必須統一使用駝峰命名法或者下劃線拼接命名法。舉個栗子：（upperCamelCase）（upper_camel_case）。所有介面命名方式，必須遵循如下規範。 （1）新增方法：如新增一個地址、新增一個聯絡人。 命名規範： 必須以“add”為字首。例如addAddress 事例地址：

https://127.0.0.1:8080/api/v1/addAddress （2）刪除方法：如刪除一個地址。 命名規範： 必須以“delete”為字首。例如deleteAddress 事例地址： https://127.0.0.1:8080/api/v1/deleteAddress （3）修改方法：如修改一個地址。 命名規範： 必須以“updata”為字首。例如updataAddress 事例地址： https://127.0.0.1:8080/api/v1/updataAddress （4）獲取方法：如獲取一個地址。 命名規範： 必須以“get”為字首。例如getAddress 事例地址： https://127.0.0.1:8080/api/v1/getAddress （5）獲取列表方法：如獲取一個地址列表。 命名規範： 必須以“get”為字首、“List”為字尾。例如getAddressList 事例地址： https://127.0.0.1:8080/api/v1/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查詢。 規範事例： 普通列表介面： https://127.0.0.1:8080/api/v1/getBannerList （不傳page、後臺預設返回全部資料） （banner介面不需要使用檢索條件） 需檢索列表介面： https://127.0.0.1:8080/api/v1/getOrderList （不傳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/xxx 2.請求方式 例如：POST、GET等 3.請求引數 例如：傳 id：“1”，name：“小明” 4.返回引數 例如：{ json... } 【參考上面的介面規範】 5.返回事例 例如：{ json... }   十：介面管理工具使用教程 介面管理工具有很多，例如RAP、eolinker等等。 介面管理工具基本的作用都是用來管理介面的。這裡簡單介紹eolinker的使用方法。 使用方法步驟： 建立介面管理專案。 邀請開發者同事加入。 編寫介面（介面地址、請求引數及備註、請求方式、返回引數及備註、返回事例、線上測試介面）。 開發者使用介面。 過程中靈活配合，介面可以靈活更新。 完成專案後可以匯出介面文件。  

1. 查詢指定專案屬性

介面功能
獲取制定專案的分類資訊

URL
http://www.api.com/index.php

支援格式
JSON

HTTP請求方式
GET

請求引數
引數 必選 型別 說明
name ture string 請求的專案名
type true int 請求專案的型別。1：型別一；2：型別二 。
返回欄位
返回欄位 欄位型別 說明
status int 返回結果狀態。0：正常；1：錯誤。
company string 所屬公司名
category string 所屬型別
介面示例
地址：http://www.api.com/index.php?name=”可口可樂”&type=1

{
"statue": 0,
"company": "可口可樂",
"category": "飲料",
}
1
2
3
4
5
markdown原始碼如下：

目錄

1\. 查詢指定專案屬性介面

---

**1\. 查詢指定專案屬性**
###### 介面功能
> 獲取制定專案的分類資訊

###### URL
> [http://www.api.com/index.php](www.api.com/index.php)

###### 支援格式
> JSON

###### HTTP請求方式
> GET

###### 請求引數
> |引數|必選|型別|說明|
|:----- |:-------|:-----|----- |
|name |ture |string|請求的專案名 |
|type |true |int |請求專案的型別。1：型別一；2：型別二 。|

###### 返回欄位
> |返回欄位|欄位型別|說明 |
|:----- |:------|:----------------------------- |
|status |int |返回結果狀態。0：正常；1：錯誤。 |
|company |string | 所屬公司名 |
|category |string |所屬型別 |

###### 介面示例
> 地址：[http://www.api.com/index.php?name="可口可樂"&type=1](http://www.api.com/index.php?name="可口可樂"&type=1)
``` javascript
{
"statue": 0,
"company": "可口可樂",
"category": "飲料",
}
---------------------