5 前后端協(xié)助規(guī)范

對于前端來說，API文檔可作為開發(fā)工具，好的API文檔可以減少不必要的溝通成本，有效的提升開發(fā)效率。

5.1 API設(shè)計(jì)

RESTful是目前使用最為廣泛的API設(shè)計(jì)規(guī)范, 基于HTTP本身的機(jī)制來實(shí)現(xiàn).

5.2 API 安全：

Token驗(yàn)證 表單驗(yàn)證 字段加密/簽名校驗(yàn)

5.3 API管理方式：

傳統(tǒng)方式 ：手寫文檔、離線API文檔、代碼生成文檔

互聯(lián)網(wǎng)模式：mock server

5.4 API接口文檔規(guī)范：

1).版本號

2).文檔描述

3).服務(wù)器地址：測試服務(wù)器，正式服務(wù)器

4).安全和認(rèn)證: token信息

5).全局接口通用配置參數(shù)，必須說明類型(數(shù)據(jù)類型、字段含義、是否可選，默認(rèn)值等)

簡單使用示例：

| 字段            | 類型             | 含義         | 是否必要     | 示例          |    
| order_by       | string           | 按字段排序    | 否              |   order_by=-id    | 
| page           | int              | 指定頁數(shù)      | 否          |  page=1           | 
| size           | int              | 指定每頁條數(shù)     | 否          | size=20     |    

6).接口請求狀態(tài)：

200: "服務(wù)器成功返回請求的數(shù)據(jù)"

400: "發(fā)出的請求有錯(cuò)誤，服務(wù)器沒有進(jìn)行新建或修改數(shù)據(jù)的操作"

401: "用戶沒有權(quán)限（令牌、用戶名、密碼錯(cuò)誤）"

403: "用戶得到授權(quán)，但是訪問是被禁止的"

404: "發(fā)出的請求針對的是不存在的記錄，服務(wù)器沒有進(jìn)行操作"

406: "請求的格式不可得"

410: "請求的資源被永久刪除，且不會再得到的"

500: "服務(wù)器發(fā)生錯(cuò)誤，請檢查服務(wù)器"

502: "網(wǎng)關(guān)錯(cuò)誤。",

503: "服務(wù)不可用，服務(wù)器暫時(shí)過載或維護(hù)。",

504: "網(wǎng)關(guān)超時(shí)。"

7).通用響應(yīng)參數(shù)格式 ,必須說明類型(數(shù)據(jù)類型、字段含義, 值的說明)

簡單使用示例：

{
  data: []
    errmsg: ""
    errno: 0
    total: 3
}
| 字段            | 類型             | 含義         | 是否必要     | 說明          |    
| data           | object           | 請求數(shù)據(jù)     | 否              |                               | 
| errmsg         | string           | 提示信息     | 是              |                               | 
| errno          | int              | 數(shù)據(jù)返回狀態(tài)    | 是          | 0 成功 非0 失敗 |    
| total          | int                  | 數(shù)據(jù)總數(shù)     | 否              |                               |   

8).具體接口定義

• API接口地址

• API接口請求類型：get/post/patch/delect

• API接口描述

• 請求參數(shù)及其描述，必須說明類型(數(shù)據(jù)類型、字段含義、是否可選、 值的說明（1：是 2:否）、默認(rèn)值等)

• 響應(yīng)參數(shù)及其描述, 必須說明類型(數(shù)據(jù)類型、字段含義、值的說明（1：是 2:否）等)

• 可能的異常情況、錯(cuò)誤代碼、以及描述

• 請求參數(shù)示例

  | 字段            | 類型             | 含義        | 示例 | 是否必要 |
  | rule_name       | string           | 規(guī)則名稱    |      | 否       |
  | key_word        | string           | 關(guān)鍵字      |      | 是       |
  | reply_type      | int              | 回復(fù)類型    |      | 是       |
  | reply_content   | string           | 回復(fù)內(nèi)容    |      | 否       |
  | reply_image_url | string           | 回復(fù)圖片url |      | 否       |
  

• 響應(yīng)數(shù)據(jù)示例

• {
        "errno": 0,
        "errmsg": "success",
      "data": {
          "created_at": "2019-01-02 15:55:01",
          "id": 15,
          "key_word": "",
          "reply_content": "",
          "reply_image_url": "",
          "reply_type": 320931,
          "rule_name": "zonst",
          "updated_at": "2019-01-02 15:55:01"
      }
  }
  
  | 字段            | 類型              | 含義        | 說明           |
  | rule_name       | string           | 規(guī)則名稱    |               |
  | key_word        | string           | 關(guān)鍵字      |               |
  | reply_type      | int              | 回復(fù)類型    | 1：文字 2：圖片 | 
  | reply_content   | string           | 回復(fù)內(nèi)容    |               | 
  | reply_image_url | string           | 回復(fù)圖片url |               | 
  | created_at      | string, datetime | 創(chuàng)建時(shí)間    |               | 
  | updated_at      | string, datetime | 更新時(shí)間    |               |
  

• 異常情況示例

  {
      "errno": -1
        "errmsg": "err"
  }
  
  

5.5 接口測試與模擬

為了做到高效率的前后端并行開發(fā)，接口的測試與模擬是必要的。

• 前端要求后端在聯(lián)調(diào)之前，需要測試驗(yàn)證好自己的接口是否可以正常工作。而不是在聯(lián)調(diào)期間，把前端當(dāng)‘接口測試員’，阻塞接口聯(lián)調(diào)進(jìn)度
• 另外前端需要在后端接口未準(zhǔn)備好之前，通過接口模擬的方式，來編寫業(yè)務(wù)邏輯代碼。

針對接口測試與模擬，存在下圖這樣一個(gè)理想的模型:

mock server.png

一切從定義良好的接口文檔出發(fā)，生成Mock Server和Mock Client, Mock Server給前端提供模擬數(shù)據(jù)，而Mock Client則輔助后端對它們的接口進(jìn)行測試.

5.6 YApi 管理工具

YApi.png

YApi使用示例截圖：

YApi預(yù)覽.png

mock配置1.png

返回?cái)?shù)據(jù)1.png