接口規範定義評審初稿

1. 接口定義規範背景
   1.1 上週六workshop，大家統一認爲接口規範定義爲第一優先級 ，我這邊其實不希望規範太過複雜，簡單實用後期可以擴展就好 。

2. 接口協議定義
   2.1 通訊協議
   https (外部,暫時沒有實施)
   http (內部)
   Tcp （暫時沒有用到）
   2.2 請求協議
   rest本身是有他的規範的，如下
   GET：從服務器取出資源（一項或多項）。
   POST：在服務器新建一個資源。
   PUT：在服務器更新資源（客戶端提供改變後的完整資源）。
   PATCH：在服務器更新資源（客戶端提供改變的屬性）。
   DELETE：從服務器刪除資源。
   其實本身 ，互聯網公司也不一定按照這一套來 。 我們同學中有人提出 ，所有請求都用POST ，這個是我覺得值得推薦 ，這裏我建議可以統一 。
   但是有一點需要強調 ，你使用POST ，你需要在接口命名上，你需要有所體現協議，比如getOrderCount 。
   這裏我們需要在方法路徑前綴上做一個統一
   GET 對應 get
   POST 對應 create
   PUT 對應 update
   DELETE 對應 delete （邏輯刪除 非物理刪除）
   爲什麼一定要這麼做呢 ,後期可以方便數據統計有多少delete 請求 ， get 請求 ，post 請求 ，put 請求

3. 接口url定義
   3.1 子域名
   h5api.業務部門或者系統名稱.xxxx.com
   pcapi.業務部門或者系統名稱.xxxx.com
   3.2 url (外部path 和內部path )
   /pc/1.0/appname/controllerpath/methodname

下面是taobao的
https://h5api.m.taobao.com/h5/mtop.taobao.baichuan.smb.get/1.0/?jsv=2.6.0&appKey=12574478&t=1602469404220&sign=98e9c15177b5352173f8fb282d6cf2a3&api=mtop.taobao.baichuan.smb.get&v=1.0&type=originaljson&dataType=jsonp&timeout=10000

4. 接口版本定義
   接口沒有多版本需求 默認1.0 ， 有多版本需求 ，可以使用迭代版本版號或者發佈時間
5. 接口參數定義
   5.1 rest規範
   如：
   GET /zoo/v1/zoos：列出所有動物園
   POST /zoo/v1/zoos：新建一個動物園
   GET /zoo/v1/zoos/{ID}：獲取某個指定動物園的信息
   PUT /zoo/v1/zoos/{ID}：更新某個指定動物園的信息（提供該動物園的全部信息）
   PATCH /zoo/v1/zoos/{ID}：更新某個指定動物園的信息（提供該動物園的部分信息）
   DELETE /zoo/v1/zoos/{ID}：刪除某個動物園
   GET /zoo/v1/zoos/{ID}/animals：列出某個指定動物園的所有動物
   DELETE /zoo/v1/zoos/ID/animals/ID：刪除某個指定動物園的指定動物
   大部分公司沒有按照他的來。
   5.2 我們公司統一規範
   5.2.1 Header 請求頭
   header存放公共參數、requestId、token、加密字段等。不要將業務字段，往裏面放，當前公司有些沒有實現，這個不要緊，重要的是規範，功能後面可以加
   5.2.1.1 app 端 network 網絡 ， operator 運營商 ，platform 平臺 ，system 操作系統 ，device 設備型號 ， udid 唯一設備id ，requestID 請求id ，sign （驗證簽名），版本id 等

​ 5.2.1.2 pc 端 requestID 請求id （鏈路監控），sign （驗證簽名），版本id 等
5.2.2 Query Parameter or ​ Path
url?後面的參數，存放請求接口的參數數據。有同學建議把所有請求參數都已body 方式提交。 我個人建議既然協議上所有請求都是POST，沒必要放在Query Parameter or ​ Path 中
5.2.3 Request Body
5.2.3.1 content-type
1. application/json; charset=utf-8: 用於一般後端請求
2. multipart/form-data: 需要在表單中進行文件上傳時，就需要使用該格式
5.2.3.2 body 格式
本身選擇了 json ，業務同學控制比較好 。

6. 接口返回定義
   有同學提過 Response Body 不統一，下面是當前我們公司返回的response body
   {
   "code":200,
   "message":"success",
   "obj":{

   }
   }
   比較合理的格式
   {
   "code":0,
   "data":{

   },
   "error":{

   },
   "extra":{
   "cost":0.008630664,
   "request-id":"997ef1f283f4b7a67d8aea8a666c1b79@2@infoq"
   }
   }

7. 接口變更規範
   接口的提供方，在修改接口後，需要告知接口的使用方，這裏接口的提供方可能會問，我怎麼知道，有哪些調用方呢 ，怎麼告知他們呢 ，現在我們服務治理這塊做的很弱，後期會提供一些服務治理工具幫助大家 。大家先將迭代涉及變更的接口在釘釘羣裏發一下 ，同時告知對應業務線測試同學，接口變更可能涉及到的業務。

8. 接口管理工具
   會有單獨一篇文章介紹