因為是接口框架，首先要做的就是制定接口規(guī)范，好的接口規(guī)范能約束開發(fā)人員虫给，能降低前后端人員之間的溝通協(xié)調(diào)，能避免后期聯(lián)調(diào)帶來的一系列問題侠碧。
1.接口規(guī)范
接口規(guī)范包含以下內(nèi)容：
1抹估、請求類型及參數(shù)
2、返回值及返回碼
3弄兜、權(quán)限及版本控制
4药蜻、接口示例
2.接口請求說明
Api使用Restful風(fēng)格，接口地址（測試）：http://host:port
（接口描述中地址需要擴展自此地址替饿，如/api/users/register语泽，擴展后則為 http://host:port/api/users/register）
接口請求類型分為兩種，GET和POST视卢，GET通常為請求獲取資源踱卵；POST通常為提交資源到服務(wù)器；
接口請求返回值基本分為兩種：
GET的請求若無錯誤据过，則返回所需資源的JSON格式內(nèi)容惋砂，若有錯誤則返回一致的JSON格式內(nèi)容，如：{“success”:false, “message”: “提交的參數(shù)不正確”, data: {}}绳锅，其中data為額外的對象西饵，具體值根據(jù)接口而定；
POST的請求的Body部分可以將對象格式化為JSON的字符串后提交榨呆，也可以使用傳統(tǒng)的Form表單形式提交， 返回一致的JSON格式內(nèi)容：如：{“success”:true, “message”: null, data: {id:1}}庸队，其中data的內(nèi)容也是具體根據(jù)接口而定积蜻。
返回碼說明：
- 200 請求成功
- 400 客戶端請求時所提交的參數(shù)不正確（通常為客戶端的問題）
- 401 未提供accessToken（即未登錄）
- 403 權(quán)限不足（已登錄，但不具有訪問該資源的權(quán)限）
- 404 找不到該資源（通常為請求的地址不正確）
- 500 服務(wù)發(fā)生錯誤（通常為服務(wù)端的問題）
實際生產(chǎn)中彻消，請求基本都為POST
3.接口權(quán)限說明
接口權(quán)限驗證使用OAUTH2.0標(biāo)準(zhǔn)竿拆，即先請求授權(quán)服務(wù)獲取accessToken，得到accessToken后使用其內(nèi)容封裝到request的頭（Headers）中宾尚，用以請求被保護的資源丙笋；
accessToken封裝在Headers中是以Authorization鍵值對形式組成的谢澈，如：accessToken為4cac113f-29b1-4585-99a8-16e39331ccb3，封裝的內(nèi)容為：Authorization: 4cac113f-29b1-4585-99a8-16e39331ccb3這種形式御板。
4.接口請求版本說明
各個接口在header里面都加Version字段锥忿，用于控制接口的版本，服務(wù)端程序可以根據(jù)版本號來動態(tài)返回數(shù)據(jù)怠肋，也可以根據(jù)版本號來提示app升級敬鬓。不加version默認(rèn)1.0。
5.公共返回碼
為了保證接口的規(guī)范性笙各，特制定標(biāo)準(zhǔn)返回碼：
成功類：
- 10001 保存成功
- 10002 刪除成功
- 10003 操作成功
- 10004 審核成功
失敗類
- 20001 操作失敗
- 20002 代碼已存在
- 30001 無權(quán)限
- 30002 系統(tǒng)錯誤
- 30003 參數(shù)錯誤
- 30004 路徑不存在
5.接口示例
上述是登錄接口的文檔標(biāo)識
總結(jié)
設(shè)計接口規(guī)范是一個相當(dāng)復(fù)雜的事情钉答，要綜合考慮很多技術(shù)及實現(xiàn)細(xì)節(jié)。后續(xù)章節(jié)依次講述這些細(xì)節(jié)杈抢，并不斷完善規(guī)范文檔数尿。
