微服務(wù)RestfulAPI的設(shè)計(jì)規(guī)范1.URIURI表示資源，資源一般對(duì)應(yīng)服務(wù)器端領(lǐng)域模型中的實(shí)體類(lèi)。URI規(guī)范不用大寫(xiě)；用中杠-不用下杠_；參數(shù)列表要encode；URI中的名詞表示資源集合，使用復(fù)數(shù)形式。資源集合vs單個(gè)資源URI表示資源的兩種方式：資源集合、單個(gè)資源。資源集合：/zoos//所有動(dòng)物園/zoos/1/animals//id為1的動(dòng)物園中的所有動(dòng)物單個(gè)資源：/zoos/1//id為1的動(dòng)物園/zoos/1;2;3//id為1，2，3的動(dòng)物園避免層級(jí)過(guò)深的URI/在url中表達(dá)層級(jí)，用于按實(shí)體關(guān)聯(lián)關(guān)系進(jìn)行對(duì)象導(dǎo)航，一般根據(jù)id導(dǎo)航。過(guò)深的導(dǎo)航容易導(dǎo)致url膨脹，不易維護(hù)，如

GET/zoos/1/areas/3/animals/4，盡量使用查詢(xún)參數(shù)代替路徑中的實(shí)體導(dǎo)航，如GET/animals?zoo=1&area=3；對(duì)Composite資源的訪(fǎng)問(wèn)服務(wù)器端的組合實(shí)體必須在uri中通過(guò)父實(shí)體的id導(dǎo)航訪(fǎng)問(wèn)。組合實(shí)體不是first-class的實(shí)體，它的生命周期完全依賴(lài)父實(shí)體，無(wú)法獨(dú)立存在，在實(shí)現(xiàn)上通常是對(duì)數(shù)據(jù)庫(kù)表中某些列的抽象，不直接對(duì)應(yīng)表，也無(wú)id。一個(gè)常見(jiàn)的例子是User—Address，Address是對(duì)User表中zipCode/country/city三個(gè)字段的簡(jiǎn)單抽象，無(wú)法獨(dú)立于User存在。必須通過(guò)User索引到Address：GET/user/1/addresses2.RequestHTTP方法通過(guò)標(biāo)準(zhǔn)HTTP方法對(duì)資源CRUD：GET：查詢(xún)GET/zoosGET/zoos/1GET/zoos/1/employeesPOST：創(chuàng)建單個(gè)資源。POST一般向“資源集合”型uri發(fā)起POST/animals//新增動(dòng)物POST/zoos/1/employees//為id為1的動(dòng)物園雇傭員工PUT：更新單個(gè)資源（全量），客戶(hù)端提供完整的更新后的資源。與之對(duì)應(yīng)的是PATCH，PATCH負(fù)責(zé)部分更新，客戶(hù)端提供要更新的那些字段。PUT/PATCH一般向“單個(gè)資源”型uri發(fā)起PUT/animals/1PUT/zoos/1DELETE：刪除DELETE/zoos/1/employees/2DELETE/zoos/1/employees/2;4;5DELETE/zoos/1/animals//刪除id為1的動(dòng)物園內(nèi)的所有動(dòng)物HEAD/OPTION用的不多，就不多解釋了。安全性和冪等性安全性：不會(huì)改變資源狀態(tài)，可以理解為只讀的；冪等性：執(zhí)行1次和執(zhí)行N次，對(duì)資源狀態(tài)改變的效果是等價(jià)的。.安全性?xún)绲刃訥ET√√POST××PUT×√DELETE×√安全性和冪等性均不保證反復(fù)請(qǐng)求能拿到相同的response。以DELETE為例，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是允許的。復(fù)雜查詢(xún)查詢(xún)可以捎帶以下參數(shù)：.示例備注過(guò)濾條件?type=1&age=16允許一定的uri冗余，如/zoos/1與/zoos?id=1排序?sort=age,desc

投影?whitelist=id,name,email

分頁(yè)?limit=10&offset=3

Bookmarker經(jīng)常使用的、復(fù)雜的查詢(xún)標(biāo)簽化，降低維護(hù)成本。如：GET/trades?status=closed&sort=created,desc快捷方式：GET/trades#recently-closed或者GET/trades/recently-closedFormat只用以下常見(jiàn)的3種bodyformat：Content-Type:application/jsonPOST/v1/animalHTTP/1.1Host:Accept:application/jsonContent-Type:application/jsonContent-Length:24{"name":"Gir","animalType":"12"}Content-Type:application/x-www-form-urlencoded

(瀏覽器POST表單用的格式)POST/loginHTTP/1.1Host:Content-Length:31Accept:text/htmlContent-Type:application/x-www-form-urlencodedusername=root&password=Zion0101Content-Type:multipart/form-data;boundary=—-RANDOM_jDMUxq4Ot5

(表單有文件上傳時(shí)的格式)ContentNegotiation資源可以有多種表示方式，如json、xml、pdf、excel等等，客戶(hù)端可以指定自己期望的格式，通常有兩種方式：httpheader

Accept：Accept:application/xml;q=0.6,application/atom+xml;q=1.0q為各項(xiàng)格式的偏好程度url中加文件后綴：/zoo/1.json6.Response不要包裝：

response的body直接就是數(shù)據(jù)，不要做多余的包裝。錯(cuò)誤示例：{"success":true,"data":{"id":1,"name":"xiaotuan"},}各HTTP方法成功處理后的數(shù)據(jù)格式：·response格式GET單個(gè)對(duì)象、集合POST新增成功的對(duì)象PUT/PATCH更新成功的對(duì)象DELETE空json格式的約定：時(shí)間用長(zhǎng)整形(毫秒數(shù))，客戶(hù)端自己按需解析（\t"/yue7603835/article/details/_blank"moment.js）不傳null字段分頁(yè)response{"paging":{"limit":10,"offset":0,"total":729},"data":[{},{},{}...]}7.錯(cuò)誤處理不要發(fā)生了錯(cuò)誤但給2xx響應(yīng)，客戶(hù)端可能會(huì)緩存成功的http請(qǐng)求；正確設(shè)置http狀態(tài)碼，不要自定義；Responsebody提供1)錯(cuò)誤的代碼（日志/問(wèn)題追查）；2)錯(cuò)誤的描述文本（展示給用戶(hù)）。對(duì)第三點(diǎn)的實(shí)現(xiàn)稍微多說(shuō)一點(diǎn)：Java服務(wù)器端一般用異常表示RESTfulAPI的錯(cuò)誤。API可能拋出兩類(lèi)異常：業(yè)務(wù)異常和非業(yè)務(wù)異常。業(yè)務(wù)異常由自己的業(yè)務(wù)代碼拋出，表示一個(gè)用例的前置條件不滿(mǎn)足、業(yè)務(wù)規(guī)則沖突等，比如參數(shù)校驗(yàn)不通過(guò)、權(quán)限校驗(yàn)失敗。非業(yè)務(wù)類(lèi)異常表示不在預(yù)期內(nèi)的問(wèn)題，通常由類(lèi)庫(kù)、框架拋出，或由于自己的代碼邏輯錯(cuò)誤導(dǎo)致，比如數(shù)據(jù)庫(kù)連接失敗、空指針異常、除0錯(cuò)誤等等。業(yè)務(wù)類(lèi)異常必須提供2種信息：如果拋出該類(lèi)異常，HTTP響應(yīng)狀態(tài)碼應(yīng)該設(shè)成什么；異常的文本描述；在Controller層使用統(tǒng)一的異常攔截器：設(shè)置HTTP響應(yīng)狀態(tài)碼：對(duì)業(yè)務(wù)類(lèi)異常，用它指定的HTTPcode；對(duì)非業(yè)務(wù)類(lèi)異常，統(tǒng)一500；ResponseBody的錯(cuò)誤碼：異常類(lèi)名ResponseBody的錯(cuò)誤描述：對(duì)業(yè)務(wù)類(lèi)異常，用它指定的錯(cuò)誤文本；對(duì)非業(yè)務(wù)類(lèi)異常，線(xiàn)上可以統(tǒng)一文案如“服務(wù)器端錯(cuò)誤，請(qǐng)稍后再試”，開(kāi)發(fā)或測(cè)試環(huán)境中用異常的stacktrace，服務(wù)器端提供該行為的開(kāi)關(guān)。常用的http狀態(tài)碼及使用場(chǎng)景：狀態(tài)碼使用場(chǎng)景400常用在參數(shù)校驗(yàn)401未經(jīng)驗(yàn)證的用戶(hù)，常見(jiàn)于未登錄。如果經(jīng)過(guò)驗(yàn)證后依然沒(méi)權(quán)限，應(yīng)該403（即authentication和authorization的區(qū)別）。403無(wú)權(quán)限404資源不存在500非業(yè)務(wù)類(lèi)異常503由容器拋出，自己的代碼不要拋這個(gè)異常8.服務(wù)型資源除了資源簡(jiǎn)單的CRUD，服務(wù)器端經(jīng)常還會(huì)提供其他服務(wù)，這些服務(wù)無(wú)法直接用上面提到的URI映射。如：按關(guān)鍵字搜索；計(jì)算地球上兩點(diǎn)間的距離；批量向用戶(hù)推送消息可以把這些服務(wù)看成資源，計(jì)算的結(jié)果是資源的presentation，按服務(wù)屬性選擇合適的HTTP方法。例：GET/search?q=filter?category=file搜索GET/distance-calc?lats=47.480&lngs=-122.389&late=37.108&lnge=-122.448POST/batch-publish-msg[{"from":0,"to":1,"text":"abc"},{},{}...]9.異步任務(wù)對(duì)耗時(shí)的異步任務(wù)，服務(wù)器端接受客戶(hù)端傳遞的參數(shù)后，應(yīng)返回創(chuàng)建成功的任務(wù)資源，其中包含了任務(wù)的執(zhí)行狀態(tài)?？蛻?hù)端可以輪訓(xùn)該任務(wù)獲得最新的執(zhí)行進(jìn)度。提交任務(wù)：POST/batch-publish-msg[{"from":0,"to":1,"text":"abc"},{},{}...]返回：{"taskId":3,"createBy":"Anonymous","status":"running"}GET/task/3{"taskId":3,"createBy":"Anonymous","status":"success"}如果任務(wù)的執(zhí)行狀態(tài)包括較多信息，可以把“執(zhí)行狀態(tài)”抽象成組合資源，客戶(hù)端查詢(xún)?cè)摖顟B(tài)資源了解任務(wù)的執(zhí)行情況。提交任務(wù)：POST/batch-publish-msg[{"from":0,"to":1,"text":"abc"},{},{}...]返回：{"taskId":3,"createBy":"Anonymous"}GET/task/3/status{"progress":"50%","total":18,"success":8,"fail":1}1