基礎約定

1. 接口路徑以/api或者/[version]/api開頭

2. 接口路徑以/api/aa-bb的方式命名

3. 接口路徑使用資源的名詞而非動詞，動作應該由http method體現

4. 接口路徑中的資源使用復數而非單數

5. 接口設計面向開發接口，而非單純前端業務

6. 數據結構

   // 不分頁數據
   {
       code: 10001,
       status: 200,
       message: "請求成功",
       data: {
       	id: 1,
       	name: "data 1"
   	}
   }
   // 分頁數據
   {
       code: 10001,
       status: 200,
       message: "請求成功",
       data: {
       	items:[{
               id: 1,
               name: "data 1"
   		}, {
               id: 2,
               name: "data 2"
           }],
   		total: 2
   	}
   }
   // 其中為了code表示業務編碼，status表示http相應狀態碼，如此設計的原因時部分場景下前后端之間經歷了不可用的網關或代理，這種情況下客戶可以從status分辨業務方的處理結果，而code是為了幫助工程師定位問題，并不是必須的。

7. 請求和響應字段采用aa_bb_cc的方式命名
8. 時間字段以ISO 8601格式返回YYYY-MM-DDTHH:MM:SSZ
9. 空數組使用[]，而非null
10. http方法

    方法	場景	例如
    GET	獲取數據	獲取單個：GET /api/tasks/1、獲取列表：GET /api/tasks
    POST	創建數據	創建單個：POST /api/tasks
    PATCH	差量修改數據	修改單個：PATCH /api/tasks/1
    PUT	全量修改數據	修改單個：PUT /api/tasks/1
    DELETE	刪除數據	刪除單個：DELETE /api/tasks/1

11. http狀態碼

    狀態碼	場景
    200	創建成功，通常用在同步操作時
    202	創建成功，通常用在異步操作時，表示請求已接受，但是還沒有處理完成
    400	參數錯誤，通常用在表單參數錯誤
    401	授權錯誤，通常用在 Token 缺失或失效，注意 401 會觸發前端跳轉到登錄頁
    403	操作被拒絕，通常發生在權限不足時，注意此時務必帶上詳細錯誤信息
    404	沒有找到對象，通常發生在使用錯誤的 id 查詢詳情
    500	服務器錯誤

創建類接口

1. 創建完成后直接返回id

2. 關聯關系只以id為表示，其他字段不應依賴客戶端

   // √
   {
       user_id: [1, 2, 3]
   }
   // ×
   {
       username: [xx, xx, xx],
       user_id: [1, 2, 3],
   	...
   }

3. 參數錯誤以數組形式返回，并附帶用戶友好的提示

   {
       code: 10002,
       status: 400,
       message: "參數錯誤",
       data: {
           error: [{
               field: "name",
               message: "缺失"
           }]
       }
   }

查詢類接口

1. 排序使用sort和order

   例如使用 GET /api/tasks?sort=created_at&order=descend表示以創建時間降序查詢數據

2. 分頁使用page和per_page

   GET /api/tasks?page=1&per_page=10表示每頁10條查詢第一頁的數據

3. 普通篩選使用鍵值對，多列模糊查詢使用keyword關鍵詞，枚舉篩選使用數組合并拼接，區間使用xxx_lt和xxx_gt關鍵詞

   例如 GET /api/tasks?creator=ming 表示查詢所有 ming 用戶創建的任務

   例如 GET /api/tasks?keyword=ming 表示查詢任意列包含 ming 關鍵詞的任務

   例如 GET /api/tasks?status=pending,complete 表示查詢狀態為阻塞和完成的任務

   例如 GET /api/tasks?weight_gt=10&weight_lt=20 表示查詢權重在 10 和 20 之間的任務

   例如 GET /api/tasks?weight_gt=10 表示查詢權重大于 10 的任務

4. 可枚舉字段使用有語義英文而非無語義數字

5. 合理自然嵌套結構而不是平鋪

刪除類接口

1. 刪除接口應酌情提供批量刪除

   例如 DELETE /api/tasks?ids=1,2,3 表示批量刪除 id 為 1 或 2 或 3 的任務

圖標類接口

1. 曲線圖、柱狀圖

   {
     code: 20000,
     status: 200,
     message: "請求成功",
     data: {
       x_axis: ['2022.04.20','2022.04.21', '2022.04.22']
       series: [{
         name: '上海用戶'，
         data： [5000,4000,3000],
         color: '#f5f5f5' // 可選，如果加上的話會使用該色值
       }, {
         name: '成都用戶'，
         data： [3000,4000,5000],  // 注意，沒有數據時候也要使用 0 填充，和 x_axis 一一對應
         color: '#f5f5f5'
       }]
     }
   }

2.  餅圖

   {
     code: 20000,
     status: 200,
     message: "請求成功",
     data: {
       series: [{
         name: '上線用戶',
         value: 1890,
         color: '#f5f5f5' // 可選，如果加上的話會使用該色值
       }, {
         name: '下線用戶',
         value: 2000,
         color: '#f5f5f5'
       }]
     }
   }

文件類接口

1. 統一提供單文件上傳接口（/api/files），支持上傳所有類型文件

   // 請求，注意這里是 FormData
   {
     file: File
   }
   
   // 響應
   {
     code: 20000,
     status: 200,
     message: "上傳成功",
     data: {
       id: 'bb313c99',
       url: '/files/bb313c99.pdf'
       name: '合同.pdf' // 原文件的名稱
     }
   }

2. 統一提供多文件上傳接口（/api/multiple-files），支持上傳所有類型文件

   // 請求，注意這里是 FormData
   {
     files: [File, File]
   }
   
   // 響應
   {
     code: 20000,
     status: 200,
     message: "上傳成功",
     data: [{
       id: 'bb313c99',
       url: '/files/bb313c99.pdf'
       name: '合同1.pdf' // 原文件的名稱
     }, {
       id: 'bb313c88',
       url: '/files/bb313c88.pdf'
       name: '合同2.pdf' // 原文件的名稱
     }]
   }

3. 文件路徑至少補全至根路徑

   // 正確
   {
     code: 20000,
     status: 200,
     message: "請求成功",
     data: {
       id: 1,
       name: 'xx'
       avatar: '/files/bb313c99.png',
     }
   }
   // 錯誤
   {
     code: 20000,
     status: 200,
     message: "請求成功",
     data: {
       id: 1,
       name: 'xx'
       avatar: 'bb313c99.png'
     }
   }

4. 對于使用到文件的接口使用文件 id 或地址而非 FormData

   // 正確
   {
     name: '新任務 1',
     file_id: 'bb313c99',
     // 或
     file_url: '/files/bb313c99.pdf',
   }
   // 錯誤
   {
     name: '新任務 1',
     file: File
   }