微服務(wù)接口定義規(guī)范方案

..接口定義規(guī)范研發(fā)部2018/01..TOC\o"1-3"\h\u1．URI命名規(guī)范32．使用HTTP方法表示動(dòng)作行為43．使用HTTP內(nèi)容協(xié)商處理資源表示內(nèi)容44．使用HTTP響應(yīng)狀態(tài)碼標(biāo)識(shí)處理結(jié)果狀態(tài)55．使用HAL<HypertextApplicationLanguage>作為響應(yīng)數(shù)據(jù)格式66．各HTTP方法成功處理后的返回?cái)?shù)據(jù)97．不要對(duì)返回結(jié)果進(jìn)行封裝98．支持資源的字段裁剪,減少響應(yīng)中返回的字段數(shù)量109．使用

OAuth2

來(lái)確保API的安全性1010．確保GET,PUT,DELETE請(qǐng)求是冪等的1011．API版本10..微服務(wù)接口設(shè)計(jì)采用Restful風(fēng)格的接口規(guī)范,下面是基于Restful風(fēng)格要求制訂的接口設(shè)計(jì)規(guī)范。URI命名規(guī)范不用大寫；用中杠-不用下杠_；參數(shù)列表要encode；使用名詞作為資源名稱<例如,不要在網(wǎng)址中使用動(dòng)詞>；使用資源集合的概念；每種資源有兩類URI〔接口：資源集合〔例如,/orders；集合中的單個(gè)資源〔例如,/orders/{orderId}。使用復(fù)數(shù)形式<使用‘orders’而不是‘order’>；資源名稱和ID組合可以作為一個(gè)網(wǎng)址的節(jié)點(diǎn)； 例如,/orders/{orderId}/items/{itemId}；盡可能的讓網(wǎng)址越短越好,單個(gè)網(wǎng)址最好不超過(guò)三個(gè)節(jié)點(diǎn)。 可以使用查詢參數(shù)代替路徑中的節(jié)點(diǎn)組合對(duì)Composite資源的訪問(wèn)服務(wù)器端的組合實(shí)體必須在uri中通過(guò)父實(shí)體的id導(dǎo)航訪問(wèn)。GET/orders/12/items使用有意義的資源描述；"禁止單純的使用ID!"響應(yīng)信息中不應(yīng)該存在單純的ID,應(yīng)使用鏈接 或是引用的對(duì)象；設(shè)計(jì)資源的表述信息,而不是簡(jiǎn)簡(jiǎn)單單的做數(shù)據(jù)庫(kù)表的映射；合并表述信息,不要通過(guò)兩個(gè)ID直接表示兩個(gè)表的關(guān)系；資源的集合應(yīng)支持過(guò)濾,排序和分頁(yè)；過(guò)濾、排序、分頁(yè)應(yīng)出現(xiàn)在參數(shù)列表中而不是Path中。例如：GET/currencies?page=1&size=10過(guò)濾條件應(yīng)該合并到一個(gè)參數(shù)里： GET/users?filter="name::todd|city::denver|title::grandpoobah" 排序字段也應(yīng)該合并到一個(gè)參數(shù)里,使用-代表倒序 GET/users?sort=last_name|first_name|-hire_date經(jīng)常使用的、復(fù)雜的查詢標(biāo)簽化,降低維護(hù)成本。如：GET/trades?status=closed&sort=createddesc快捷方式：GET/trades/recently-closed使用HTTP方法表示動(dòng)作行為POST-創(chuàng)建資源,非冪等性操作；PUT-更新資源；PATCH-部分更新資源；GET-獲取單個(gè)資源或資源集合；DELETE-刪除單個(gè)資源或資源集合；原則上URI中不應(yīng)該出現(xiàn)動(dòng)詞,當(dāng)出現(xiàn)復(fù)雜操作超出上述HTTP方法描述的行為時(shí),可以考慮通過(guò)URL參數(shù)來(lái)指定動(dòng)作。如PUT/books/1?action=like標(biāo)注ID為1的圖書為喜愛(ài)圖書使用其他動(dòng)作時(shí),HTTP方法仍然根據(jù)實(shí)際操作屬于那種類型設(shè)定,比如屬于資源的更新操作,那么就使用PUT方法。使用HTTP內(nèi)容協(xié)商處理資源表示內(nèi)容通過(guò)請(qǐng)求頭/響應(yīng)頭中的Content-Type判斷請(qǐng)求提中的數(shù)據(jù)類型,然后根據(jù)數(shù) 據(jù)類型做出相應(yīng)處理。請(qǐng)求Body內(nèi)容格式采用JSON格式,其格式通過(guò)HTTPHeader Content-Type:application/json表示。或From表單格式,其格式通過(guò)HTTPHeader：Content-Type:application/x-www-form-urlencoded響應(yīng)內(nèi)容格式為JSON,響應(yīng)頭Content-Type:application/json或HAL+JSON,響應(yīng)頭為Content-Type:application/hal+json或XML格式,響應(yīng)頭為Content-Type:text/xml使用HTTP響應(yīng)狀態(tài)碼標(biāo)識(shí)處理結(jié)果狀態(tài)不要發(fā)生了錯(cuò)誤但給2xx響應(yīng),客戶端可能會(huì)緩存成功的http請(qǐng)求；正確設(shè)置http狀態(tài)碼,不要自定義；下面是常用狀態(tài)碼及其意義：響應(yīng)碼說(shuō)明200OK請(qǐng)求處理正常,通常用于GET操作時(shí)內(nèi)容正常返回201CreatedPost或PUT操作時(shí)對(duì)象被正常創(chuàng)建,通常在Body中返回對(duì)象內(nèi)容。204Nocontent處理成功,但沒(méi)返回值。如delete操作,沒(méi)有內(nèi)容可返回。301Movedpermanently資源被移動(dòng)到其它位置,需要客戶端重定向。400Badrequest請(qǐng)求有問(wèn)題,可能是缺少參數(shù)或參數(shù)不正確,需要客戶端修正請(qǐng)求內(nèi)容?？梢栽谡?qǐng)求體中返回錯(cuò)誤提示信息。401Unauthorized指定資源需要授權(quán),用戶未認(rèn)證身份所以不能訪問(wèn)資源。403Forbidden用戶已登錄但是沒(méi)有指定資源的訪問(wèn)權(quán)限。404Notfound指定的資源不存在。405Methodnotallowed資源不支持訪問(wèn)方法,如對(duì)只讀資源使用PUT進(jìn)行更新409

Conflict將出現(xiàn)重復(fù)的數(shù)據(jù)或是無(wú)效的數(shù)據(jù)狀態(tài)。500Internalservererror服務(wù)器發(fā)生非預(yù)期錯(cuò)誤,此時(shí)需要在響應(yīng)體中返回錯(cuò)誤的具體信息。對(duì)于400、409、500這種需要進(jìn)一步說(shuō)明原因的錯(cuò)誤碼,可以在響應(yīng)體中返回對(duì)應(yīng)的錯(cuò)誤信息,格式如下：{code:’500’,message:'服務(wù)暫不可用,請(qǐng)稍后重試或與管理員聯(lián)系'}使用HAL<HypertextApplicationLanguage>作為響應(yīng)數(shù)據(jù)格式簡(jiǎn)單資源對(duì)象：{"_links":{"self":{"href":"/api/user/matthew"}},"id":"matthew","name":"MatthewWeierO'Phinney"}復(fù)雜資源對(duì)象：{"_links":{"self":{"href":"/api/user/matthew"}},"id":"matthew","name":"MatthewWeierO'Phinney","_embedded":{"contacts":[{"_links":{"self":{"href":"/api/user/mac_nibblet"}},"id":"mac_nibblet","name":"AntoineHedgecock"},{"_links":{"self":{"href":"/api/user/spiffyjr"}},"id":"spiffyjr","name":"KyleSpraggs"}],"website":{"_links":{"self":{"href":"/api/locations/mwop"}},"id":"mwop","url":""},}}帶有分頁(yè)的結(jié)果：{"_embedded":{"currencyLogs":[{"type":1,"coin":0.50,"usercoin":5.50,"add_time":"1504228164","expressid":0},{"type":1,"coin":0.50,"usercoin":6.00,"add_time":"1504228187","expressid":0},{"type":1,"coin":0.50,"usercoin":10.00,"add_time":"1504228349","expressid":0}]},"_links":{"first":{},"prev":{gs/group-by-day?page=0&size=10"},"self":{},"next":{page=2&size=10"},"last":{}},"page":{"size":10,"totalElements":53454,"totalPages":5346,"number":1}}各HTTP方法成功處理后的返回?cái)?shù)據(jù)HTTP方法response格式GET單個(gè)對(duì)象、集合POST新增成功的對(duì)象、或URIPUT/PATCH更新成功的對(duì)象或URIDELETE空不要對(duì)返回結(jié)果進(jìn)行封裝response的body直接就是數(shù)據(jù),不要做多余的包裝。{"type":1,"coin":24991.50,"expressid":0,"_links":{"self":{"href":"http://localhost:8011/currencies/270"}}}支持資源的字段裁剪,減少響應(yīng)中返回的字段數(shù)量使用

OAuth2

來(lái)確保API的安全性使用